feat: add Tags endpoints

README.md

@@ -37,7 +37,7 @@ const validateApiKey = async () => {
   }
 
   return true;
-}
+};
 
 const validApiKey = await validateApiKey();
 
@@ -60,17 +60,17 @@ if (validApiKey) {
 
 The following modules of the Up API are fully supported:
 
-* [Accounts](https://developer.up.com.au/#accounts)
-* [Categories](https://developer.up.com.au/#categories)
-* [Transactions](https://developer.up.com.au/#transactions)
-* [Utility](https://developer.up.com.au/#utility_endpoints)
+- [Accounts](https://developer.up.com.au/#accounts)
+- [Categories](https://developer.up.com.au/#categories)
+- [Transactions](https://developer.up.com.au/#transactions)
+- [Utility](https://developer.up.com.au/#utility_endpoints)
+- [Tags](https://developer.up.com.au/#tags)
 
 ## Not supported yet
 
 The following modules of the Up API are not yet supported (feel free to send a PR!):
 
-* [Tags](https://developer.up.com.au/#tags)
-* [Webhooks](https://developer.up.com.au/#webhooks)
+- [Webhooks](https://developer.up.com.au/#webhooks)
 
 ## Special thanks
 

package.json

@@ -30,7 +30,7 @@
     "access": "public"
   },
   "dependencies": {
-    "axios": "^0.20.0"
+    "axios": "^0.19.0"
   },
   "devDependencies": {
     "dts-bundle": "^0.7.3",

src/helper/client.ts

@@ -10,7 +10,7 @@ export class UpClient {
       headers: {
         Accept: 'application/json',
         'Content-Type': 'application/json',
-        'Authorization': `Bearer ${apiKey}`
+        Authorization: `Bearer ${apiKey}`,
       },
     });
   }
@@ -19,4 +19,14 @@ export class UpClient {
     const res = await this.api.get<T>(url);
     return res.data;
   }
+
+  public async post<T>(url: string, payload: T): Promise<void> {
+    await this.api.post<T>(url, { data: payload });
+    return;
+  }
+
+  public async delete<T>(url: string, payload: T): Promise<void> {
+    await this.api.delete<T>(url, { data: { data: payload } });
+    return;
+  }
 }

src/index.ts

@@ -1,21 +1,24 @@
 import { UtilApi } from './util/api';
-import { AccountsApi } from "./accounts/api";
-import { CategoriesApi } from "./categories/api";
-import { UpClient } from "./helper/client";
-import { TransactionsApi } from "./transactions/api";
+import { AccountsApi } from './accounts/api';
+import { CategoriesApi } from './categories/api';
+import { UpClient } from './helper/client';
+import { TransactionsApi } from './transactions/api';
+import { TagsApi } from './tags/api';
 
 export class UpApi {
   public util: UtilApi;
   public accounts: AccountsApi;
   public categories: CategoriesApi;
   public transactions: TransactionsApi;
+  public tags: TagsApi;
 
   constructor(apiKey: string) {
     const api = new UpClient(apiKey);
     this.util = new UtilApi(api);
     this.accounts = new AccountsApi(api);
     this.categories = new CategoriesApi(api);
     this.transactions = new TransactionsApi(api);
+    this.tags = new TagsApi(api);
   }
 }
 
@@ -24,5 +27,5 @@ export * from './interfaces';
 export * from './util/interfaces';
 export * from './accounts/interfaces';
 export * from './categories/interfaces';
+export * from './tags/interfaces';
 export * from './transactions/interfaces';
-

src/tags/api.ts

@@ -0,0 +1,67 @@
+import { ListTagsRequest, ListTagsResponse, TagInputResourceIdentifier } from './interfaces';
+import { UpClient } from '../helper/client';
+
+const LIST_ENDPOINT = 'tags';
+const TRANSACTION_ENDPOINT = 'transactions';
+
+/**
+ * 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(private api: UpClient) {}
+
+  /**
+   * Retrieve a list of all tags currently in use. The returned list is not
+   * paginated.
+   */
+  public async list(params: ListTagsRequest = {}): Promise<{ data: ListTagsResponse[] }> {
+    const urlParams = [];
+    if (params.pageSize) {
+      urlParams.push(`page[size]=${params.pageSize}`);
+    }
+
+    return this.api.get<{ data: ListTagsResponse[] }>(`${LIST_ENDPOINT}?${urlParams.join('&')}`);
+  }
+
+  /**
+   * 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.
+   */
+  public async addTagsToTransaction(
+    transactionId: string,
+    tags: TagInputResourceIdentifier[]
+  ): Promise<void> {
+    return this.api.post(TagsApi.buildTransactionTagsPath(transactionId), tags);
+  }
+
+  /**
+   * 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.
+   */
+  public async removeTagsFromTransaction(
+    transactionId: string,
+    tags: TagInputResourceIdentifier[]
+  ): Promise<void> {
+    return this.api.delete(TagsApi.buildTransactionTagsPath(transactionId), tags);
+  }
+
+  /**
+   * Build API path to access the tags for a given transaction.
+   * @param transactionId The unique identifier for the transaction. e.g.
+   * 0a3c4bdd-1de5-4b9b-bf9e-53fb0b5f2cd7
+   */
+  private static buildTransactionTagsPath(transactionId: string) {
+    return `${TRANSACTION_ENDPOINT}/${transactionId}/relationships/tags`;
+  }
+}

src/tags/interfaces.ts

@@ -0,0 +1,76 @@
+/**
+ * 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: {
+      links?: {
+        /**
+         * The link to retrieve the related resource(s) in this relationship.
+         */
+        related: string;
+      };
+    };
+  };
+}
+
+/**
+ * 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: {
+    /**
+     * The link to the previous page in the results. If this value is `null`
+     * there is no previous page.
+     */
+    prev: string | null;
+    /**
+     * The link to the next page in the results. If this value is `null`
+     * there is no next page.
+     */
+    next: string | null;
+  };
+}
+
+/**
+ * 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;
+}