\n A Node.js library written in TypeScript to integrate the AIMS Tagging API.\n You MAY USE this library on the client as well as on the server side.\n \n \n Reach for more information at aimsapi.com\n \n \n Report a Bug\n -\n Request a Feature\n -\n Ask a Question\n
\n \n\n
\n\n\n
\n\n\n
Table of Contents
\n\n- [Getting Started](#getting-started)\n - [Authentication](#authentication)\n - [Next.js example](#example-with-nextjs)\n- [Usage](#usage)\n - [Routes](#routes)\n - [Response Structure](#response-structure)\n- [License](#license)\n\n\n\n---\n\n\n\n\n## Getting Started\n\n\n\n \nTo work with the package you need to have npm (or other package manager) installed.\nLibrary supports Node.js version 18 and above, and can be used in a client codebase.\n \n \n\n```\nnpm install @aims-api/aims-tagging-node\n```\n\n### Authentication\n\nIn order to use the lirbary you need to obtain credentials by contacting us at [hello@aimsapi.com](mailto:hello@aimsapi.com). Credentials consist of `CLIENT_ID`, `CLIENT_SECRET`, `LOGIN` and `PASSWORD`.\n\nTo access protected routes you need to authenticate in order to get a time-limited token. You need to use this token while creating a client instance.\n\n\n\n\n### Example with Next.js\n\n\n\nIt is common to make a proxy request from client app to the server \"Next.js API route\" in order to hide foreign URL.\n\nYou may store the token in a cookie or local storage (browser), but you need to retrieve it from the request object. Storing the token in cookies is recommended for security reasons. In case you decide to store it in cookies, you can set Axios interceptor to check if cookie is still valid and if not, terminate user session in order to obtain a new token.\n\n```typescript\n// pages/api/authenticate.ts\n\nimport { NextApiRequest, NextApiResponse } from 'next'\nimport { Client as TaggingApiClient } from '@aims-api/aims-tagging-node'\n\nexport const createClient = async (req: NextApiRequest) => {\n const { clientId, clientSecret } = await getSiteConfigForRequest(req)\n const apiUserToken = getTokenFromCookie(req)\n\n // You can retrieve auth_token from cookies or local storage\n // Authentication endpoints (e.g. \"authenticate\", \"register\", ...)\n // do not require \"apiUserToken\" field\n return new TaggingApiClient({\n apiHost: 'HOST_URL', // optional\n clientId: 'YOUR_CLIENT_ID', // required\n clientSecret: 'YOUR_CLIENT_SECRET', // required\n apiUserToken: JSON.parse(req.cookies.auth_token),\n })\n}\n\nconst handler = async (req: NextApiRequest, res: NextApiResponse) => {\n if (req.method === 'POST') {\n try {\n const { userEmail, userPassword } = req.body // credentials: LOGIN, PASSWORD\n // passed from the client-side code\n const aimsClient = createClient(req)\n const response = await aimsClient.endpoints.authentication.authenticate({\n userEmail,\n userPassword,\n })\n\n const { token, ...rest } = response // removes token from the response to hide\n // from the client-side code (optional)\n return\n res\n .setHeader(\n 'Set-Cookie',\n `auth_token=${JSON.stringify(response.token)}; HttpOnly; Secure; path=/`,\n ) // sets token to cookie (optional)\n .status(200)\n .json(rest)\n } catch (error) {\n console.warn(error)\n }\n }\n return res.status(400).json('Method not allowed')\n}\n\nexport default handler\n```\n\n\n\n\n## Usage\n\nWhen you create a client instance in your codebase, you can then easily access all the existing endpoints via IDE autocomplete, as well as the required and optional parameters.\n\nIt's recommended to create a new file for each request handler.\n\nFor calling an endpoint `batch.startTagging` credits are required, for each track in a batch user needs to have exactly one credit. To get information about credits availability, please call `apiUser.remainingMonthlyRequests` endpoint, property is named `remainingMonthlyRequests`.\n\n#### TypeScript\n\nYou can import input and response types that are provided in every endpoint file. In order to validate response structure and prevent application from crashing, you may use [Zod](https://github.com/colinhacks/zod) library.\n\nExample\n\n```typescript\n// src/types/index.ts\n\n...\n\ntype Track = Partial<{\n id: string\n title: string\n tags: Tags | null\n filesize: number | null\n duration: number | null\n processedAt: DateTime | null\n hookUrl: string | null\n modelVersion: string\n queuedAt: DateTime | null\n batchId: string | null\n}>\n```\n\n### Routes\n\nThe library provides a set of endpoints that can be found in [src/client/index.ts](/src/client/index.ts#L175) file by the `endpoints` property on line #175.\n\n### Response Structure\n\nResponses are not validated by this library, therefore you need to parse the structure on your own, referring to provided response types. If you find any incosistency, please open an issue or contact us via email.\n\nAll endpoints excerpt `userData` object that contains `remainingRequests` property, the value is an integer (of type String) that represents the number of credits available for tagging. To access exact response data in the client-side code you need to read `response.data.data`.\n\n```typescript\ntype ResponseType = {\n data: any\n userData: {\n remainingRequests: string\n }\n}\n```\n\nThis library uses Axios under the hood to make requests, so any network error will be of type `AxiosError`. Please, check [Axios documentation](https://axios-http.com/docs/handling_errors) for more information.\n\nExample of parsing an error with [Zod](https://github.com/colinhacks/zod) on the client side:\n\n```typescript\n// src/helpers/response.ts\n\nimport { z } from 'zod'\nimport { isAxiosError } from 'axios'\n\ninterface CustomError {\n status: number | null\n message: string\n field?: string\n}\n\nconst errorSchema = z.object({\n status: z.number(),\n message: z.string(),\n field: z.optional(z.string()),\n})\n\nconst notParsed: CustomError = {\n status: 500,\n message: 'Not able to parse error',\n}\n\nexport const parseError = (error: unknown) => {\n if (isAxiosError(error) && error.response !== undefined) {\n const errorParserResponse = errorSchema.safeParse(error.response.data)\n if (!errorParserResponse.success) {\n return notParsed\n }\n return errorParserResponse.data\n }\n return notParsed\n}\n```\n\n## License\n\nSee [LICENSE](LICENSE) for more information.\n","readmeFilename":"README.md"}
![\"Created](\"https://img.shields.io/badge/created%20by-AIMS%20API-8137CF\"){kind=icon}
\n![\"NPM](\"https://img.shields.io/npm/v/@aims-api/aims-tagging-node.svg\")
\n