figma-metadata-extractor 1.0.14 → 1.0.15

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/README.md CHANGED
@@ -22,21 +22,21 @@ npm install figma-metadata-extractor
22
22
  ### Get Metadata with Auto-Downloaded Images (LLM-Ready!)
23
23
 
24
24
  ```typescript
25
- import { getFigmaMetadata } from 'figma-metadata-extractor';
25
+ import { getFigmaMetadata } from "figma-metadata-extractor";
26
26
 
27
27
  // Extract metadata AND automatically download image assets to disk
28
28
  const metadata = await getFigmaMetadata(
29
- 'https://figma.com/file/ABC123/My-Design',
29
+ "https://figma.com/file/ABC123/My-Design",
30
30
  {
31
- apiKey: 'your-figma-api-key',
32
- outputFormat: 'object',
33
- downloadImages: true, // Auto-download image assets
34
- localPath: './assets/images' // Where to save images
35
- }
31
+ apiKey: "your-figma-api-key",
32
+ outputFormat: "object",
33
+ downloadImages: true, // Auto-download image assets
34
+ localPath: "./assets/images", // Where to save images
35
+ },
36
36
  );
37
37
 
38
38
  // Nodes are enriched with downloadedImage property
39
- metadata.nodes.forEach(node => {
39
+ metadata.nodes.forEach((node) => {
40
40
  if (node.downloadedImage) {
41
41
  console.log(node.downloadedImage.filePath);
42
42
  console.log(node.downloadedImage.markdown); // ![name](path)
@@ -47,17 +47,20 @@ metadata.nodes.forEach(node => {
47
47
  ### Get Images as Buffers (No Disk Write)
48
48
 
49
49
  ```typescript
50
- import { getFigmaMetadata, enrichMetadataWithImages } from 'figma-metadata-extractor';
51
- import fs from 'fs/promises';
50
+ import {
51
+ getFigmaMetadata,
52
+ enrichMetadataWithImages,
53
+ } from "figma-metadata-extractor";
54
+ import fs from "fs/promises";
52
55
 
53
56
  // Get metadata with images as ArrayBuffers
54
57
  const result = await getFigmaMetadata(
55
- 'https://figma.com/file/ABC123/My-Design',
58
+ "https://figma.com/file/ABC123/My-Design",
56
59
  {
57
- apiKey: 'your-figma-api-key',
60
+ apiKey: "your-figma-api-key",
58
61
  downloadImages: true,
59
- returnBuffer: true // Get images as ArrayBuffer
60
- }
62
+ returnBuffer: true, // Get images as ArrayBuffer
63
+ },
61
64
  );
62
65
 
63
66
  // Images are returned separately, metadata is not enriched
