xerogolang

README

xerogolang (deprecated as of April 2021)

Looking for OAuth 2.0?

This repository xerogolang was hand written for use with OAuth1.0a. For OAuth 2, we've moved to building next generation SDKs in an automated fashion using OpenAPI specifications.

OAuth 1.0a was officially deprecated on March 31, 2021. We've made the decision to archive xerogolang and not update to OAuth 2 as this is not inline with our strategy to automate the creation of them from OpenAPI specs.

Our official Golang OAuth2 SDK is development is on hold until we secure resources to get the code to MVP status.

In the meantime, we do have a golang example project that can help you authenticate and roll your own API calls without a full blown SDK.

https://github.com/XeroAPI/golang-oauth2-example

What about updating xerogolang to OAuth 2.0?

We are devoting resources towards building and improving our new OAuth 2.0 SDKs which don't share a code base with this library. For those using xerogolang, you have the option of forking this repository and modifying it for future use.

This is the Xero Golang SDK for the Xero API.

Currently it only supports the Accounting API.

Xero App

You'll need to decide which type of Xero app you'll be building Private, Public, or Partner. Go to http://app.xero.com and login with your Xero user account to create an app.

Download Xero Golang SDK

Download the SDK using the following command:

$ go get github.com/XeroAPI/xerogolang

Configure

The Xero Golang SDK is easily configured using environment variables to configure values unique to your Application.

The following values need to be set:

XERO_KEY=Your_Consumer_Key
XERO_SECRET=Your_Consumer_Secret
XERO_USER_AGENT=Your_application_name

Find the Consumer_Key and Consumer_Secret you want to use at developer.xero.com under My Apps > Select App > OAuth Credentials.

You must also set a method - this must be either "public", "private", or "partner"

XERO_METHOD=public_private_or_partner

If you are using the "private" or "partner" method you'll also need a Private key path:

XERO_PRIVATE_KEY_PATH=/Path/to/your/privatekey.pem

We include an Example App (in this repo) built using Gorilla.

Example App

This repo includes an Example App mentioned above. The app contains examples of most of the functions available via the API.

To run the example app do the following:

$ cd xerogolang/example
$ go get -v
$ go build
$ ./example

Now open up your browser and go to http://localhost:3000 to see the example.

The example app uses a filesystem store for sessions - you will need to implement your own store when using this SDK within your own app. We recommend Gorilla Sessions

Data Endpoints

The Xero Golang SDK contains the Accounting package which has helper methods to perform (Create, Find, Update and Remove) actions on each endpoints and structs of each endpoint's response. If an endpoint does not have one of the methods then that method is not available on the endpoint. E.g. Branding Themes can only use Find methods because you cannot Create, Update, or Remove them via the API.

Create

Create can be called on structs that have been populated with data:

c := &Contacts{
  Contacts: []Contact{
    Contact{
      Name: "Cosmo Kramer",
    },
  },
}
r, err := c.Create(provider, session)

Find

Find is called either to get a single entity given an id:

i, err := accounting.FindInvoice(provider, session, id)

all entities from an endpoint:

i, err = accounting.FindInvoices(provider, session, nil)

all entities from an endpoint since a specific time:

i, err = accounting.FindInvoicesModifiedSince(provider, session, time.Now().Add(-24*time.Hour), nil)

all entities from an endpoint using paging:

querystringParameters := map[string]string{
  "page": 1,
}

i, err = accounting.FindInvoices(provider, session, querystringParameters)

all entities from an endpoint that match a given where clause:

querystringParameters := map[string]string{
  "where": "Contact.Name==\"Vanderlay Industries\"",
}

i, err = accounting.FindInvoices(provider, session, querystringParameters)

all entities from an endpoint in a particular order:

querystringParameters := map[string]string{
  "order": "DueDate",
}

i, err = accounting.FindInvoices(provider, session, querystringParameters)

all entities from an endpoint using a filter:

querystringParameters := map[string]string{
  "Statuses": "DRAFT,SUBMITTED",
}

i, err = accounting.FindInvoices(provider, session, querystringParameters)

a combination of all of the above:

