CTW BOX - Core SDK

The following is the NodeJS implementation of the SDK APIs for CTW BOX

Goal

Having a component that can be integrated in other applications to use features from ctw-box like:

• Searching for object
• Retrieving objects with permanent links
• Upoading new objects

Setup

import BoxClient from "@g123jp/ctw-box-sdk";

const boxClient = new BoxClient({
  endpoint: "https://ctwbox.stg.g123.jp/api/v1", // Change between staging and production
  accessToken: "...", // Bearer token to handle auth and permissions
});

After the client instance is created, it is recommended to use the setup command to have access to all the available categories

await boxClient.setup();

const categories = boxClient.categories; // List of categories

Available operations

.listProjects - Fetch available projects

This operation allow to list all the projects that are available under the chosen category

const projects = await boxClient.listProjects("icon");

The function takes a string as input (the id/key of the category)

.listObjects - Search objects

The search feature allows to search in CTW Box for one or more objects given a set of parameters. Follows an example in TypeScript

const options: ListObjectsOptions = {
  category: "icon",
  app_id: "auo",
  text: "image_02",
};
const { data } = await boxClient.listObjects(options);

This will retrieve a default limit of 20 objects on the page 1 within the icon workspace and the auo project. The search will be further filtered by objects containing the image_02 tag.

The following parameters are usable for search:

| name | type | default | description | | ---------------- | ------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- | | category | string | | Category (or workspace) | | app_id | string | | Project (or game) | | text | string | | Text of the search. Matches with file_name | | mime_type | string | | Object's MIME Type | | attributes | Record<string, string | number | boolean> | | Custom attributes of the object based on the category | | properties | Record<string, string | number | boolean> | | Properties of the object like the owner or the file_size | | filter | Record<string, string[]> | | Optional filters | | page | number | 1 | Page of the results pagination | | limit | number | 20 | Limit of the results pagination | | height_range | string | | Range of accepted height for the object. Ex: 300_500 | | width_range | string | | Range of accepted width for the object. Ex: 300_500 | | file_size_range | string | | Range of accepted file sizes for the object. Ex: 300_500 | | created_at_range | string | | Range of dates of creation accepted in the range for the object. Ex: 27636152_33225540152 | | updated_at_range | string | | Range of dates of update accepted in the range for the object. Ex: 27636152_33225540152 | | object_id | string | | Exact object ID to look for in any workspace in any project. all the other parameters are being ignored | | tags | string | | List of tags in stringified JSON array. |

.listObjectsFromLink - Retrieve with permanent link

With this operation, it is possibile to retrieve all the objects uploaded in a specific batch given the permanent URL

const link =
  "https://ctwbox.stg.g123.jp/?link_id=3c7d6e9ecb0a4ac9ab9aedfa0035232d";
const { data } = await boxClient.listObjectsFromLink({
  fullLink: link,
});

The supported parameters are fullLink, linkId, page and limit

| name | type | default | description | | -------- | ------ | ------- | ------------------------------- | | fullLink | string | | Complete link to the batch | | linkId | string | | Only the id of the batch upload | | page | number | 1 | Page of the results pagination | | limit | number | 1 | Limit of the results pagination |

File Upload

The following is an example of usage for uploading a file to CTW BOX with some parameters like

• Category
• Project
• Attributes Other parameters are not necessary and identified by the method, like
• Owner: already identified by the access token
• File Size: from file
• Mime Type: from file
• File Name: from file if not set

const options = {
  category: "icon",
  app_id: "auo",
  attributes: {
    style: "round",
    isTemplate: true,
  },
};

const { object_id } = await boxClient.fPutObject(file, metadata);