@tokens-studio/sdk/README.md

The official SDK for Tokens Studio

# Token Studio SDK

This is the official SDK for Tokens Studio.

[View technical diagram](https://www.figma.com/board/ieFpFJvKKTbAO7cUmpinig/cli-sdk?node-id=0-1&p=f&t=sykbNofJ23WFXt9B-0) which we created to showcase how the SDK & CLI work, how to create an API key, and how you can use the GraphQL Apollo Sandbox environment to play around with our API and run regular HTTP requests against it to query or mutate data.

## Quickstart

### Installation

```sh
npm install @tokens-studio/sdk
```

## CLI

See help menu for usage of the CLI.

```sh
npx tokensstudio --help
npx tokensstudio setup --help
npx tokensstudio pull --help
```

Example pulling tokens into local filesystem, after having created and filled a `.tokensstudio.json` file in the current working directory through the `setup` command:

```sh
TOKENS_STUDIO_API_KEY=your_api_key npx tokensstudio setup
TOKENS_STUDIO_API_KEY=your_api_key npx tokensstudio pull
```

> Note: if you don't pass an environment variable for the API key, the CLI will prompt you for it instead.

Which will pull the tokens from your configured org, project and branch, assuming the API key has read permissions to the tokensets in that project.

### .tokensstudio.json Example

```json
{
	"version": "2",
	"org": "1f15691a-1d96-4049-bd53-943c869ce827",
	"project": "bd5e89d5-96f3-441a-bf9c-6041d5eccebc",
	"branch": "main",
	"release": "",
	"output": "studio-export"
}
```

### Host Configuration

You can configure the GraphQL host URL in your `.tokensstudio.json` config file to avoid specifying `--host` on every command. This is useful for local development or custom Studio instances.

```json
{
	"version": "2",
	"org": "1f15691a-1d96-4049-bd53-943c869ce827",
	"project": "bd5e89d5-96f3-441a-bf9c-6041d5eccebc",
	"branch": "main",
	"release": "",
	"output": "studio-export",
	"host": "graphql.app.prod.tokens.studio"
}
```

**Precedence order**: The `--host` command-line flag takes precedence over the config file `host`, which takes precedence over the default host (`graphql.prod.tokens.studio`).

Examples:

```sh
# Uses host from config file
npx tokensstudio pull

# Overrides config file host with command-line flag
npx tokensstudio pull --host graphql.app.prod.tokens.studio
```

### Releases

When you have created a release for your project, you can specify the release property to pull tokens and executable Style Dictionary JavaScript file from that specific release.
Running this with NodeJS will build the platform outputs for you.

```json
{
	"version": "2",
	"org": "1f15691a-1d96-4049-bd53-943c869ce827",
	"project": "bd5e89d5-96f3-441a-bf9c-6041d5eccebc",
	"branch": "main",
	"release": "^1.0.0",
	"output": "studio-export"
}
```

You have a couple of options here:

- A SemVer version, which will pull from that specific version -> e.g. `"1.0.0"`
- A SemVer version range (using NPM SemVer implementation), which will pull the release with the version that is the highest satisfyable version in the specified range. -> e.g. `"^1.0.0"`
- `"latest"`, which will pull from the latest release. It does a SemVer sort

See [NPM SemVer](https://www.npmjs.com/package/semver) for more information. We use this module internally for resolving a range or "latest" to a version.

### Local backend

For Studio devs that run the Studio App backend locally:

```sh
npx tokensstudio pull --host localhost:4200 --insecure
```

If your API key was created through seeding rather than in the frontend app itself, ensure you associate the key with the correct user in the database (e.g through Prisma Studio).

## Contributing

When running tests, ensure that you run the `build` step first because the tests run the compiled CLI directly as a way to test end to end.

## Underlying GraphQL documentation

See the documentation for the GraphQL API [here](https://tokens-studio.github.io/studio-app/types/Query.html).

## Documentation

You can generate the GraphQL documentation locally with the following command (from the sdk directory). We're using [SpectaQL](https://github.com/anvilco/spectaql) to generate the docs.

```sh
npm run docs:graphql
```

You can then view them by running `open docs/graphql/index.html`

We'll publish those docs once we figure out how to host them nicely.

The old documentation is available on this [documentation site](https://tokens-studio.github.io/studio-app/).

## ESM

This library is ESM by default. We do not compile to CommonJS.

## Type secure

The entire library is built with TypeScript and provides multiple utilities to ensure type safety.

## License

This repository is published under the [MIT](LICENSE) license.