@g123jp/ctw-box-sdk

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);