Getting started

Getting started with the Specify SDK in your Javascript / Typescript code base.

Prerequisites

• Javascript ESM compatible runtime (browser or NodeJS)

• [Optional] Typescript >= 4.9

Installation

npm

npm install -D @specifyapp/sdk

Yarn

yarn install -D @specifyapp/sdk

The Specify SDK is still in beta and subject to API changes. Please get in touch with us on Discord if you have any question.

Create a client

import { createSpecifyClient } from '@specifyapp/sdk';

const specifyClient = createSpecifyClient();

Authenticate

In order to consume the private data from a Specify repository, you must authenticate using a personal access token.

You can generate a new PAT in your Specify user settings.

await specifyClient.authenticate('your-personal-access-token');

console.log(specifyClient.isAuthenticated); // true
console.log(specifyClient.whoAmI()); // current user

List your organization repositories

Get a list of repositories belonging to your organization.

const repositories = await specifyClient.getRepositories();

console.log(repositories); // [{ id: '...', name: '...' }, ...]

Get a SDTFClient

The SDTFClient is a class providing numerous methods to work with the design data stored using the Specify Design Token Format (SDTF).

It's the way of interacting with your tokens and generating content.

const sdtfClient = await specifyClient.getSDTFClientByRepositoryName('repository-name');

console.log(sdtfClient); // instance of SDTFClient
console.log(sdtfClient.repository) // { id: string; name: string... }

Get the SDTF JSON token tree

You would want to grab the SDTF JSON token tree of a repository anytime you want to: send the token tree over the network or debug an intermediate manipulation.

const jsonTokenTree = sdtfClient.getJSONTokenTree();

console.log(jsonTokenTree) // the object literal representation of the Specify Design Token data

Now that we know how to retrieve our SDTF, let's see how we can manipulate and retrieve our tokens.