expensify

README

lukasmalkmus/expensify-go

An Expensify API client. - by Lukas Malkmus

---

Table of Contents

1. Introduction
2. Usage
3. Contributing
4. License

Introduction

expensify-go is an opinionated client library for the Expensify API. I created it in order to add expenses which makes it the only method currently supported.

Usage

Installation

go get github.com/lukasmalkmus/expensify-go

Usage

// Get credentials from https://www.expensify.com/tools/integrations.
client, err := expensify.NewClient("XXX-REPLACE-ME-XXX", "XXX-REPLACE-ME-XXX")
if err != nil {
    // Handle error!
}

expense := &expensify.Expense{
    Merchant: "Apple Inc.",
    Created:  expensify.NewTime(time.Now()),
    Amount:   99,
    Currency: "USD",
}

res, err := client.Expense.Create(context.TODO(), "you@example.com", []*expensify.Expense{exp})
if err != nil {
    // Handle error!
}

fmt.Println(res[0].TransactionID)

Contributing

Feel free to submit PRs or to fill Issues. Every kind of help is appreciated.

License

© Lukas Malkmus, 2020

Distributed under MIT License (The MIT License).

See LICENSE for more information.

Documentation

Overview

Package expensify provides a client for the Expensify API.

Index

• type Client
  • func NewClient(partnerUserID, partnerUserSecret string, options ...Option) (*Client, error)
  • func (c *Client) Options(options ...Option) error
• type Error
  • func (e Error) Error() string
• type Expense
• type ExpenseService
• type Option
  • func SetClient(client *http.Client) Option
• type SubmittedExpense
• type Tax
• type Time
  • func NewTime(t time.Time) Time
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t *Time) UnmarshalJSON(b []byte) (err error)

Types

type Client

type Client struct {
	Expense ExpenseService
	// contains filtered or unexported fields
}

Client provides the Expensify HTTP API operations.

func NewClient

func NewClient(partnerUserID, partnerUserSecret string, options ...Option) (*Client, error)

NewClient returns a new Expensify API client. The credentials can be retrieved from https://www.expensify.com/tools/integrations.

func (*Client) Options

func (c *Client) Options(options ...Option) error

Options applies Options to a client instance.

type Error

type Error struct {
	Message    string `json:"responseMessage"`
	StatusCode int    `json:"responseCode"`
}

Error is the generic error response returned on non 2xx HTTP status codes.

func (Error) Error

func (e Error) Error() string

Error implements the error interface.

type Expense

type Expense struct {
	// The name of the expense's merchant.
	Merchant string `json:"merchant"`
	// The date of the expense.
	Created Time `json:"created"`
	// The amount of the expense, in cents.
	Amount int `json:"amount"`
	// The three-letter currency code of the expense.
	Currency string `json:"currency"`

	// An unique, custom string that you specify. This will help identify the
	// expense after being exported. Optional.
	ExternalID string `json:"externalID,omitempty"`
	// The name of the category to assign to the expense. Optional.
	Category string `json:"category,omitempty"`
	// The name of the tag to assign to the expense. Optional.
	Tag string `json:"tag,omitempty"`
	// Whether to mark the expense as billable or not. Optional.
	Billable bool `json:"billable,omitempty"`
	// Whether to mark the expense as reimbursable or not. Optional.
	Reimbursable bool `json:"reimbursable,omitempty"`
	// An expense comment. Optional.
	Comment string `json:"comment,omitempty"`
	// The ID of the report you want to attach the expense to. Optional.
	ReportID int `json:"reportID,omitempty"`
	// The ID of the policy the tax belongs to. Optional.
	PolicyID string `json:"policyID,omitempty"`
	// Optional.
	Tax *Tax `json:"tax,omitempty"`
}

Expense is an Expensify expense.

type ExpenseService

type ExpenseService interface {
	// Create submits expenses to the given account.
	Create(ctx context.Context, employeeEmail string, expenses []*Expense) ([]*SubmittedExpense, error)
}

ExpenseService bundles all operations on expenses.

type Option

type Option func(c *Client) error

An Option can be used to configure the behaviour of the API client.

func SetClient

func SetClient(client *http.Client) Option

SetClient specifies a custom http client that should be used to make requests.

type SubmittedExpense

type SubmittedExpense struct {
	Expense

	// The transaction ID for the submitted expense.
	TransactionID string `json:"transactionID,omitempty"`
}

SubmittedExpense is an Expensify expense which has been submitted to Expensify and contains additional details.

type Tax

type Tax struct {
	// The tax RateID as defined in the policy.
	RateID string `json:"rateID"`

	// Amount paid on the expense. Specify it when only a sub-part of the
	// expense was taxed. Optional
	Amount int `json:"amount,omitempty"`
}

Tax applied to an expense.

type Time

type Time struct {
	time.Time
}

Time which marshals to and unmarshals from "yyyy-mm-dd" format.

func NewTime

func NewTime(t time.Time) Time

NewTime returns a new Time from the given time.Time.

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON implements json.Unmarshaler.