hubspot

package module
v0.1.0-alpha Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 30, 2019 License: MIT Imports: 11 Imported by: 0

README

Hubspot SDK for Go

GoDoc

This library serves as a simple SDK for the Hubspot API. The existing solutions did not meet our needs, so we decided to roll our own. We do not currently implement the entire API (as that is a lot) so PRs are always welcome.

Warning

This SDK is not yet ready for production use and is under active development. If you would like to assist, feel free, but know that it is actively changing and should not currently be used for any real application.

NOTE This SDK exists as a temporary solution until an official SDK is released from Hubspot or a community-standard SDK is developed.

Installing

You can simply install the package:

go get github.com/getwagz/hubspot-sdk

Or if you are using dep:

dep ensure -add github.com/getwagz/hubspot-sdk

Usage

First, there are some optional environment variables (with hopefully sane defaults):

HUBSPOT_SDK_ENV is the environment the SDK is running in; defaults to development

HUBSPOT_SDK_ROOT_URL is the root URL for the Hubspot service, defaults to https://api.hubapi.com

HUBSPOT_SDK_LOGGING will toggle logging on if not blank and not off, false, or no

HUBSPOT_SDK_API_KEY is the api key for your account; defaults to demo

HUBSPOT_SDK_APPLICATION_ID is the oAuth application ID; this is not required for all functionality but is required for complete non-mocked testing and calls requiring oAuth

HUBSPOT_SDK_USER_ID is the oAuth userID for the developer account; this is not required for all functionality but is required for complete non-mocked testing and calls requiring oAuth

HUBSPOT_SDK_CLIENT_ID is the oAuth client ID for the developer account; this is not required for all functionality but is required for complete non-mocked testing and calls requiring oAuth

HUBSPOT_SDK_CLIENT_SECRET is the oAuth client secret key for the developer account; this is not required for all functionality but is required for complete non-mocked testing and calls requiring oAuth

HUBSPOT_SDK_OAUTH_REFRESH_TOKEN is the oAuth refresh token for the developer account; this is not required for all functionality but is required for complete non-mocked testing and calls requiring oAuth

OAuth

Many calls (for example, events on the timeline) require an oAuth token to complete. This requires setting up an account on the Hubspot Developer portal and then providing the correct environment variables. On init(), a request is made to get a new access token based upon the refresh token. If this fails, a log with level error is raised. HOWEVER we will not panic just because we cannot talk to the Hubspot API Server. We will attempt to refresh the token upon expiry.

Given that the API calls requiring oAuth will be mocked if these tokens are not provided, it is VERY important that you consider testing this API with the proper oAuth tokens to ensure the communication is correct. We are not responsible for a failure to test in your specific environment!

Testing

Please note that testing without changing environment variables will only be able to test some aspects of the API; the demo api key for the HUBSPOT_SDK_API_KEY will allow testing Contacts but not Events, which require an oAuth application. If testing those is important to you, you should use a dummy account and pass in the information as appropriate in the environment.

To run the tests, run

go test

For coverage in HTML format, run

go test -coverprofile=coverage.out && go tool cover -html=coverage.out

The coverage is notably lower than ideal, which may cause concerns. However, most of the uncovered calls would be calls directly to the Hubspot API, which we cannot easily mock in success conditions, that are malformed. Feel free to check the results of the coverage report to see what exactly isn't covered and make a determination if that is acceptable to you.

Contributing

Pull Requests are welcome! See our CONTRIBUTING.md file for more information.

Third-party Libraries

The following libraries are used in this project. We thank the creators and maintainers for making our lives easier!

Resty

Logrus

Testify

Mapstructure

Endpoints Implemented

  • Contacts
    • Create or Update Docs
    • Delete Doc
    • Get by Email Doc
  • Events
    • Create Event Type Doc
    • Delete Event Type Doc
    • Create Event on Timeline Doc

TODO

  • Clean up any TODO: in the comments of the source
  • Convert to Go Modules
  • Improve Documentation
  • Add more end points
    • Engagements Doc

Documentation

Index

Constants

View Source 
const (
	EndpointCreateContact = "endpointCreateContact"
	EndpointGetContact    = "endpointGetContact"
	EndpointDeleteContact = "endpointDeleteContact"

	EndpointCreateEventType = "endpointCreateEventType"
	EndpointDeleteEventType = "endpointDeleteEventType"
	EndpointCreateEvent     = "endpointCreateEvent"
)

Endpoints represent specific calls to the Hubspot API and some meta data about them. These should largely be ignored by the consumer of the API

View Source 
const (
	CodeContactCouldNotBeCreated = "the contact could not be created at hubspot; you should check the Message field"
	CodeContactNoEmail           = "you failed to specify an email for that contact"
	CodeContactNotFound          = "contact could not be found"
	CodeContactVIDZero           = "the contact VID cannot be 0 for this action"

	CodeEventTypeCouldNotBeCreated = "the event type could not be created"
	CodeEventTypeMissingData       = "the input is missing required information"
	CodeEventTypeCouldNotBeDeleted = "that event type could not be deleted"

	CodeEventCouldNotBeCreated = "the event could not be created"
	CodeEventMissingData       = "the input is missing required information"

	CodeGeneralError = "a general error occurred"
)

