up-bank-api
Version:
The Up Bank API TypeScript wrapper
749 lines (731 loc) • 30.6 kB
TypeScript
// Generated by dts-bundle v0.7.3
export class UpApi {
readonly util: UtilApi;
readonly accounts: AccountsApi;
readonly categories: CategoriesApi;
readonly transactions: TransactionsApi;
readonly tags: TagsApi;
readonly webhooks: WebhookApi;
constructor(apiKey?: string | null);
updateApiKey(apiKey: string): void;
}
/**
* Some endpoints exist not to expose data, but to test the API itself.
* Currently there is only one endpoint in this group: ping!
*/
export class UtilApi {
constructor(api: UpClient);
/**
* Make a basic ping request to the API.
* This is useful to verify that authentication is functioning correctly.
* On authentication success an HTTP 200 status is returned.
* On failure an HTTP 401 error response is returned.
*/
ping(): Promise<Pong>;
}
/**
* Accounts represent the underlying store used to track balances and the transactions
* that have occurred to modify those balances over time. Up currently has two types of
* account: SAVER - used to earn interest and to hit savings goals, and
* TRANSACTIONAL - used for everyday spending.
*/
export class AccountsApi {
constructor(api: UpClient);
/**
* Retrieve a paginated list of all accounts for the currently authenticated user.
* The returned list is paginated and can be scrolled by following the prev and next links where present.
*/
list(params?: ListAccountsRequest): Promise<ListAccountResponse>;
/**
* Retrieve a specific account by providing its unique identifier.
* @param accountId The unique identifier for the account. e.g. e7a729f0-aaa7-4d6a-b231-f794c0155e1d
*/
retrieve(accountId: string): Promise<{
data: AccountResource;
}>;
}
/**
* Categories enable understanding where your money goes by driving powerful insights in Up.
* All categories in Up are pre-defined and are automatically assigned to new purchases in most cases.
* A parent-child relationship is used to represent categories, however parent categories cannot be
* directly assigned to transactions.
*/
export class CategoriesApi {
constructor(api: UpClient);
/**
* Retrieve a list of all categories and their ancestry. The returned list is not paginated.
*/
list(params?: ListCategoriesRequest): Promise<{
data: CategoryResource[];
}>;
/**
* Retrieve a specific category by providing its unique identifier.
* @param categoryId The unique identifier for the category. e.g. restaurants-and-cafes
*/
retrieve(categoryId: string): Promise<{
data: CategoryResource;
}>;
}
/**
* Transactions represent the movement of money into and out of an account. They have many
* characteristics that vary depending on the kind of transaction. Transactions may be temporarily
* HELD (pending) or SETTLED, typically depending on which payment method was used at the point of sale.
*/
export class TransactionsApi {
constructor(api: UpClient);
/**
* Retrieve a list of all transactions across all accounts for the currently authenticated user.
* The returned list is paginated and can be scrolled by following the next and prev links where present.
* To narrow the results to a specific date range pass one or both of filter[since] and filter[until] in
* the query string. These filter parameters should not be used for pagination. Results are ordered
* newest first to oldest last.
*/
list(params?: ListTransactionRequest): Promise<ListTransactionsResponse>;
/**
* Retrieve a specific transaction by providing its unique identifier.
* @param transactionId The unique identifier for the transaction. e.g. 58c28694-4639-4992-94f3-b030bdb06a8e
*/
retrieve(transactionId: string): Promise<{
data: TransactionResource;
}>;
/**
* Retrieve a list of all transactions for a specific account. The returned list is paginated and can be
* scrolled by following the next and prev links where present. To narrow the results to a specific date
* range pass one or both of filter[since] and filter[until] in the query string. These filter parameters
* should not be used for pagination. Results are ordered newest first to oldest last.
* @param accountId The unique identifier for the account. e.g. 7a2dfb6f-4c5c-47db-9a95-8794b1ae1470
*/
listByAccount(accountId: string, params?: ListTransactionRequest): Promise<ListTransactionsResponse>;
}
/**
* Tags are custom labels that can be associated with transactions on Up. Within
* the Up application, tags provide additional insight into spending. For
* example, you could have a "Take Away" tag that you apply to purchases from
* food delivery services. The Up API allows you to manage the tags associated
* with transactions. Each transaction may have up to 6 tags.
*/
export class TagsApi {
constructor(api: UpClient);
/**
* Retrieve a list of all tags currently in use. The returned list is not
* paginated.
*/
list(params?: ListTagsRequest): Promise<ListTagsResponse>;
/**
* Associates one or more tags with a specific transaction. No more than 6
* tags may be present on any single transaction. Duplicate tags are silently
* ignored.
* @param transactionId The unique identifier for the transaction. e.g.
* 0a3c4bdd-1de5-4b9b-bf9e-53fb0b5f2cd7
* @param tags The tags to add to the transaction.
*/
addTagsToTransaction(transactionId: string, tags: TagInputResourceIdentifier[]): Promise<void>;
/**
* Disassociates one or more tags from a specific transaction. Tags that are
* not associated are silently ignored.
* @param transactionId The unique identifier for the transaction. e.g.
* 0a3c4bdd-1de5-4b9b-bf9e-53fb0b5f2cd7
* @param tags The tags to remove from the transaction.
*/
removeTagsFromTransaction(transactionId: string, tags: TagInputResourceIdentifier[]): Promise<void>;
}
/**
* Webhooks provide a mechanism for a configured URL to receive events when
* transaction activity occurs on Up. You can think of webhooks as being like
* push notifications for your server-side application.
*/
export class WebhookApi {
constructor(api: UpClient);
/**
* Retrieve a list of configured webhooks. The returned list is not
* paginated.
*/
list(params?: ListWebhooksRequest): Promise<ListWebhooksResponse>;
/**
* Create a new webhook with a given URL. The URL will receive webhook events
* as JSON-encoded POST requests. The URL must respond with a HTTP 200 status
* on success.
* @param url The URL that this webhook should post events to. This must be a
* valid HTTP or HTTPS URL that does not exceed 300 characters in length.
* @param description An optional description for this webhook, up to 64
* characters in length.
*/
create(url: string, description?: string | null): Promise<CreateWebhookResponse>;
/**
* Retrieve a specific webhook by providing its unique identifier.
* @param id The unique identifier for the webhook. e.g.
* a3f1e92b-b790-42cf-afe7-6f4efad9fa9d
*/
retrieve(id: string): Promise<WebhookResource>;
/**
* Delete a specific webhook by providing its unique identifier. Once deleted,
* webhook events will no longer be sent to the configured URL.
* @param id The unique identifier for the webhook. e.g.
* a3f1e92b-b790-42cf-afe7-6f4efad9fa9d
*/
delete(id: string): Promise<void>;
/**
* Send a `PING` event to a webhook by providing its unique identifier. This is
* useful for testing and debugging purposes. The event is delivered
*hronously and its data is returned in the response to this request
* @param id The unique identifier for the webhook. e.g.
* a3f1e92b-b790-42cf-afe7-6f4efad9fa9d
*/
ping(id: string): Promise<WebhookEventResource>;
}
export function isUpApiError(e: unknown): e is UpApiError;
export interface MoneyObject {
/** The ISO 4217 currency code. */
currencyCode: string;
/**
* The amount of money, formatted as a string in the relevant currency.
* For example, for an Australian dollar value of $10.56, this field will be "10.56".
* The currency symbol is not included in the string.
*/
value: string;
/**
* The amount of money in the smallest denomination for the currency, as a 64-bit integer.
* For example, for an Australian dollar value of $10.56, this field will be 1056.
*/
valueInBaseUnits: number;
}
export interface RelationshipData<RelationshipType extends string> {
/** The type of this resource */
type: RelationshipType;
/** The unique identifier of the resource within its type. */
id: string;
}
export interface Relationship<TRelationshipData> {
data: TRelationshipData;
links?: {
/** The link to retrieve the related resource(s) in this relationship. */
related?: string;
};
}
export interface PaginationLinks<ReturnType> {
/** The link to the previous page in the results. If this value is null there is no previous page. */
prev: null | (() => Promise<ReturnType>);
/** The link to the next page in the results. If this value is null there is no next page. */
next: null | (() => Promise<ReturnType>);
}
export interface UpApiError {
response: {
data: ErrorResponse;
status: number;
};
}
/** Generic error response that returns one or more errors. */
export interface ErrorResponse {
/** The list of errors returned in this response. */
errors: ErrorObject[];
}
export interface ErrorObject {
/**
* The HTTP status code associated with this error. This can also be obtained from the response headers.
* The status indicates the broad type of error according to HTTP semantics.
*/
status: string;
/**
* A short description of this error. This should be stable across multiple occurrences of this type
* of error and typically expands on the reason for the status code.
*/
title: string;
/**
* A detailed description of this error. This should be considered unique to individual occurrences
* of an error and subject to change. It is useful for debugging purposes.
*/
detail: string;
/**
* If applicable, location in the request that this error relates to. This may be a parameter in
* the query string, or a an attribute in the request body.
*/
source?: {
/** If this error relates to a query parameter, the name of the parameter. */
parameter?: string;
/** If this error relates to an attribute in the request body, a rfc-6901 JSON pointer to the attribute. */
pointer?: string;
};
}
export interface Pong {
meta: {
/** The unique identifier of the authenticated customer. */
id: string;
/** A cute emoji that represents the response status. */
statusEmoji: string;
};
}
export interface ListAccountsRequest {
/** The number of records to return in each page. e.g. ?page[size]=30 */
pageSize?: number;
}
export enum AccountTypeEnum {
saver = "SAVER",
transactional = "TRANSACTIONAL"
}
export interface AccountResource {
/** The type of this resource: accounts */
type: string;
/** The unique identifier for this account. */
id: string;
attributes: {
/** The name associated with the account in the Up application. */
displayName: string;
/** The bank account type of this account. */
accountType: AccountTypeEnum;
/** The available balance of the account, taking into account any amounts that are currently on hold. */
balance: MoneyObject;
/** The date-time at which this account was first opened. */
createdAt: string;
};
relationships: {
transactions: Relationship<undefined>;
};
links: {
/** The canonical link to this resource within the API. */
self: string;
};
}
export interface ListAccountResponse {
/** The list of accounts returned in this response. */
data: AccountResource[];
links: PaginationLinks<ListAccountResponse>;
}
export interface ListCategoriesRequest {
/**
* The unique identifier of a parent category for which to return only its children.
* Providing an invalid category identifier results in a 404 response.
* e.g. ?filter[parent]=good-life
*/
parent?: string;
}
export interface CategoryResource {
/** The type of this resource: categories */
type: string;
/** The unique identifier for this category. This is a human-readable but URL-safe value. */
id: string;
attributes: {
/** The name of this category as seen in the Up application. */
name: string;
};
relationships: {
parent: Relationship<null | RelationshipData<'categories'>>;
children: Relationship<Array<RelationshipData<'categories'>>>;
};
links: {
/** The canonical link to this resource within the API. */
self: string;
};
}
/**
* Provides information about a tag.
*/
export interface TagResource {
/**
* The type of this resource: `tags`
*/
type: string;
/**
* The label of the tag, which also acts as the tag’s unique identifier.
*/
id: string;
relationships: {
transactions: Relationship<undefined>;
};
}
/**
* Uniquely identifies a single tag in the API.
*/
export interface TagInputResourceIdentifier {
/**
* The type of this resource: `tags`
*/
type: string;
/**
* The label of the tag, which also acts as the tag’s unique identifier.
*/
id: string;
}
export interface ListTagsRequest {
/** The number of records to return in each page. e.g. ?page[size]=30 */
pageSize?: number;
}
/**
* Successful response to get all tags. This returns a paginated list of
* tags, which can be scrolled by following the `prev` and `next` links if
* present.
*/
export interface ListTagsResponse {
/**
* The list of tags returned in this response.
*/
data: TagResource[];
links: PaginationLinks<ListTagsResponse>;
}
/**
* Request to add or remove tags associated with a transaction.
*/
export interface UpdateTransactionTagsRequest {
/**
* The tags to add to or remove from the transaction.
*/
data: TagInputResourceIdentifier;
}
export interface ListTransactionRequest {
/** The number of records to return in each page. e.g. ?page[size]=30 */
pageSize?: number;
/**
* The transaction status for which to return records. This can be used to filter HELD transactions
* from those that are SETTLED.
* e.g. ?filter[status]=HELD
*/
filterStatus?: string;
/**
* The start date-time from which to return records, formatted according to rfc-3339. Not
* to be used for pagination purposes.
* e.g. ?filter[since]=2020-01-01T01:02:03+10:00
*/
filterSince?: string;
/**
* The end date-time up to which to return records, formatted according to rfc-3339. Not to
* be used for pagination purposes.
* e.g. ?filter[until]=2020-02-01T01:02:03+10:00
*/
filterUntil?: string;
/**
* The category identifier for which to filter transactions. Both parent and child categories
* can be filtered through this parameter. Providing an invalid category identifier results in a 404 response.
* e.g. ?filter[category]=good-life
*/
filterCategory?: string;
/**
* A transaction tag to filter for which to return records. If the tag does not exist, zero records
* are returned and a success response is given.
* e.g. ?filter[tag]=Holiday
*/
filterTag?: string;
}
export enum TransactionTypeEnum {
held = "HELD",
settled = "SETTLED"
}
export interface HoldInfoObject {
/** The amount of this transaction while in the HELD status, in Australian dollars. */
amount: MoneyObject;
/**
* The foreign currency amount of this transaction while in the HELD status. This field will be null
* for domestic transactions. The amount was converted to the AUD amount reflected in the amount field.
*/
foreignAmount: MoneyObject | null;
}
export interface RoundUpObject {
/** The total amount of this Round Up, represented as negative value. */
amount: MoneyObject;
/**
* The portion of the Round Up amount owing to boosted Round Ups, represented as a negative value.
* If no boost was added to the Round Up this field will be null.
*/
boostPortion: MoneyObject | null;
}
export interface CashbackObject {
/** A brief description of why this cashback was paid. */
description: string;
/** The total amount of cashback paid, represented as a positive value. */
amount: MoneyObject;
}
export interface TransactionResource {
/** The type of this resource: accounts */
type: string;
/** The unique identifier for this account. */
id: string;
attributes: {
/**
* The current processing status of this transaction,
* according to whether or not this transaction has settled or is still held.
*/
status: TransactionTypeEnum;
/**
* The original, unprocessed text of the transaction. This is often not a perfect indicator of
* the actual merchant, but it is useful for reconciliation purposes in some cases.
*/
rawText: string | null;
/** A short description for this transaction. Usually the merchant name for purchases. */
description: string;
/** Attached message for this transaction, such as a payment message, or a transfer note. */
message: string | null;
/**
* If this transaction is currently in the HELD status, or was ever in the HELD status,
* the amount and foreignAmount of the transaction while HELD.
*/
holdInfo: HoldInfoObject | null;
/** Details of how this transaction was rounded-up. If no Round Up was applied this field will be null. */
roundUp: RoundUpObject | null;
/** The total amount of cashback paid, represented as a positive value. */
cashback: CashbackObject | null;
/**
* The amount of this transaction in Australian dollars. For transactions that were once HELD
* but are now SETTLED, refer to the holdInfo field for the original amount the transaction was HELD at.
*/
amount: MoneyObject;
/**
* The foreign currency amount of this transaction. This field will be null for domestic transactions.
* The amount was converted to the AUD amount reflected in the amount of this transaction.
* Refer to the holdInfo field for the original foreignAmount the transaction was HELD at.
*/
foreignAmount: MoneyObject | null;
/**
* The date-time at which this transaction settled. This field will be null for transactions
* that are currently in the HELD status.
*/
settledAt: string;
/** The date-time at which this transaction was first encountered. */
createdAt: string;
};
relationships: {
account: Relationship<RelationshipData<'accounts'>>;
transferAccount: Relationship<null | RelationshipData<'accounts'>>;
category: Relationship<null | RelationshipData<'categories'>>;
parentCategory: Relationship<null | RelationshipData<'categories'>>;
tags: Relationship<Array<RelationshipData<'tags'>>>;
};
links: {
/** The canonical link to this resource within the API. */
self: string;
};
}
export interface ListTransactionsResponse {
/** The list of transactions returned in this response. */
data: TransactionResource[];
links: PaginationLinks<ListTransactionsResponse>;
}
/**
* Provides information about a webhook.
*/
export interface WebhookResource {
/**
* The type of this resource: `webhooks`
*/
type: string;
/**
* The unique identifier for this webhook.
*/
id: string;
attributes: {
/**
* The URL that this webhook is configured to `POST` events to.
*/
url: string;
/**
* An optional description that was provided at the time the webhook was
* created.
*/
description: string | null;
/**
* A shared secret key used to sign all webhook events sent to the
* configured webhook URL. This field is returned only once, upon the
* initial creation of the webhook. If lost, create a new webhook and
* delete this webhook.
*
* The webhook URL receives a request with a
* `X-Up-Authenticity-Signature` header, which is the SHA-256 HMAC of
* the entire raw request body signed using this `secretKey`. It is
* advised to compute and check this signature to verify the
* authenticity of requests sent to the webhook URL. See
* [Handling webhook events](#callback_post_webhookURL) for full
* details.
*/
secretKey?: string;
/**
* The date-time at which this webhook was created.
*/
createdAt: string;
};
relationships: {
logs: Relationship<undefined>;
};
links?: {
/**
* The canonical link to this resource within the API.
*/
self: string;
};
}
export interface ListWebhooksRequest {
/** The number of records to return in each page. e.g. ?page[size]=30 */
pageSize?: number;
}
/**
* Successful response to get all webhooks. This returns a paginated list of
* webhooks, which can be scrolled by following the `prev` and `next` links
* if present.
*/
export interface ListWebhooksResponse {
/**
* The list of webhooks returned in this response.
*/
data: WebhookResource[];
links: PaginationLinks<ListWebhooksResponse>;
}
/**
* Represents a webhook specified as request input.
*/
export interface WebhookInputResource {
attributes: {
/**
* The URL that this webhook should post events to. This must be a valid
* HTTP or HTTPS URL that does not exceed 300 characters in length.
*/
url: string;
/**
* An optional description for this webhook, up to 64 characters in
* length.
*/
description?: string | null;
};
}
/**
* Request to create a new webhook. This currently only requires a `url`
* attribute.
*/
export interface CreateWebhookRequest {
/**
* The webhook resource to create.
*/
data: WebhookInputResource;
}
/**
* Successful response after creating a webhook.
*/
export interface CreateWebhookResponse {
/**
* The webhook that was created.
*/
data: WebhookResource;
}
/**
* Provides the event data used in asynchronous webhook event callbacks to
* subscribed endpoints. Webhooks events have defined `eventType`s and may
* optionally relate to other resources within the Up API.
*/
export interface WebhookEventResource {
/**
* The type of this resource: `webhook-events`
*/
type: string;
/**
* The unique identifier for this event. This will remain constant across
* delivery retries.
*/
id: string;
attributes: {
/**
* The type of this event. This can be used to determine what action to
* take in response to the event.
*/
eventType: 'TRANSACTION_CREATED' | 'TRANSACTION_SETTLED' | 'TRANSACTION_DELETED' | 'PING';
/**
* The date-time at which this event was generated.
*/
createdAt: string;
};
relationships: {
webhook: Relationship<RelationshipData<'webhooks'>>;
transaction?: Relationship<RelationshipData<'transactions'>>;
};
}
/**
* Asynchronous callback request used for webhook event delivery.
*/
export interface WebhookEventCallback {
/**
* The webhook event data sent to the subscribed webhook.
*/
data: WebhookEventResource;
}
/**
* Successful response to get a single webhook.
*/
export interface GetWebhookResponse {
/**
* The webhook returned in this response.
*/
data: WebhookResource;
}
/**
* Provides historical webhook event delivery information for analysis and
* debugging purposes.
*/
export interface WebhookDeliveryLogResource {
/**
* The type of this resource: `webhook-delivery-logs`
*/
type: string;
/**
* The unique identifier for this log entry.
*/
id: string;
attributes: {
/**
* Information about the request that was sent to the webhook URL.
*/
request: {
/**
* The payload that was sent in the request body.
*/
body: string;
};
/**
* Information about the response that was received from the webhook URL.
*/
response: {
/**
* The HTTP status code received in the response.
*/
statusCode: number;
/**
* The payload that was received in the response body.
*/
body: string;
} | null;
/**
* Specifies the nature of the success or failure of a webhook delivery
* attempt to the subscribed webhook URL. The currently returned values are
* described below:
*
* - **`DELIVERED`**: The event was delivered to the webhook URL
* successfully and a `200` response was received.
* - **`UNDELIVERABLE`**: The webhook URL was not reachable, or timed out.
* - **`BAD_RESPONSE_CODE`**: The event was delivered to the webhook URL
* but a non-`200` response was received.
*/
deliveryStatus: 'DELIVERED' | 'UNDELIVERABLE' | 'BAD_RESPONSE_CODE';
/**
* The date-time at which this log entry was created.
*/
createdAt: string;
};
relationships: {
webhookEvent: {
data: RelationshipData<'webhook-events'>;
};
};
}
/**
* Successful response to get all delivery logs for a webhook. This returns
* a paginated list of delivery logs, which can be scrolled by following the
* `next` and `prev` links if present.
*/
export interface ListWebhookDeliveryLogsResponse {
/**
* The list of delivery logs returned in this response.
*/
data: WebhookDeliveryLogResource[];
links: PaginationLinks<ListWebhookDeliveryLogsResponse>;
}
export class UpClient {
constructor(apiKey?: string | null);
updateApiKey(apiKey: string): void;
processLink<T>(link: string): null | (() => Promise<T>);
get<T>(url: string): Promise<T>;
post<T, V>(url: string, payload?: T): Promise<V>;
delete<T, V>(url: string, payload?: T): Promise<V>;
}