Up Yeah

A Javascript wrapper for the Up Banking API

Installation

npm npm i up-yeah

Yarn yarn add up-yeah

Usage

Using the UpClient

The simplest way to start is to create a client instance and export it for use elsewhere.

You can create a client object by calling the UpClient constructor and providing an options object with a personal access token:

Typescript

// create a a client
import UpClient, { UpClientOptions } from 'up-yeah/client';

const options: UpClientOptions = {
	personalAccessToken: process.env.UP_TOKEN as string,
};

export const client = new UpClient(options);

Javascript

import UpClient, { UpClientOptions } from 'up-yeah/client';

const options = {
	personalAccessToken: process.env.UP_TOKEN as string
};

export const client = new UpClient(options);

And here's how you'd use the client in another file:

Typescript

import { GetAccountsQueryOptions } from 'up-yeah/client';
import AccountResource from 'up-yeah/resources/Account';
import client from './client';

const accounts: AccountResource = await client.getAccounts();

Javascript

import client from './client';

const accounts = await client.getAccounts();

You can also use an AccountResource object to get its transactions

Typescript

import {
	GetAccountsQueryOptions,
	GetTransactionsQueryOptions,
} from 'up-yeah/client';
import { OwnershipTypeEnum } from 'up-yeah';
import AccountResource from 'up-yeah/resources/Account';
import ResourceColelction from 'up-yeah/resources/Resource';
import TransactionResource from 'up-yeah/resources/Account';
import client from './client';

const options: GetAccountsQueryOptions = {
	filterAccOwnershipType: OwnershipTypeEnum.INDIVIDUAL,
};

const accounts: ResourceCollection<AccountResource> = await client.getAccounts(
	options,
);

const transactions: ResourceCollection<TransactionResource> =
	await accounts[0].getTransactions();

Javascript

import {
	GetAccountsQueryOptions,
	GetTransactionsQueryOptions,
} from 'up-yeah/client';
import client from './client';

const options = {
	filterAccOwnershipType: OwnershipTypeEnum.INDIVIDUAL,
};

const accounts = await client.getAccounts(options);

const transactions = await accounts[0].getTransactions();

For more info, checkout API and look checkout the examples!

Using ResourceCollection

The ResourceCollection class holds an array of resources and allows for pagination through the use of next and prev methods.

Example:

import {
	GetAccountsQueryOptions,
	GetTransactionsQueryOptions,
} from 'up-yeah/client';
import { OwnershipTypeEnum } from 'up-yeah';
import AccountResource from 'up-yeah/resources/Account';
import ResourceColelction from 'up-yeah/resources/Resource';
import TransactionResource from 'up-yeah/resources/Account';
import client from './client';

const options: GetAccountsQueryOptions = {
	filterAccOwnershipType: OwnershipTypeEnum.INDIVIDUAL,
};

const accounts: ResourceCollection<AccountResource> = await client.getAccounts(
	options,
);

console.log(accounts.resources);
const nextAccounts: AccountResource[]  = await accounts.next();
console.log(nextAccounts);
const prevAccounts: AccountResource[] = await accounts.prev();

Error handling

When an error occurs, the Up API responds with an array of one or more errors. When an UpError occurs, this package will throw an UpErrorCollection error with all the errors.

Example:

import {
	GetAccountsQueryOptions,
	GetTransactionsQueryOptions,
} from 'up-yeah/client';
import client from './client';
import UpErrorCollection from 'up-yeah/erros/UpErrorCollection';

async function getAccounts() {
	const options = {
		filterAccOwnershipType: OwnershipTypeEnum.INDIVIDUAL,
	};

	try {
		const accounts = await client.getAccounts(options);
	} catch (e: unknown) {
		if (e instanceof UpErrorCollection) {
			console.log(e.getFirstError()); //get first error
			console.log(e.errors);
		}
	}
}

API

UpClient (src/client/UpClient.ts)

A class that exposes the Up API endpoints in its methods, using axios to handle requests.

Returns: an UpClient object.

options: UpClientOptions

UpClient options passed to parameter

• personalAccessToken - Up Personal Access Token

interface UpClientOptions {
	personalAccessToken: string;
};

Methods

getClientInstance(): Axios - Getter for the clientInstance property

• Returns: Axios instance created by client

getAccounts(options?) - Get a paginated list of all accounts for the currently authenticated user.

• Ref: List Accounts
• Request: GET /accounts
• Returns: Promise<ResourceCollection<AccountResource>>
• Parameters:
  • options?: GetAccountsQueryOptions - Params to be provided to the endpoint.

getAccount(id) - Get account with matching id.

