# Specify SDK Cheatsheet

## Creating Specify and SDTF clients

You will first create a Specify client, then authenticate, then create a SDTF client by fetching the repository token tree.

```typescript
import { createSpecifyClient } from "@specifyapp/sdk";

const specifyClient = createSpecifyClient();
await specifyClient.authenticate("<YOUR_PERSONAL_ACCESS_TOKEN_VAR>");

const sdtfClient = 
  await specifyClient.getSDTFClientByRepositoryName("<YOUR_SPECIFY_REPO_NAME>");
  
  console.log('Repository name',sdtfClient.repository.name)
```

## Updating tokens

The following example is only an overview, if you need more details you can have a look [here](/guides/specify-sdk-usage-101/update-the-tokens.md).

```typescript
import { updaters } from '@specifyapp/sdk'

sdtfClient.update(
  updaters.color({ toFormat: 'hex' }, { where: { token: '^color-' }}),
);
```

## Convert a token to XXX

The following example is only an overview, if you need more details you can have a look [here](#convert-a-token-to-xxx).

```typescript
import {
  dimensionToCss,
  breakpointToCss,
  colorToCss,
  createResolveAliasStrategy 
} from '@specify/sdk/css'

const strategy = createResolveAliasStrategy();

const outputs = sdtfClient.mapTokenStates(tokenState => 
  tokenState.matchByType(
    {
      dimension: dimensionToCss(strategy) // Output example: '12px'
      breakpoint: breakpointToCss(strategy) // Output example: '12px'
      color: colorToCss(strategy) // Output example: '#ff00ff'
    }, 
    _ => undefined
  )
);
```

## Execute a parser

The following example is only an overview, if you need more details you can have a look [here](/guides/specify-sdk-usage-101/executing-parsers.md).

```typescript
import { parsers } from '@specify/sdk'

const executePipelines = sdtfClient
  .createParsersPipelines(
    parsers.toCssCustomProperties({ filePath: 'myFile.css' }),
  );
const parsersEngineResults = await executePipelines();
```

## Retrieving data

### Get a specific token

```typescript
const tokenState = sdtfClient.getTokenState(['path', 'to', 'token']);
```

### Get all the tokens

```typescript
const tokenStates = sdtfClient.getAllTokenStates();
```

### Map over all the tokens

```ts
const results = sdtfClient.mapTokenStates(tokenState => ...);
```

### Get a specific group

```typescript
const group = sdtfClient.getGroupState(['path', 'to', 'myGroup']);
```

### Get all the groups

```typescript
const groups = sdtfClient.getAllGroupStates();
```

### Map over all the groups

```ts
const results = sdtfClient.mapGroupStates(tokenState => ...);
```

### Get a specific collection

```typescript
const collection = sdtfClient.getCollectionState(['path', 'to', 'myCollection']);
```

### Get all collections

```typescript
const collections = sdtfClient.getAllCollectionStates();
```

### Map over all the collections

```ts
const results = sdtfClient.mapCollectionStates(tokenState => ...);
```

## Filtering data

### Keeping a sub-graph from a path

If you only want a specific portion of the graph, you can cherry-pick using the `pick` function:

```typescript
const colors = sdtfClient.pick(['colors']);
```

### Keeping the children of a path

If you only want the children of a specific portion of the graph you can use the `pick` function this way:

```typescript
const colors = sdtfClient.pick(['colors', '*']);
```

### Query a specific set of data

You can use the `query` method of the `SDTFClient` to create a copy of the current SDTF with only the tokens that'll match your query:

```ts
const colorAndTextStyleOnlySdtf = sdtfClient.query({
  where: {
    token: '.*',
    withTypes: {
      include: ['color', 'textStyle']
    }
  }
});
```

You can find all the details about querying the data [here](/guides/querying-a-sdtf-graph.md).

### Remove tokens from the SDTF

You can use the `remove` method to delete tokens based on a query:

```typescript
sdtfClient
  .remove({ where: { token: '^Blue$', select: true } })
```

## Renaming tokens

### Rename a node

By not specifying any type, the method will rename any node as long as the path is valid.

```typescript
sdtfClient.renameNode({ atPath: ['my', 'path' ], name: 'newName' });
```

### Rename a collection

By specifying the type, the method will rename only a collection node.

```typescript
sdtfClient.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'collection'
});
```

### Rename a group

By specifying the type, the method will rename only a group node.

```typescript
sdtf.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'group'
});
```

### Rename a token

By specifying the type, the method will rename only a token node.

```typescript
sdtf.renameNode({ 
  atPath: ['my', 'path' ],
  name: 'newName',
  type: 'token'
});
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.specifyapp.com/guides/specify-sdk-cheatsheet.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.