@@ -75,11 +78,11 @@ for (const image of result.images) {
75
78
 
76
79
  // Optionally enrich metadata with saved file paths
77
80
  const enrichedMetadata = enrichMetadataWithImages(result, savedPaths, {
78
- useRelativePaths: true
81
+ useRelativePaths: true,
79
82
  });
80
83
 
81
84
  // Now nodes have downloadedImage properties
82
- enrichedMetadata.nodes.forEach(node => {
85
+ enrichedMetadata.nodes.forEach((node) => {
83
86
  if (node.downloadedImage) {
84
87
  console.log(node.downloadedImage.markdown);
85
88
  }
@@ -89,15 +92,15 @@ enrichedMetadata.nodes.forEach(node => {
89
92
  ### Get Metadata Only (No Downloads)
90
93
 
91
94
  ```typescript
92
- import { getFigmaMetadata } from 'figma-metadata-extractor';
95
+ import { getFigmaMetadata } from "figma-metadata-extractor";
93
96
 
94
97
  // Extract metadata from a Figma file
95
98
  const metadata = await getFigmaMetadata(
96
- 'https://figma.com/file/ABC123/My-Design',
99
+ "https://figma.com/file/ABC123/My-Design",
97
100
  {
98
- apiKey: 'your-figma-api-key',
99
- outputFormat: 'object' // or 'json' or 'yaml'
100
- }
101
+ apiKey: "your-figma-api-key",
102
+ outputFormat: "object", // or 'json' or 'yaml'
103
+ },
101
104
  );
102
105
 
103
106
  console.log(metadata.nodes); // Array of design nodes
@@ -105,35 +108,35 @@ console.log(metadata.globalVars); // Styles, colors, etc.
105
108
 
106
109
  // Download images from the file
107
110
  const images = await downloadFigmaImages(
108
- 'https://figma.com/file/ABC123/My-Design',
111
+ "https://figma.com/file/ABC123/My-Design",
109
112
  [
110
113
  {
111
- nodeId: '1234:5678',
112
- fileName: 'icon.svg'
114
+ nodeId: "1234:5678",
115
+ fileName: "icon.svg",
113
116
  },
114
117
  {
115
- nodeId: '9876:5432',
116
- fileName: 'hero-image.png'
117
- }
118
+ nodeId: "9876:5432",
119
+ fileName: "hero-image.png",
120
+ },
118
121
  ],
119
122
  {
120
- apiKey: 'your-figma-api-key',
121
- localPath: './assets/images'
122
- }
123
+ apiKey: "your-figma-api-key",
124
+ localPath: "./assets/images",
125
+ },
123
126
  );
124
127
 
125
128
  console.log(images); // Array of download results
126
129
 
127
130
  // Download a single frame image from a Figma URL
128
131
  const frameImage = await downloadFigmaFrameImage(
129
- 'https://figma.com/file/ABC123/My-Design?node-id=1234-5678',
132
+ "https://figma.com/file/ABC123/My-Design?node-id=1234-5678",
130
133
  {
131
- apiKey: 'your-figma-api-key',
132
- localPath: './assets/frames',
133
- fileName: 'my-frame.png',
134
- format: 'png', // or 'svg'
135
- pngScale: 2
136
- }
134
+ apiKey: "your-figma-api-key",
135
+ localPath: "./assets/frames",
136
+ fileName: "my-frame.png",
137
+ format: "png", // or 'svg'
138
+ pngScale: 2,
139
+ },
137
140
  );
138
141
 
139
142
  console.log(frameImage.filePath); // Path to downloaded image
@@ -146,13 +149,14 @@ console.log(frameImage.filePath); // Path to downloaded image
146
149
  Extracts comprehensive metadata from a Figma file including layout, content, visuals, and component information.
147
150
 
148
151
  **Parameters:**
152
+
149
153
  - `figmaUrl` (string): The Figma file URL
150
154
  - `options` (FigmaMetadataOptions): Configuration options
151
155
 
152
156
  **Options:**
153
- - `apiKey?: string` - Figma API key (Personal Access Token)
154
- - `oauthToken?: string` - Figma OAuth Bearer token
155
- - `useOAuth?: boolean` - Whether to use OAuth instead of API key
157
+
158
+ - `apiKey?: string` - Figma API key (Personal Access Token). Either apiKey or oauthToken is required
159
+ - `oauthToken?: string` - Figma OAuth Bearer token. When provided, OAuth is used automatically
156
160
  - `outputFormat?: 'json' | 'yaml' | 'object'` - Output format (default: 'object')
157
161
  - `depth?: number` - Maximum depth to traverse the node tree
158
162
  - `downloadImages?: boolean` - Automatically download image assets and enrich metadata (default: false)
@@ -165,6 +169,7 @@ Extracts comprehensive metadata from a Figma file including layout, content, vis
165
169
  **Returns:** Promise<FigmaMetadataResult | string>
166
170
 
167
171
  **FigmaMetadataResult:**
172
+
168
173
  ```typescript
169
174
  {
170
175
  metadata: any; // File metadata
@@ -175,13 +180,16 @@ Extracts comprehensive metadata from a Figma file including layout, content, vis
175
180
  ```
176
181
 
177
182
  When `downloadImages: true` and `returnBuffer: false`, nodes with image assets will include a `downloadedImage` property:
183
+
178
184
  ```typescript
179
185
  {
180
- filePath: string; // Absolute path
181
- relativePath: string; // Relative path for code
182
- dimensions: { width, height };
183
- markdown: string; // ![name](path)
184
- html: string; // <img src="..." />
186
+ filePath: string; // Absolute path
187
+ relativePath: string; // Relative path for code
188
+ dimensions: {
189
+ width, height;
190
+ }
191
+ markdown: string; // ![name](path)
192
+ html: string; // <img src="..." />
185
193
  }
186
194
  ```
187
195
 
@@ -192,11 +200,13 @@ When `downloadImages: true` and `returnBuffer: true`, images are returned in the
192
200
  Downloads SVG and PNG images from a Figma file.
193
201
 
194
202
  **Parameters:**
203
+
195
204
  - `figmaUrl` (string): The Figma file URL
196
205
  - `nodes` (FigmaImageNode[]): Array of image nodes to download
197
206
  - `options` (FigmaMetadataOptions & FigmaImageOptions): Configuration options
198
207
 
199
208
  **Node Properties:**
209
+
200
210
  - `nodeId: string` - The Figma node ID (format: '1234:5678')
201
211
  - `fileName: string` - Local filename (must end with .png or .svg)
202
212
  - `imageRef?: string` - Image reference for image fills
@@ -206,6 +216,7 @@ Downloads SVG and PNG images from a Figma file.
206
216
  - `filenameSuffix?: string` - Suffix for unique filenames
207
217
 
208
218
  **Additional Options:**
219
+
209
220
  - `pngScale?: number` - Export scale for PNG images (default: 2)
210
221
  - `localPath?: string` - Absolute path to save images (optional if returnBuffer is true)
211
222
  - `returnBuffer?: boolean` - Return images as ArrayBuffer instead of saving to disk (default: false)
@@ -220,6 +231,7 @@ When `returnBuffer` is true, each result will contain a `buffer` property instea
220
231
  Enriches metadata with saved image file paths after saving buffers to disk.
221
232
 
222
233
  **Parameters:**
234
+
223
235
  - `metadata` (FigmaMetadataResult): The metadata result from getFigmaMetadata with returnBuffer: true
224
236
  - `imagePaths` (string[]): Array of file paths where images were saved (must match order of metadata.images)
225
237
  - `options` (object): Configuration options
@@ -229,25 +241,27 @@ Enriches metadata with saved image file paths after saving buffers to disk.
229
241
  **Returns:** FigmaMetadataResult with enriched nodes
230
242
 
231
243
  **Example:**
244
+
232
245
  ```typescript
233
246
  // Get metadata with buffers
234
247
  const result = await getFigmaMetadata(url, {
235
- apiKey: 'key',
248
+ apiKey: "key",
236
249
  downloadImages: true,
237
- returnBuffer: true
250
+ returnBuffer: true,
238
251
  });
239
252
 
240
253
  // Save buffers to disk
241
254
  const paths = await Promise.all(
242
- result.images.map((img, i) =>
243
- fs.writeFile(`./images/img-${i}.png`, Buffer.from(img.buffer))
244
- .then(() => `./images/img-${i}.png`)
245
- )
255
+ result.images.map((img, i) =>
256
+ fs
257
+ .writeFile(`./images/img-${i}.png`, Buffer.from(img.buffer))
258
+ .then(() => `./images/img-${i}.png`),
259
+ ),
246
260
  );
247
261
 
248
262
  // Enrich metadata with file paths
249
263
  const enriched = enrichMetadataWithImages(result, paths, {
250
- useRelativePaths: true
264
+ useRelativePaths: true,
251
265
  });
252
266
  ```
253
267
 
@@ -256,13 +270,14 @@ const enriched = enrichMetadataWithImages(result, paths, {
256
270
  Downloads a single frame image from a Figma URL that contains a node-id parameter.
257
271
 
258
272
  **Parameters:**
273
+
259
274
  - `figmaUrl` (string): The Figma URL with node-id parameter (e.g., `https://figma.com/file/ABC123/My-Design?node-id=1234-5678`)
260
275
  - `options` (FigmaFrameImageOptions): Configuration options
261
276
 
262
277
  **Options:**
263
- - `apiKey?: string` - Figma API key (Personal Access Token)
264
- - `oauthToken?: string` - Figma OAuth Bearer token
265
- - `useOAuth?: boolean` - Whether to use OAuth instead of API key
278
+
279
+ - `apiKey?: string` - Figma API key (Personal Access Token). Either apiKey or oauthToken is required
280
+ - `oauthToken?: string` - Figma OAuth Bearer token. When provided, OAuth is used automatically
266
281
  - `localPath?: string` - Absolute path to save the image (optional if returnBuffer is true)
267
282
  - `fileName?: string` - Local filename (must end with .png or .svg, optional if returnBuffer is true)
268
283
  - `format?: 'png' | 'svg'` - Image format to download (default: 'png')
@@ -273,6 +288,7 @@ Downloads a single frame image from a Figma URL that contains a node-id paramete
273
288
  **Returns:** Promise<FigmaImageResult>
274
289
 
275
290
  **Result Properties:**
291
+
276
292
  - `filePath?: string` - Path to saved file (only when returnBuffer is false)
277
293
  - `buffer?: ArrayBuffer` - Image data as ArrayBuffer (only when returnBuffer is true)
278
294
  - `finalDimensions: { width: number; height: number }` - Image dimensions
@@ -281,17 +297,28 @@ Downloads a single frame image from a Figma URL that contains a node-id paramete
281
297
 
282
298
  ## Authentication
283
299
 
284
- You need either a Figma API key or OAuth token:
300
+ You need either a Figma API key (Personal Access Token) or an OAuth token:
285
301
 
286
302
  ### API Key (Personal Access Token)
303
+
287
304
  1. Go to Figma → Settings → Account → Personal Access Tokens
288
305
  2. Generate a new token
289
306
  3. Use it in the `apiKey` option
290
307
 
308
+ ```typescript
309
+ getFigmaMetadata(url, { apiKey: "figd_xxx..." });
310
+ ```
311
+
291
312
  ### OAuth Token
313
+
292
314
  1. Set up Figma OAuth in your application
293
315
  2. Use the bearer token in the `oauthToken` option
294
- 3. Set `useOAuth: true`
316
+
317
+ ```typescript
318
+ getFigmaMetadata(url, { oauthToken: "figu_xxx..." });
319
+ ```
320
+
321
+ **Note:** When `oauthToken` is provided, OAuth (Bearer auth) is used automatically. If both `apiKey` and `oauthToken` are provided, `oauthToken` takes precedence.
295
322
 
296
323
  ## Usage Examples
297
324
 
@@ -300,22 +327,25 @@ You need either a Figma API key or OAuth token:
300
327
  The easiest way to download a frame image is to copy the Figma URL directly from your browser when viewing a specific frame:
301
328
 
302
329
  ```typescript
303
- import { downloadFigmaFrameImage } from 'figma-metadata-extractor';
330
+ import { downloadFigmaFrameImage } from "figma-metadata-extractor";
304
331
 
305
332
  // Copy this URL from Figma when viewing a frame
306
- const figmaUrl = 'https://www.figma.com/design/ABC123/My-Design?node-id=1234-5678&t=xyz123';
333
+ const figmaUrl =
334
+ "https://www.figma.com/design/ABC123/My-Design?node-id=1234-5678&t=xyz123";
307
335
 
308
336
  // Save to disk
309
337
  const result = await downloadFigmaFrameImage(figmaUrl, {
310
- apiKey: 'your-figma-api-key',
311
- localPath: './downloads',
312
- fileName: 'my-frame.png',
313
- format: 'png',
314
- pngScale: 2 // High resolution
338
+ apiKey: "your-figma-api-key",
339
+ localPath: "./downloads",
340
+ fileName: "my-frame.png",
341
+ format: "png",
342
+ pngScale: 2, // High resolution
315
343
  });
316
344
 
317
345
  console.log(`Downloaded to: ${result.filePath}`);
318
- console.log(`Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`);
346
+ console.log(
347
+ `Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`,
348
+ );
319
349
  ```
320
350
 
321
351
  ### Get Frame Image as ArrayBuffer (No Disk Write)
@@ -323,19 +353,22 @@ console.log(`Dimensions: ${result.finalDimensions.width}x${result.finalDimension
323
353
  If you want to process the image in memory without saving to disk:
324
354
 
325
355
  ```typescript
326
- import { downloadFigmaFrameImage } from 'figma-metadata-extractor';
356
+ import { downloadFigmaFrameImage } from "figma-metadata-extractor";
327
357
 
328
- const figmaUrl = 'https://www.figma.com/design/ABC123/My-Design?node-id=1234-5678';
358
+ const figmaUrl =
359
+ "https://www.figma.com/design/ABC123/My-Design?node-id=1234-5678";
329
360
 
330
361
  // Get as ArrayBuffer
331
362
  const result = await downloadFigmaFrameImage(figmaUrl, {
332
- apiKey: 'your-figma-api-key',
363
+ apiKey: "your-figma-api-key",
333
364
  returnBuffer: true,
334
- format: 'png'
365
+ format: "png",
335
366
  });
336
367
 
337
368
  console.log(`Buffer size: ${result.buffer.byteLength} bytes`);
338
- console.log(`Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`);
369
+ console.log(
370
+ `Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`,
371
+ );
339
372
 
340
373
  // Use the buffer directly (e.g., upload to cloud storage, process with sharp, etc.)
341
374
  // const processedImage = await sharp(Buffer.from(result.buffer)).resize(100, 100).toBuffer();
@@ -344,39 +377,39 @@ console.log(`Dimensions: ${result.finalDimensions.width}x${result.finalDimension
344
377
  ### Download Multiple Frame Images
345
378
 
346
379
  ```typescript
347
- import { downloadFigmaImages } from 'figma-metadata-extractor';
380
+ import { downloadFigmaImages } from "figma-metadata-extractor";
348
381
 
349
382
  // For multiple frames, use the batch download function
350
383
  const results = await downloadFigmaImages(
351
- 'https://figma.com/file/ABC123/My-Design',
384
+ "https://figma.com/file/ABC123/My-Design",
352
385
  [
353
- { nodeId: '1234:5678', fileName: 'frame1.png' },
354
- { nodeId: '9876:5432', fileName: 'frame2.svg' },
355
- { nodeId: '1111:2222', fileName: 'frame3.png' }
386
+ { nodeId: "1234:5678", fileName: "frame1.png" },
387
+ { nodeId: "9876:5432", fileName: "frame2.svg" },
388
+ { nodeId: "1111:2222", fileName: "frame3.png" },
356
389
  ],
357
390
  {
358
- apiKey: 'your-figma-api-key',
359
- localPath: './frames'
360
- }
391
+ apiKey: "your-figma-api-key",
392
+ localPath: "./frames",
393
+ },
361
394
  );
362
395
  ```
363
396
 
364
397
  ### Download Multiple Images as Buffers
365
398
 
366
399
  ```typescript
367
- import { downloadFigmaImages } from 'figma-metadata-extractor';
400
+ import { downloadFigmaImages } from "figma-metadata-extractor";
368
401
 
369
402
  // Get multiple images as ArrayBuffers
370
403
  const results = await downloadFigmaImages(
371
- 'https://figma.com/file/ABC123/My-Design',
404
+ "https://figma.com/file/ABC123/My-Design",
372
405
  [
373
- { nodeId: '1234:5678', fileName: 'frame1.png' },
374
- { nodeId: '9876:5432', fileName: 'frame2.png' }
406
+ { nodeId: "1234:5678", fileName: "frame1.png" },
407
+ { nodeId: "9876:5432", fileName: "frame2.png" },
375
408
  ],
376
409
  {
377
- apiKey: 'your-figma-api-key',
378
- returnBuffer: true
379
- }
410
+ apiKey: "your-figma-api-key",
411
+ returnBuffer: true,
412
+ },
380
413
  );
381
414
 
382
415
  // Process each buffer
@@ -391,20 +424,20 @@ results.forEach((result, index) => {
391
424
  The library also exports the underlying extractor system for custom processing:
392
425
 
393
426
  ```typescript
394
- import {
395
- simplifyRawFigmaObject,
427
+ import {
428
+ simplifyRawFigmaObject,
396
429
  allExtractors,
397
430
  layoutExtractor,
398
- textExtractor
399
- } from 'figma-metadata-extractor';
431
+ textExtractor,
432
+ } from "figma-metadata-extractor";
400
433
 
401
434
  // Use specific extractors
402
- const customResult = simplifyRawFigmaObject(
403
- rawFigmaResponse,
404
- [layoutExtractor, textExtractor]
405
- );
435
+ const customResult = simplifyRawFigmaObject(rawFigmaResponse, [
436
+ layoutExtractor,
437
+ textExtractor,
438
+ ]);
406
439
  ```
407
440
 
408
441
  ## License
409
442
 
410
- MIT
443
+ MIT
package/dist/index.cjs CHANGED
@@ -386,10 +386,10 @@ class FigmaService {
386
386
  oauthToken;
387
387
  useOAuth;
388
388
  baseUrl = "https://api.figma.com/v1";
389
- constructor({ figmaApiKey, figmaOAuthToken, useOAuth }) {
390
- this.apiKey = figmaApiKey || "";
391
- this.oauthToken = figmaOAuthToken || "";
392
- this.useOAuth = !!useOAuth && !!this.oauthToken;
389
+ constructor({ figmaApiKey, figmaOAuthToken }) {
390
+ this.apiKey = figmaApiKey ?? "";
391
+ this.oauthToken = figmaOAuthToken ?? "";
392
+ this.useOAuth = !!this.oauthToken;
393
393
  }
394
394
  getAuthHeaders() {
395
395
  if (this.useOAuth) {
@@ -1525,7 +1525,6 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
1525
1525
  const {
1526
1526
  apiKey,
1527
1527
  oauthToken,
1528
- useOAuth = false,
1529
1528
  outputFormat = "object",
1530
1529
  depth,
1531
1530
  downloadImages = false,
@@ -1548,9 +1547,8 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
1548
1547
  const nodeIdMatch = figmaUrl.match(/node-id=([^&]+)/);
1549
1548
  const nodeId = nodeIdMatch ? nodeIdMatch[1].replace(/-/g, ":") : void 0;
1550
1549
  const figmaService = new FigmaService({
1551
- figmaApiKey: apiKey || "",
1552
- figmaOAuthToken: oauthToken || "",
1553
- useOAuth: useOAuth && !!oauthToken
1550
+ figmaApiKey: apiKey,
1551
+ figmaOAuthToken: oauthToken
1554
1552
  });
1555
1553
  try {
1556
1554
  Logger.log(
@@ -1645,7 +1643,6 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
1645
1643
  const {
1646
1644
  apiKey,
1647
1645
  oauthToken,
1648
- useOAuth = false,
1649
1646
  pngScale = 2,
1650
1647
  localPath,
1651
1648
  enableLogging = false,
@@ -1664,9 +1661,8 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
1664
1661
  }
1665
1662
  const fileKey = urlMatch[2];
1666
1663
  const figmaService = new FigmaService({
1667
- figmaApiKey: apiKey || "",
1668
- figmaOAuthToken: oauthToken || "",
1669
- useOAuth: useOAuth && !!oauthToken
1664
+ figmaApiKey: apiKey,
1665
+ figmaOAuthToken: oauthToken
1670
1666
  });
1671
1667
  try {
1672
1668
  const processedNodes = nodes.map((node) => ({
@@ -1694,7 +1690,6 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
1694
1690
  const {
1695
1691
  apiKey,
1696
1692
  oauthToken,
1697
- useOAuth = false,
1698
1693
  pngScale = 2,
1699
1694
  localPath,
1700
1695
  fileName,
@@ -1732,9 +1727,8 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
1732
1727
  }
1733
1728
  }
1734
1729
  const figmaService = new FigmaService({
1735
- figmaApiKey: apiKey || "",
1736
- figmaOAuthToken: oauthToken || "",
1737
- useOAuth: useOAuth && !!oauthToken
1730
+ figmaApiKey: apiKey,
1731
+ figmaOAuthToken: oauthToken
1738
1732
  });
1739
1733
  try {
1740
1734
  Logger.log(
package/dist/index.js CHANGED
@@ -384,10 +384,10 @@ class FigmaService {
384
384
  oauthToken;
385
385
  useOAuth;
386
386
  baseUrl = "https://api.figma.com/v1";
387
- constructor({ figmaApiKey, figmaOAuthToken, useOAuth }) {
388
- this.apiKey = figmaApiKey || "";
389
- this.oauthToken = figmaOAuthToken || "";
390
- this.useOAuth = !!useOAuth && !!this.oauthToken;
387
+ constructor({ figmaApiKey, figmaOAuthToken }) {
388
+ this.apiKey = figmaApiKey ?? "";
389
+ this.oauthToken = figmaOAuthToken ?? "";
390
+ this.useOAuth = !!this.oauthToken;
391
391
  }
392
392
  getAuthHeaders() {
393
393
  if (this.useOAuth) {
@@ -1523,7 +1523,6 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
1523
1523
  const {
1524
1524
  apiKey,
1525
1525
  oauthToken,
1526
- useOAuth = false,
1527
1526
  outputFormat = "object",
1528
1527
  depth,
1529
1528
  downloadImages = false,
@@ -1546,9 +1545,8 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
1546
1545
  const nodeIdMatch = figmaUrl.match(/node-id=([^&]+)/);
1547
1546
  const nodeId = nodeIdMatch ? nodeIdMatch[1].replace(/-/g, ":") : void 0;
1548
1547
  const figmaService = new FigmaService({
1549
- figmaApiKey: apiKey || "",
1550
- figmaOAuthToken: oauthToken || "",
1551
- useOAuth: useOAuth && !!oauthToken
1548
+ figmaApiKey: apiKey,
1549
+ figmaOAuthToken: oauthToken
1552
1550
  });
1553
1551
  try {
1554
1552
  Logger.log(
@@ -1643,7 +1641,6 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
1643
1641
  const {
1644
1642
  apiKey,
1645
1643
  oauthToken,
1646
- useOAuth = false,
1647
1644
  pngScale = 2,
1648
1645
  localPath,
1649
1646
  enableLogging = false,
@@ -1662,9 +1659,8 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
1662
1659
  }
1663
1660
  const fileKey = urlMatch[2];
1664
1661
  const figmaService = new FigmaService({
1665
- figmaApiKey: apiKey || "",
1666
- figmaOAuthToken: oauthToken || "",
1667
- useOAuth: useOAuth && !!oauthToken
1662
+ figmaApiKey: apiKey,
1663
+ figmaOAuthToken: oauthToken
1668
1664
  });
1669
1665
  try {
1670
1666
  const processedNodes = nodes.map((node) => ({
@@ -1692,7 +1688,6 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
1692
1688
  const {
1693
1689
  apiKey,
1694
1690
  oauthToken,
1695
- useOAuth = false,
1696
1691
  pngScale = 2,
1697
1692
  localPath,
1698
1693
  fileName,
@@ -1730,9 +1725,8 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
1730
1725
  }
1731
1726
  }
1732
1727
  const figmaService = new FigmaService({
1733
- figmaApiKey: apiKey || "",
1734
- figmaOAuthToken: oauthToken || "",
1735
- useOAuth: useOAuth && !!oauthToken
1728
+ figmaApiKey: apiKey,
1729
+ figmaOAuthToken: oauthToken
1736
1730
  });
1737
1731
  try {
1738
1732
  Logger.log(
package/dist/lib.d.ts CHANGED
@@ -1,10 +1,8 @@
1
1
  export interface FigmaMetadataOptions {
2
- /** The Figma API key (Personal Access Token) */
2
+ /** The Figma API key (Personal Access Token). Either apiKey or oauthToken must be provided. */
3
3
  apiKey?: string;
4
- /** The Figma OAuth Bearer token */
4
+ /** The Figma OAuth Bearer token. When provided, OAuth is used automatically. Preferred over apiKey if both are set. */
5
5
  oauthToken?: string;
6
- /** Whether to use OAuth instead of API key */
7
- useOAuth?: boolean;
8
6
  /** Output format for the metadata */
9
7
  outputFormat?: "json" | "yaml" | "object";
10
8
  /** Maximum depth to traverse the node tree */
@@ -72,12 +70,10 @@ export interface FigmaImageResult {
72
70
  cssVariables?: string;
73
71
  }
74
72
  export interface FigmaFrameImageOptions {
75
- /** The Figma API key (Personal Access Token) */
73
+ /** The Figma API key (Personal Access Token). Either apiKey or oauthToken must be provided. */
76
74
  apiKey?: string;
77
- /** The Figma OAuth Bearer token */
75
+ /** The Figma OAuth Bearer token. When provided, OAuth is used automatically. Preferred over apiKey if both are set. */
78
76
  oauthToken?: string;
79
- /** Whether to use OAuth instead of API key */
80
- useOAuth?: boolean;
81
77
  /** Export scale for PNG images (defaults to 2) */
82
78
  pngScale?: number;
83
79
  /** The absolute path to the directory where the image should be stored (optional if returnBuffer is true) */
@@ -1,9 +1,8 @@
1
1
  import type { GetFileResponse, GetFileNodesResponse } from "@figma/rest-api-spec";
2
2
  import { type ImageProcessingResult } from "~/utils/image-processing.js";
3
3
  export type FigmaAuthOptions = {
4
- figmaApiKey: string;
5
- figmaOAuthToken: string;
6
- useOAuth: boolean;
4
+ figmaApiKey?: string;
5
+ figmaOAuthToken?: string;
7
6
  };
8
7
  type SvgOptions = {
9
8
  outlineText: boolean;
@@ -15,7 +14,7 @@ export declare class FigmaService {
15
14
  private readonly oauthToken;
16
15
  private readonly useOAuth;
17
16
  private readonly baseUrl;
18
- constructor({ figmaApiKey, figmaOAuthToken, useOAuth }: FigmaAuthOptions);
17
+ constructor({ figmaApiKey, figmaOAuthToken }: FigmaAuthOptions);
19
18
  private getAuthHeaders;
20
19
  /**
21
20
  * Filters out null values from Figma image responses. This ensures we only work with valid image URLs.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "figma-metadata-extractor",
3
- "version": "1.0.14",
3
+ "version": "1.0.15",
4
4
  "description": "Extract metadata and download images from Figma files. A standalone library for accessing Figma design data and downloading frame images programmatically.",
5
5
  "type": "module",
6
6
  "main": "dist/index.cjs",