tokens-bruecke 3.15.0 → 3.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,15 @@
1
+ ## [3.15.1](https://github.com/tokens-bruecke/figma-plugin/compare/v3.15.0...v3.15.1) (2026-10-02)
2
+
3
+ ### Bug Fixes
4
+
5
+ - **analytics:** send GoatCounter events to the tokens-bruecke site ([af40e2c](https://github.com/tokens-bruecke/figma-plugin/commit/af40e2ce77dccb91b561cb5b8a6de00a0cc33b7a))
6
+
7
+ ## [3.15.0](https://github.com/tokens-bruecke/figma-plugin/compare/v3.14.2...v3.15.0) (2026-10-02)
8
+
9
+ ### Features
10
+
11
+ - **export:** make export deterministic ([#98](https://github.com/tokens-bruecke/figma-plugin/issues/98)) ([3c0bcf4](https://github.com/tokens-bruecke/figma-plugin/commit/3c0bcf4d98c6f6ea22af335c6af498316d743f86))
12
+
1
13
  ## [3.14.2](https://github.com/tokens-bruecke/figma-plugin/compare/v3.14.1...v3.14.2) (2026-10-02)
2
14
 
3
15
  ### Bug Fixes
package/README.md CHANGED
@@ -42,6 +42,7 @@ TokensBruecke exports Figma variables and styles as design tokens JSON compatibl
42
42
  - [CLI Configuration File](#cli-configuration-file)
43
43
  - [For AI agents](#for-ai-agents)
44
44
  - [Agentic usage without the REST API](#agentic-usage-without-the-rest-api)
45
+ - [Use as a library](#use-as-a-library)
45
46
  - [Push to server](#push-to-server)
46
47
  - [JSONBin](#jsonbin)
47
48
  - [GitHub](#github)
@@ -735,6 +736,49 @@ On a bad snapshot the CLI exits `1` and names the offending key — for example
735
736
 
736
737
  ---
737
738
 
739
+ ## Use as a library
740
+
741
+ The converter is also available as a module, for build pipelines that want tokens in the same process: no child process, no files on disk, and the token is passed as an argument instead of an environment variable.
742
+
743
+ ```ts
744
+ import { fetchTokens, convertTokens } from 'tokens-bruecke/api';
745
+ import type { ExportOptions, TokensSnapshot } from 'tokens-bruecke/api';
746
+
747
+ // 1. Fetch from the Figma REST API
748
+ const tokens = await fetchTokens({
749
+ fileKey: 'abc123',
750
+ personalAccessToken: myToken, // or oauthToken
751
+ options: { colorMode: 'hex', splitByMode: true },
752
+ });
753
+
754
+ // 2. Convert data you already have
755
+ const fromSnapshot = await convertTokens(snapshot, { splitByCollection: true });
756
+ const fromRest = await convertTokens(restResponse); // GET /v1/files/:key/variables/local
757
+ ```
758
+
759
+ - **`options`** takes the same fields as the [CLI configuration file](#cli-configuration-file) and the same defaults, so the API and the CLI give identical output for the same settings.
760
+ - **Result:** one DTCG token tree when nothing is split. With `splitByCollection` it is keyed by collection name, and with `splitByMode` by `collection/mode`. See [Split results](#split-results) below for how these relate to the files the CLI writes.
761
+ - **`convertTokens`** accepts a [snapshot](#snapshot-input), or the raw response of the Figma REST variables endpoint (detected by its `meta` key). That response has no styles, so enabling any `includedStyles` with it throws `INVALID_ARGUMENT`.
762
+ - **Module formats:** the package ships an ESM and a CommonJS build of `tokens-bruecke/api`, so both `import` and `require` work. Each build has its own `TokensBrueckeError` class, so check `error.code` rather than `instanceof` if your code mixes the two.
763
+ - **No side effects:** the API does not write files, read environment variables, log or exit the process.
764
+ - **Errors** are `TokensBrueckeError`s with a `code` (`INVALID_ARGUMENT`, `INVALID_SNAPSHOT`, `FIGMA_FORBIDDEN`, `FIGMA_NOT_FOUND`, `FIGMA_RATE_LIMITED`, `FIGMA_REQUEST_FAILED`, `CONVERSION_FAILED`) and the original error as `cause`. `FIGMA_FORBIDDEN` usually means the file is not on an Enterprise plan, or the token lacks the `file_variables:read` scope.
765
+
766
+ ### Split results
767
+
768
+ For a split key, the API returns the bare token tree. The CLI writes the file as `{ "<collection>": <that tree> }`, so the tree sits in a group named after the collection. To get the same contents as a CLI file, wrap it again:
769
+
770
+ ```ts
771
+ for (const [key, tree] of Object.entries(tokens)) {
772
+ const collection = key.split('/')[0]; // simple names only, see below
773
+ const file = JSON.stringify({ [collection]: tree }, null, 2);
774
+ }
775
+ ```
776
+
777
+ - **Aliases** inside a tree are qualified with the collection name (for example `{Semantic.spacing.md}`), so the tree has to be wrapped in `{ [collection]: tree }` for references to resolve.
778
+ - **Names are raw.** The CLI replaces characters that are illegal in file names (such as `/`) in collection and mode names. The API keys keep the Figma names as they are. A collection or mode name can contain `/`, so splitting a key at the first `/` is only safe for simple names.
779
+
780
+ ---
781
+
738
782
  ## Push to server
739
783
 
740
784
  With this feature you can connect a server and push the generated JSON directly to it. At the moment the plugin supports [JSONBin](https://jsonbin.io), [GitHub](https://github.com) (direct commit or pull request), [GitLab](https://gitlab.com) and custom servers.
package/api.d.ts ADDED
@@ -0,0 +1,152 @@
1
+ /**
2
+ * Type declarations for `tokens-bruecke/api`.
3
+ *
4
+ * Kept self-contained (no ambient globals), so it can be shipped as is.
5
+ * `src/api/index.ts` imports these types, so the implementation is checked
6
+ * against what consumers see.
7
+ */
8
+
9
+ export type ColorMode =
10
+ | 'hex'
11
+ | 'rgba-object'
12
+ | 'rgba-css'
13
+ | 'srgb-dtcg'
14
+ | 'hsla-object'
15
+ | 'hsla-css'
16
+ | 'hsl-dtcg'
17
+ | 'oklch-dtcg';
18
+
19
+ export interface StyleInclusion {
20
+ isIncluded: boolean;
21
+ /** Name of the token group the styles are exported under. */
22
+ customName: string;
23
+ }
24
+
25
+ /**
26
+ * The export options. Same fields as the CLI config file
27
+ * (`schemas/cli-options.schema.json`); every field is optional and missing
28
+ * ones get the same defaults as the CLI.
29
+ */
30
+ export interface ExportOptions {
31
+ /** Each style type is merged with its default. */
32
+ includedStyles?: {
33
+ text?: Partial<StyleInclusion>;
34
+ effects?: Partial<StyleInclusion>;
35
+ grids?: Partial<StyleInclusion>;
36
+ colors?: Partial<StyleInclusion>;
37
+ };
38
+ includeScopes?: boolean;
39
+ useDTCG?: boolean;
40
+ includeValueStringKeyToAlias?: boolean;
41
+ colorMode?: ColorMode;
42
+ storeStyleInCollection?: string;
43
+ includeFigmaMetaData?: boolean;
44
+ usePercentageOpacity?: boolean;
45
+ expandEasingPresets?: boolean;
46
+ splitByCollection?: boolean;
47
+ splitByMode?: boolean;
48
+ omitCollectionNames?: boolean;
49
+ /** Leave `createdAt` out of the metadata, so unchanged files export identically. */
50
+ omitCreatedAt?: boolean;
51
+ }
52
+
53
+ /**
54
+ * A DTCG token tree. The result of `fetchTokens` and `convertTokens`:
55
+ * - one tree when nothing is split
56
+ * - keyed by collection name with `splitByCollection`
57
+ * - keyed by `collection/mode` with `splitByMode`
58
+ *
59
+ * Each split tree is bare: the CLI writes a file as `{ [collection]: tree }`,
60
+ * and aliases inside the tree are qualified with the collection name. Keys
61
+ * keep the raw Figma names, which can contain `/`, so splitting a
62
+ * `collection/mode` key is only safe for simple names.
63
+ */
64
+ export type TokenTree = Record<string, any>;
65
+
66
+ /**
67
+ * Local variables and styles in the Plugin API shapes
68
+ * (`schemas/tokens-snapshot.schema.json`). Extra properties are allowed.
69
+ */
70
+ export interface TokensSnapshot {
71
+ variableCollections: Array<{
72
+ id: string;
73
+ name: string;
74
+ modes: Array<{ modeId: string; name: string }>;
75
+ [key: string]: any;
76
+ }>;
77
+ variables: Array<{
78
+ id: string;
79
+ name: string;
80
+ variableCollectionId: string;
81
+ valuesByMode: Record<string, any>;
82
+ [key: string]: any;
83
+ }>;
84
+ paintStyles?: Array<Record<string, any>>;
85
+ textStyles?: Array<Record<string, any>>;
86
+ effectStyles?: Array<Record<string, any>>;
87
+ gridStyles?: Array<Record<string, any>>;
88
+ }
89
+
90
+ /**
91
+ * The response of `GET /v1/files/:key/variables/local`. It holds no styles,
92
+ * so converting it with any `includedStyles` enabled throws `INVALID_ARGUMENT`.
93
+ */
94
+ export interface LocalVariablesResponse {
95
+ meta: {
96
+ variables: Record<string, any>;
97
+ variableCollections: Record<string, any>;
98
+ };
99
+ [key: string]: any;
100
+ }
101
+
102
+ export interface FetchTokensParams {
103
+ fileKey: string;
104
+ /** Figma personal access token. Either this or `oauthToken` is required. */
105
+ personalAccessToken?: string;
106
+ /** Figma OAuth token. Used instead of `personalAccessToken` when both are set. */
107
+ oauthToken?: string;
108
+ options?: ExportOptions;
109
+ }
110
+
111
+ export type TokensBrueckeErrorCode =
112
+ /**
113
+ * A required argument is missing (e.g. the file key or the token), or styles
114
+ * are enabled for a REST variables response, which has none.
115
+ */
116
+ | 'INVALID_ARGUMENT'
117
+ /** The snapshot or REST response does not have the expected shape. */
118
+ | 'INVALID_SNAPSHOT'
119
+ /** 403: the Variables API needs an Enterprise plan and the `file_variables:read` scope. */
120
+ | 'FIGMA_FORBIDDEN'
121
+ /** 404: wrong file key, or the token has no access to the file. */
122
+ | 'FIGMA_NOT_FOUND'
123
+ | 'FIGMA_RATE_LIMITED'
124
+ /** Any other failed request to Figma. */
125
+ | 'FIGMA_REQUEST_FAILED'
126
+ /** The data was valid but could not be converted. */
127
+ | 'CONVERSION_FAILED';
128
+
129
+ export declare class TokensBrueckeError extends Error {
130
+ readonly code: TokensBrueckeErrorCode;
131
+ /** The original error, when there is one. */
132
+ readonly cause?: unknown;
133
+ constructor(
134
+ code: TokensBrueckeErrorCode,
135
+ message: string,
136
+ options?: { cause?: unknown }
137
+ );
138
+ }
139
+
140
+ /** Fetches the variables from the Figma REST API and converts them to tokens. */
141
+ export declare function fetchTokens(
142
+ params: FetchTokensParams
143
+ ): Promise<TokenTree>;
144
+
145
+ /**
146
+ * Converts data you already have to tokens. Accepts a snapshot, or the raw
147
+ * response of the Figma REST variables endpoint (detected by its `meta` key).
148
+ */
149
+ export declare function convertTokens(
150
+ input: TokensSnapshot | LocalVariablesResponse,
151
+ options?: ExportOptions
152
+ ): Promise<TokenTree>;