System codes are used to convey specific statuses in return objects

Variables

This section is empty.

Functions

func CreateNewEventType 

func CreateNewEventType(input *EventType) error

CreateNewEventType creates a new event type for events on the timeline

API Doc: https://developers.hubspot.com/docs/methods/timeline/create-event-type

func CreateOrUpdateContact 

func CreateOrUpdateContact(contact *Contact) error

CreateOrUpdateContact creates or updates a contact using an email address and additional properties. If the VID is 0, it is assumed that the user has not been created or updated yet.

API Doc: https://developers.hubspot.com/docs/methods/contacts/create_or_update

func CreateOrUpdateEvent 

func CreateOrUpdateEvent(input *Event) error

CreateOrUpdateEvent creates or update an event on the timeline. The ID should be provided externally. If it isn't, this func will generate a random ID based upon the current timestamp. This returns no data since the return header is a 204

API Doc: https://developers.hubspot.com/docs/methods/timeline/create-or-update-event

func DeleteContactByVID 

func DeleteContactByVID(vid int64) error

DeleteContactByVID deletes a single contact by it's VID

API Doc: https://developers.hubspot.com/docs/methods/contacts/delete_contact

func DeleteEventTypeByID 

func DeleteEventTypeByID(eventTypeID int64) error

DeleteEventTypeByID deletes an event type by the id

API Doc: https://developers.hubspot.com/docs/methods/timeline/delete-event-type

Types

type APIError 

type APIError struct {
	HTTPCode   int
	SystemCode string
	Message    string
	Body       *map[string]interface{}
}

APIError is the error struct containing additional information regarding the error that occurred. The HTTPCode is the returned value from Hubspot OR a 400 if there was an error prior to calling Hubspot. The SystemCode is a constant and you can check systemCodes.go for more information.

func (APIError) Error 

func (e APIError) Error() string

type APIReturn 

type APIReturn struct {
	HTTPCode int
	Body     interface{}
}

APIReturn represents a successful API return value, with the HTTPCode representing the exact returned HTTP Code and the Body representing the returned body

type ConfigStruct 

type ConfigStruct struct {
	Environment   string
	RootURL       string
	HubspotAPIKey string
	Logging       bool
	// Certain API endpoints require an OAuth application; those are specified here
	HubspotApplicationID     string
	HubspotUserID            string
	HubspotClientID          string
	HubspotClientSecret      string
	HubSpotOAuthRefreshToken string
}

ConfigStruct holds the various configuration options 

var Config *ConfigStruct

Config is the global configuration object that holds global configuration settings

func ConfigSetup 

func ConfigSetup() *ConfigStruct

ConfigSetup sets up the config struct with data from the environment

type Contact 

type Contact struct {
	VID                  int64
	Email                string
	FirstName            string
	LastName             string
	Website              string
	Company              string
	Phone                string
	Address              string
	City                 string
	State                string
	Zip                  string
	AdditionalProperties *[]ContactProperty
}

Contact is an individual person that you would like to create or update in Hubspot. Email is the only required field. By default, the VID field will be 0. After a create call, the VID will be filled in for you. Additional porperties are tricky

func GetContactByEmail 

func GetContactByEmail(email string) (Contact, error)

GetContactByEmail gets a single contact by their email address

API Doc: https://developers.hubspot.com/docs/methods/contacts/get_contact_by_email

type ContactProperty 

type ContactProperty struct {
	Property string `json:"property"`
	Value    string `json:"value"`
}

type Event 

type Event struct {
	ID string `json:"id"`
	// The VID of the contact
	ObjectID       int64              `json:"objectId"`
	EventTypeID    int64              `json:"eventTypeId"`
	ExtraData      *map[string]string `json:"extraData,omitempty"`
	TimelineIFrame *EventIFrame       `json:"timelineIFrame,omitempty"`
}

Event represents a timeline event

type EventIFrame 

type EventIFrame struct {
	LinkLabel   string `json:"linkLabel"`
	IFrameLabel string `json:"iframeLabel"`
	IFrameURI   string `json:"iframeUri"`
	Width       int    `json:"width"`
	Height      int    `json:"height"`
}

EventIFrame represent an event IFrame which will open an iframe in the display of the timeline event. All fields are needed.

type EventType 

type EventType struct {
	ID   int64  `json:"id,omitempty"`
	Name string `json:"name"`
	// HeaderTemplate is used when displaying the event in the timeline and uses Handlebars.js templating
	HeaderTemplate string `json:"headerTemplate"`
	// DetailTemplate is used when displaying the event in the timeline and uses Handlebars.js templating
	DetailTemplate string `json:"detailTemplate"`
	ApplicationID  string `json:"applicationId"`
	// ObjectType should be one of `CONTACT` `COMPANY` `DEAL`
	ObjectType string `json:"objectType"`
}

EventType represents an event type used for adding events to the timeline

type OAuthResponse 

type OAuthResponse struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	ExpiresIn    int    `json:"expires_in"`
	TokenType    string `json:"token_type"`
}

OAuthResponse represents the oAuth response when trying to refresh a token

type OAuthToken 

type OAuthToken struct {
	RefreshToken string
	AccessToken  string
	ExpiresIn    int
}

OAuthToken represents a current oAuth token for accessing calls requiring oAuth

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.