• Ref: Retrieve Account
• Request: GET /accounts/{id}
• Returns: Promise<ResourceCollection<AccountResource>>
• Parameters:
  • id: string - The unique idenifier of the account.

getTransaction(transactionId) - Get the transaction with matching id.

• Ref: Retrieve Transaction
• Request: GET /transactions/{id}.
• Returns: Promise<TransactionResource>
• Parameters:
  • transactionId: string - The unique identifier of the transaction

getTransactions(options?) - Get a paginated list of all transactions across all accounts.

• Ref: List Transactions
• Request: GET /transactions
• Returns: Promise<ResourceCollection<TransactionResource>>
• Parameters:
  • options?: GetTransactionsQueryOptions

getTransactionsByAccount(accountId: string, options?) - Get a list of transactions based on a unique account identifier

• Ref: List transactions by account
• Request: GET /accounts/{accountId}/transactions
• Returns: Promise<ResourceCollection<TransactionResource>>
• Parameters:
  • accountId - the unique account identifier.
  • options?: GetTransactionsQueryOptions - request query params.

getCategories() - Get a non-paginated list of categories and their ancestry

• Ref: List categories
• Request: GET /categories
• Returns: Promise<ResourceCollection<CategroyResource>>

categorizeTransaction(transactionId,category) - Update the category associated with a transaction

• Ref: Categorize transaction
• Request: PATCH /transactions/{transactionId}/relationships/category
• Returns: Promise<boolean>
• Parameters:
  • transactionId: string - the unique identifier of the transaction
  • category - the category to update the transaction with

getCategory(id: string)

• Ref: Retrieve a category
• Request: GET /categories/{id}
• Returns: Promise<CategoryResource>
• Paramaters:
  • id: string - the category to retrieve.

getTags() - Get a paginated list of all tags in use. Ref: List tags

• Request: GET /tags
• Returns: Promise<ResourceCollection<TagResource>>

addTagsToTransaction(transactionId, payload) - Associate one or more tags with a specific transaction.

• Ref: Add tags to transaction
• Request: POST /transactions/{transactionId}/relationships/tags
• Returns: Promise<boolean>
• Parameters:
  • transactionId: string - the unique transaction identifier
  • paylod: PostTagPayload[] - the list of tags to associate with the transaction

removeTagsFromTransaction(transactionId)

• Ref: Remove tags from transaction
• Request: DELETE /transactions/{transactionId}/relationships/tags
• Returns: Promise<boolean>
• Parameters:
  • transactionId: string - the unique transaction identifier

ResourceCollection src/resources/Resource/ResourceCollection.ts

A pagination wrapper for Up resources.

The class takes a generic which must extend the Resource class.

Pagination is offered through the prev() and next() methods.

Methods

prev() - Retrieve the previous list of pages if available.

next() - Retrieve the next list of pages if available.

AccountResource

A class which encapsulates an Up Account resource.

Methods

getTransactions(options?) - Get paginated list of transactions for an account

• Request: GET /accounts/this.id/transactions
• Returns: Promise<ResourceCollection<AccountResource>>
• Parameters:
  • options?: GetTransactionsQueryOptions - options to pass as params to the request.

TransactionResource

A class which encapsulates an Up Transaction.

Methods

getAccount() - Get paginated list of transactions for an account

• Request: GET /accounts/{id}/transactions
• Returns: Promise<AccountResource>

Types

GetAccountsQueryOptions - Typescript interface for the List Accounts params.

• pageSize - the number of records to return in each page.
• filterAccType - the type of account for which to return records. This can be used to filter Savers from spending accounts.
• filterAccOwnershipType - the account ownership structure for which to return records. This can be used to filter 2Up accounts from Up accounts.

interface GetAccountsQueryOptions {
   pageSize?: number;
   filterAccType?: AccountTypeEnum;
   filterAccOwnershipType?: OwnershipTypeEnum;
};

GetTransactionsQueryOptions - Typescript interface for the List Transactions query params

• pageSize - the number of records to return in each page.
• filterStatus - filter the transactions by transaction status.
• filterSince - filter transactions made since the specified date
• filterUntil - filter transactions made up to the specified date
• filterTag - filter by tags, includes only transactions with the specified tag.

interface GetTransactionsQueryOptions {
   pageSize?: number;
   filterStatus?: TransactionStatus;
   filterSince?: string;
   filterUntil?: string;
   filterCategory?: string;
   filterTag?: string;
};

More...

For more information about a specific type or method in this library, I recommend reading the code.

If you're looking to learn more about the Up API then the best place to start is https://developer.up.com.au.