querystringParameters := map[string]string{
  "page": 1,
  "where": "Contact.Name==\"Vanderlay Industries\"",
  "order": "DueDate",
  "Statuses": "DRAFT,SUBMITTED",
}

i, err = accounting.FindInvoicesModifiedSince(provider, session, time.Now().Add(-24*time.Hour), querystringParameters)

Update

Update can be called on a struct containing the data to update. You can only update one entity at a time though.

a, err := accounts.Update(provider, session)

Remove

Remove can be called to remove an entity if you provide an ID - it is not provided on all endpoints though.

t, err := RemoveTrackingCategory(provider, session, "trackingCategoryID")

Acknowledgement

The Xero golang SDK is extended from the great oauth work done by markbates' Goth and mrjones' oauth. We have added support for Xero a provider directly in goth as well so if for some reason you don't want models and methods you can use goth directly.

The gorilla web toolkit is used throughout this SDK and comes highly recommended.

License

This software is published under the MIT License.

Copyright (c) 2016 Xero Limited

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Documentation

Index

• type Organisation
• type OrganisationCollection
• type Provider
  • func New(clientKey, secret, callbackURL string) *Provider
  • func NewCustomHTTPClient(clientKey, secret, callbackURL string, httpClient *http.Client) *Provider
  • func NewNoEnviro(clientKey, secret, callbackURL, userAgent, xeroMethod string, ...) *Provider
  • func (p *Provider) BeginAuth(state string) (goth.Session, error)
  • func (p *Provider) Client() *http.Client
  • func (p *Provider) Create(session goth.Session, endpoint string, additionalHeaders map[string]string, ...) ([]byte, error)
  • func (p *Provider) Debug(debug bool)
  • func (p *Provider) FetchUser(session goth.Session) (goth.User, error)
  • func (p *Provider) Find(session goth.Session, endpoint string, additionalHeaders map[string]string, ...) ([]byte, error)
  • func (p *Provider) GetSessionFromStore(request *http.Request, response http.ResponseWriter) (goth.Session, error)
  • func (p *Provider) Name() string
  • func (p *Provider) RefreshOAuth1Token(session *Session) error
  • func (p *Provider) RefreshToken(refreshToken string) (*oauth2.Token, error)
  • func (p *Provider) RefreshTokenAvailable() bool
  • func (p *Provider) Remove(session goth.Session, endpoint string, additionalHeaders map[string]string) ([]byte, error)
  • func (p *Provider) SetName(name string)
  • func (p *Provider) UnmarshalSession(data string) (goth.Session, error)
  • func (p *Provider) Update(session goth.Session, endpoint string, additionalHeaders map[string]string, ...) ([]byte, error)
• type Session
  • func (s *Session) Authorize(provider goth.Provider, params goth.Params) (string, error)
  • func (s Session) GetAuthURL() (string, error)
  • func (s Session) Marshal() string
  • func (s Session) String() string

Types

type Organisation

type Organisation struct {
	// Display name of organisation shown in Xero
	Name string `json:"Name,omitempty"`

	// Organisation name shown on Reports
	LegalName string `json:"LegalName,omitempty"`

	// Organisation Type
	OrganisationType string `json:"OrganisationType,omitempty"`

	// Country code for organisation. See ISO 3166-2 Country Codes
	CountryCode string `json:"CountryCode,omitempty"`

	// A unique identifier for the organisation.
	ShortCode string `json:"ShortCode,omitempty"`
}

Organisation is the expected response from the Organisation endpoint - this is not a complete schema and should only be used by FetchUser

type OrganisationCollection

type OrganisationCollection struct {
	Organisations []Organisation `json:"Organisations,omitempty"`
}

OrganisationCollection is the Total response from the Xero API

type Provider

type Provider struct {
	ClientKey       string
	Secret          string
	CallbackURL     string
	HTTPClient      *http.Client
	Method          string
	UserAgentString string
	PrivateKey      string
	// contains filtered or unexported fields
}

Provider is the implementation of `goth.Provider` for accessing Xero.

func New

func New(clientKey, secret, callbackURL string) *Provider

New creates a new Xero provider, and sets up important connection details. You should always call `xero.New` to get a new Provider. Never try to create one manually.

func NewCustomHTTPClient

func NewCustomHTTPClient(clientKey, secret, callbackURL string, httpClient *http.Client) *Provider

New creates a new Xero provider, with a custom http client

func NewNoEnviro

func NewNoEnviro(clientKey, secret, callbackURL, userAgent, xeroMethod string, privateKey []byte) *Provider

NewNoEnviro creates a new Xero provider without using the environmental set variables , and sets up important connection details. You should always call `xero.New` to get a new Provider. Never try to create one manually.

func (*Provider) BeginAuth

func (p *Provider) BeginAuth(state string) (goth.Session, error)

BeginAuth asks Xero for an authentication end-point and a request token for a session. Xero does not support the "state" variable.

func (*Provider) Client

func (p *Provider) Client() *http.Client

Client does pretty much everything

func (*Provider) Create

func (p *Provider) Create(session goth.Session, endpoint string, additionalHeaders map[string]string, body []byte) ([]byte, error)

Create sends data to an endpoint and returns a response to be unmarshaled into the appropriate data type

func (*Provider) Debug

func (p *Provider) Debug(debug bool)

Debug sets the logging of the OAuth client to verbose.

func (*Provider) FetchUser

func (p *Provider) FetchUser(session goth.Session) (goth.User, error)

FetchUser will go to Xero and access basic information about the user.

func (*Provider) Find

func (p *Provider) Find(session goth.Session, endpoint string, additionalHeaders map[string]string, querystringParameters map[string]string) ([]byte, error)

Find retrieves the requested data from an endpoint to be unmarshaled into the appropriate data type

func (*Provider) GetSessionFromStore

func (p *Provider) GetSessionFromStore(request *http.Request, response http.ResponseWriter) (goth.Session, error)

GetSessionFromStore returns a session for a given a request and a response This is an exaple of how you could get a session from a store - as long as you're supplying a goth.Session to the interactors it will work though so feel free to use your own method

func (*Provider) Name

func (p *Provider) Name() string

Name is the name used to retrieve this provider later.

func (*Provider) RefreshOAuth1Token

func (p *Provider) RefreshOAuth1Token(session *Session) error

RefreshOAuth1Token should be used instead of RefeshToken which is not compliant with the Oauth1.0a standard

func (*Provider) RefreshToken

func (p *Provider) RefreshToken(refreshToken string) (*oauth2.Token, error)

RefreshToken refresh token is not provided by the Xero Public or Private Application - only the Partner Application and you must use RefreshOAuth1Token instead

func (*Provider) RefreshTokenAvailable

func (p *Provider) RefreshTokenAvailable() bool

RefreshTokenAvailable refresh token is not provided by the Xero Public or Private Application - only the Partner Application and you must use RefreshOAuth1Token instead

func (*Provider) Remove

func (p *Provider) Remove(session goth.Session, endpoint string, additionalHeaders map[string]string) ([]byte, error)

Remove deletes the specified data from an endpoint

func (*Provider) SetName

func (p *Provider) SetName(name string)

SetName is to update the name of the provider (needed in case of multiple providers of 1 type)

func (*Provider) UnmarshalSession

func (p *Provider) UnmarshalSession(data string) (goth.Session, error)

UnmarshalSession will unmarshal a JSON string into a session.

func (*Provider) Update

func (p *Provider) Update(session goth.Session, endpoint string, additionalHeaders map[string]string, body []byte) ([]byte, error)

Update sends data to an endpoint and returns a response to be unmarshaled into the appropriate data type

type Session

type Session struct {
	AuthURL            string
	AccessToken        *oauth.AccessToken
	RequestToken       *oauth.RequestToken
	AccessTokenExpires time.Time
}

Session stores data during the auth process with Xero.

func (*Session) Authorize

func (s *Session) Authorize(provider goth.Provider, params goth.Params) (string, error)

Authorize the session with Xero and return the access token to be stored for future use.

func (Session) GetAuthURL

func (s Session) GetAuthURL() (string, error)

GetAuthURL will return the URL set by calling the `BeginAuth` function on the Xero provider.

func (Session) Marshal

func (s Session) Marshal() string

Marshal the session into a string

func (Session) String

func (s Session) String() string