figma-metadata-extractor 1.0.13 → 1.0.15

package/README.md

@@ -22,21 +22,21 @@ npm install figma-metadata-extractor
 ### Get Metadata with Auto-Downloaded Images (LLM-Ready!)
 
 ```typescript
-import { getFigmaMetadata } from 'figma-metadata-extractor';
+import { getFigmaMetadata } from "figma-metadata-extractor";
 
 // Extract metadata AND automatically download image assets to disk
 const metadata = await getFigmaMetadata(
-  'https://figma.com/file/ABC123/My-Design',
+  "https://figma.com/file/ABC123/My-Design",
   {
-    apiKey: 'your-figma-api-key',
-    outputFormat: 'object',
-    downloadImages: true,        // Auto-download image assets
-    localPath: './assets/images' // Where to save images
-  }
+    apiKey: "your-figma-api-key",
+    outputFormat: "object",
+    downloadImages: true, // Auto-download image assets
+    localPath: "./assets/images", // Where to save images
+  },
 );
 
 // Nodes are enriched with downloadedImage property
-metadata.nodes.forEach(node => {
+metadata.nodes.forEach((node) => {
   if (node.downloadedImage) {
     console.log(node.downloadedImage.filePath);
     console.log(node.downloadedImage.markdown); // ![name](path)
@@ -47,17 +47,20 @@ metadata.nodes.forEach(node => {
 ### Get Images as Buffers (No Disk Write)
 
 ```typescript
-import { getFigmaMetadata, enrichMetadataWithImages } from 'figma-metadata-extractor';
-import fs from 'fs/promises';
+import {
+  getFigmaMetadata,
+  enrichMetadataWithImages,
+} from "figma-metadata-extractor";
+import fs from "fs/promises";
 
 // Get metadata with images as ArrayBuffers
 const result = await getFigmaMetadata(
-  'https://figma.com/file/ABC123/My-Design',
+  "https://figma.com/file/ABC123/My-Design",
   {
-    apiKey: 'your-figma-api-key',
+    apiKey: "your-figma-api-key",
     downloadImages: true,
-    returnBuffer: true  // Get images as ArrayBuffer
-  }
+    returnBuffer: true, // Get images as ArrayBuffer
+  },
 );
 
 // Images are returned separately, metadata is not enriched
@@ -75,11 +78,11 @@ for (const image of result.images) {
 
 // Optionally enrich metadata with saved file paths
 const enrichedMetadata = enrichMetadataWithImages(result, savedPaths, {
-  useRelativePaths: true
+  useRelativePaths: true,
 });
 
 // Now nodes have downloadedImage properties
-enrichedMetadata.nodes.forEach(node => {
+enrichedMetadata.nodes.forEach((node) => {
   if (node.downloadedImage) {
     console.log(node.downloadedImage.markdown);
   }
@@ -89,15 +92,15 @@ enrichedMetadata.nodes.forEach(node => {
 ### Get Metadata Only (No Downloads)
 
 ```typescript
-import { getFigmaMetadata } from 'figma-metadata-extractor';
+import { getFigmaMetadata } from "figma-metadata-extractor";
 
 // Extract metadata from a Figma file
 const metadata = await getFigmaMetadata(
-  'https://figma.com/file/ABC123/My-Design',
+  "https://figma.com/file/ABC123/My-Design",
   {
-    apiKey: 'your-figma-api-key',
-    outputFormat: 'object' // or 'json' or 'yaml'
-  }
+    apiKey: "your-figma-api-key",
+    outputFormat: "object", // or 'json' or 'yaml'
+  },
 );
 
 console.log(metadata.nodes); // Array of design nodes
@@ -105,35 +108,35 @@ console.log(metadata.globalVars); // Styles, colors, etc.
 
 // Download images from the file
 const images = await downloadFigmaImages(
-  'https://figma.com/file/ABC123/My-Design',
+  "https://figma.com/file/ABC123/My-Design",
   [
     {
-      nodeId: '1234:5678',
-      fileName: 'icon.svg'
+      nodeId: "1234:5678",
+      fileName: "icon.svg",
     },
     {
-      nodeId: '9876:5432', 
-      fileName: 'hero-image.png'
-    }
+      nodeId: "9876:5432",
+      fileName: "hero-image.png",
+    },
   ],
   {
-    apiKey: 'your-figma-api-key',
-    localPath: './assets/images'
-  }
+    apiKey: "your-figma-api-key",
+    localPath: "./assets/images",
+  },
 );
 
 console.log(images); // Array of download results
 
 // Download a single frame image from a Figma URL
 const frameImage = await downloadFigmaFrameImage(
-  'https://figma.com/file/ABC123/My-Design?node-id=1234-5678',
+  "https://figma.com/file/ABC123/My-Design?node-id=1234-5678",
   {
-    apiKey: 'your-figma-api-key',
-    localPath: './assets/frames',
-    fileName: 'my-frame.png',
-    format: 'png', // or 'svg'
-    pngScale: 2
-  }
+    apiKey: "your-figma-api-key",
+    localPath: "./assets/frames",
+    fileName: "my-frame.png",
+    format: "png", // or 'svg'
+    pngScale: 2,
+  },
 );
 
 console.log(frameImage.filePath); // Path to downloaded image
@@ -146,13 +149,14 @@ console.log(frameImage.filePath); // Path to downloaded image
 Extracts comprehensive metadata from a Figma file including layout, content, visuals, and component information.
 
 **Parameters:**
+
 - `figmaUrl` (string): The Figma file URL
 - `options` (FigmaMetadataOptions): Configuration options
 
 **Options:**
-- `apiKey?: string` - Figma API key (Personal Access Token)
-- `oauthToken?: string` - Figma OAuth Bearer token  
-- `useOAuth?: boolean` - Whether to use OAuth instead of API key
+
+- `apiKey?: string` - Figma API key (Personal Access Token). Either apiKey or oauthToken is required
+- `oauthToken?: string` - Figma OAuth Bearer token. When provided, OAuth is used automatically
 - `outputFormat?: 'json' | 'yaml' | 'object'` - Output format (default: 'object')
 - `depth?: number` - Maximum depth to traverse the node tree
 - `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
 **Returns:** Promise<FigmaMetadataResult | string>
 
 **FigmaMetadataResult:**
+
 ```typescript
 {
   metadata: any;              // File metadata
@@ -175,13 +180,16 @@ Extracts comprehensive metadata from a Figma file including layout, content, vis
 ```
 
 When `downloadImages: true` and `returnBuffer: false`, nodes with image assets will include a `downloadedImage` property:
+
 ```typescript
 {
-  filePath: string;           // Absolute path
-  relativePath: string;       // Relative path for code
-  dimensions: { width, height };
-  markdown: string;           // ![name](path)
-  html: string;              // <img src="..." />
+  filePath: string; // Absolute path
+  relativePath: string; // Relative path for code
+  dimensions: {
+    width, height;
+  }
+  markdown: string; // ![name](path)
+  html: string; // <img src="..." />
 }
 ```
 
@@ -192,11 +200,13 @@ When `downloadImages: true` and `returnBuffer: true`, images are returned in the
 Downloads SVG and PNG images from a Figma file.
 
 **Parameters:**
+
 - `figmaUrl` (string): The Figma file URL
 - `nodes` (FigmaImageNode[]): Array of image nodes to download
 - `options` (FigmaMetadataOptions & FigmaImageOptions): Configuration options
 
 **Node Properties:**
+
 - `nodeId: string` - The Figma node ID (format: '1234:5678')
 - `fileName: string` - Local filename (must end with .png or .svg)
 - `imageRef?: string` - Image reference for image fills
@@ -206,6 +216,7 @@ Downloads SVG and PNG images from a Figma file.
 - `filenameSuffix?: string` - Suffix for unique filenames
 
 **Additional Options:**
+
 - `pngScale?: number` - Export scale for PNG images (default: 2)
 - `localPath?: string` - Absolute path to save images (optional if returnBuffer is true)
 - `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
 Enriches metadata with saved image file paths after saving buffers to disk.
 
 **Parameters:**
+
 - `metadata` (FigmaMetadataResult): The metadata result from getFigmaMetadata with returnBuffer: true
 - `imagePaths` (string[]): Array of file paths where images were saved (must match order of metadata.images)
 - `options` (object): Configuration options
@@ -229,25 +241,27 @@ Enriches metadata with saved image file paths after saving buffers to disk.
 **Returns:** FigmaMetadataResult with enriched nodes
 
 **Example:**
+
 ```typescript
 // Get metadata with buffers
 const result = await getFigmaMetadata(url, {
-  apiKey: 'key',
+  apiKey: "key",
   downloadImages: true,
-  returnBuffer: true
+  returnBuffer: true,
 });
 
 // Save buffers to disk
 const paths = await Promise.all(
-  result.images.map((img, i) => 
-    fs.writeFile(`./images/img-${i}.png`, Buffer.from(img.buffer))
-      .then(() => `./images/img-${i}.png`)
-  )
+  result.images.map((img, i) =>
+    fs
+      .writeFile(`./images/img-${i}.png`, Buffer.from(img.buffer))
+      .then(() => `./images/img-${i}.png`),
+  ),
 );
 
 // Enrich metadata with file paths
 const enriched = enrichMetadataWithImages(result, paths, {
-  useRelativePaths: true
+  useRelativePaths: true,
 });
 ```
 
@@ -256,13 +270,14 @@ const enriched = enrichMetadataWithImages(result, paths, {
 Downloads a single frame image from a Figma URL that contains a node-id parameter.
 
 **Parameters:**
+
 - `figmaUrl` (string): The Figma URL with node-id parameter (e.g., `https://figma.com/file/ABC123/My-Design?node-id=1234-5678`)
 - `options` (FigmaFrameImageOptions): Configuration options
 
 **Options:**
-- `apiKey?: string` - Figma API key (Personal Access Token)
-- `oauthToken?: string` - Figma OAuth Bearer token  
-- `useOAuth?: boolean` - Whether to use OAuth instead of API key
+
+- `apiKey?: string` - Figma API key (Personal Access Token). Either apiKey or oauthToken is required
+- `oauthToken?: string` - Figma OAuth Bearer token. When provided, OAuth is used automatically
 - `localPath?: string` - Absolute path to save the image (optional if returnBuffer is true)
 - `fileName?: string` - Local filename (must end with .png or .svg, optional if returnBuffer is true)
 - `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
 **Returns:** Promise<FigmaImageResult>
 
 **Result Properties:**
+
 - `filePath?: string` - Path to saved file (only when returnBuffer is false)
 - `buffer?: ArrayBuffer` - Image data as ArrayBuffer (only when returnBuffer is true)
 - `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
 
 ## Authentication
 
-You need either a Figma API key or OAuth token:
+You need either a Figma API key (Personal Access Token) or an OAuth token:
 
 ### API Key (Personal Access Token)
+
 1. Go to Figma → Settings → Account → Personal Access Tokens
 2. Generate a new token
 3. Use it in the `apiKey` option
 
+```typescript
+getFigmaMetadata(url, { apiKey: "figd_xxx..." });
+```
+
 ### OAuth Token
+
 1. Set up Figma OAuth in your application
 2. Use the bearer token in the `oauthToken` option
-3. Set `useOAuth: true`
+
+```typescript
+getFigmaMetadata(url, { oauthToken: "figu_xxx..." });
+```
+
+**Note:** When `oauthToken` is provided, OAuth (Bearer auth) is used automatically. If both `apiKey` and `oauthToken` are provided, `oauthToken` takes precedence.
 
 ## Usage Examples
 
@@ -300,22 +327,25 @@ You need either a Figma API key or OAuth token:
 The easiest way to download a frame image is to copy the Figma URL directly from your browser when viewing a specific frame:
 
 ```typescript
-import { downloadFigmaFrameImage } from 'figma-metadata-extractor';
+import { downloadFigmaFrameImage } from "figma-metadata-extractor";
 
 // Copy this URL from Figma when viewing a frame
-const figmaUrl = 'https://www.figma.com/design/ABC123/My-Design?node-id=1234-5678&t=xyz123';
+const figmaUrl =
+  "https://www.figma.com/design/ABC123/My-Design?node-id=1234-5678&t=xyz123";
 
 // Save to disk
 const result = await downloadFigmaFrameImage(figmaUrl, {
-  apiKey: 'your-figma-api-key',
-  localPath: './downloads',
-  fileName: 'my-frame.png',
-  format: 'png',
-  pngScale: 2 // High resolution
+  apiKey: "your-figma-api-key",
+  localPath: "./downloads",
+  fileName: "my-frame.png",
+  format: "png",
+  pngScale: 2, // High resolution
 });
 
 console.log(`Downloaded to: ${result.filePath}`);
-console.log(`Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`);
+console.log(
+  `Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`,
+);
 ```
 
 ### Get Frame Image as ArrayBuffer (No Disk Write)
@@ -323,19 +353,22 @@ console.log(`Dimensions: ${result.finalDimensions.width}x${result.finalDimension
 If you want to process the image in memory without saving to disk:
 
 ```typescript
-import { downloadFigmaFrameImage } from 'figma-metadata-extractor';
+import { downloadFigmaFrameImage } from "figma-metadata-extractor";
 
-const figmaUrl = 'https://www.figma.com/design/ABC123/My-Design?node-id=1234-5678';
+const figmaUrl =
+  "https://www.figma.com/design/ABC123/My-Design?node-id=1234-5678";
 
 // Get as ArrayBuffer
 const result = await downloadFigmaFrameImage(figmaUrl, {
-  apiKey: 'your-figma-api-key',
+  apiKey: "your-figma-api-key",
   returnBuffer: true,
-  format: 'png'
+  format: "png",
 });
 
 console.log(`Buffer size: ${result.buffer.byteLength} bytes`);
-console.log(`Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`);
+console.log(
+  `Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`,
+);
 
 // Use the buffer directly (e.g., upload to cloud storage, process with sharp, etc.)
 // 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
 ### Download Multiple Frame Images
 
 ```typescript
-import { downloadFigmaImages } from 'figma-metadata-extractor';
+import { downloadFigmaImages } from "figma-metadata-extractor";
 
 // For multiple frames, use the batch download function
 const results = await downloadFigmaImages(
-  'https://figma.com/file/ABC123/My-Design',
+  "https://figma.com/file/ABC123/My-Design",
   [
-    { nodeId: '1234:5678', fileName: 'frame1.png' },
-    { nodeId: '9876:5432', fileName: 'frame2.svg' },
-    { nodeId: '1111:2222', fileName: 'frame3.png' }
+    { nodeId: "1234:5678", fileName: "frame1.png" },
+    { nodeId: "9876:5432", fileName: "frame2.svg" },
+    { nodeId: "1111:2222", fileName: "frame3.png" },
   ],
   {
-    apiKey: 'your-figma-api-key',
-    localPath: './frames'
-  }
+    apiKey: "your-figma-api-key",
+    localPath: "./frames",
+  },
 );
 ```
 
 ### Download Multiple Images as Buffers
 
 ```typescript
-import { downloadFigmaImages } from 'figma-metadata-extractor';
+import { downloadFigmaImages } from "figma-metadata-extractor";
 
 // Get multiple images as ArrayBuffers
 const results = await downloadFigmaImages(
-  'https://figma.com/file/ABC123/My-Design',
+  "https://figma.com/file/ABC123/My-Design",
   [
-    { nodeId: '1234:5678', fileName: 'frame1.png' },
-    { nodeId: '9876:5432', fileName: 'frame2.png' }
+    { nodeId: "1234:5678", fileName: "frame1.png" },
+    { nodeId: "9876:5432", fileName: "frame2.png" },
   ],
   {
-    apiKey: 'your-figma-api-key',
-    returnBuffer: true
-  }
+    apiKey: "your-figma-api-key",
+    returnBuffer: true,
+  },
 );
 
 // Process each buffer
@@ -391,20 +424,20 @@ results.forEach((result, index) => {
 The library also exports the underlying extractor system for custom processing:
 
 ```typescript
-import { 
-  simplifyRawFigmaObject, 
+import {
+  simplifyRawFigmaObject,
   allExtractors,
   layoutExtractor,
-  textExtractor 
-} from 'figma-metadata-extractor';
+  textExtractor,
+} from "figma-metadata-extractor";
 
 // Use specific extractors
-const customResult = simplifyRawFigmaObject(
-  rawFigmaResponse, 
-  [layoutExtractor, textExtractor]
-);
+const customResult = simplifyRawFigmaObject(rawFigmaResponse, [
+  layoutExtractor,
+  textExtractor,
+]);
 ```
 
 ## License
 
-MIT
+MIT

package/dist/__vite-browser-external-Dyvby5gX.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/__vite-browser-external-l0sNRNKZ.js

@@ -0,0 +1 @@
+

package/dist/index.cjs

@@ -265,15 +265,131 @@ function formatHeadersForCurl(headers) {
   }
   return headerArgs;
 }
+async function downloadFigmaImage(fileName, localPath, imageUrl, returnBuffer = false) {
+  const { pipeline } = await Promise.resolve().then(() => require("./__vite-browser-external-Dyvby5gX.cjs"));
+  const { Readable } = await Promise.resolve().then(() => require("./__vite-browser-external-Dyvby5gX.cjs"));
+  try {
+    const response = await fetch(imageUrl, {
+      method: "GET"
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Failed to download image: ${response.status} ${response.statusText}`
+      );
+    }
+    if (!response.body) {
+      throw new Error("Response body is empty");
+    }
+    if (returnBuffer) {
+      const arrayBuffer = await response.arrayBuffer();
+      if (arrayBuffer.byteLength === 0) {
+        throw new Error("Downloaded image buffer is empty");
+      }
+      return arrayBuffer;
+    }
+    if (!fs.existsSync(localPath)) {
+      fs.mkdirSync(localPath, { recursive: true });
+    }
+    const fullPath = path.join(localPath, fileName);
+    const fileStream = fs.createWriteStream(fullPath);
+    await pipeline(Readable.fromWeb(response.body), fileStream);
+    const stats = fs.statSync(fullPath);
+    if (stats.size === 0) {
+      fs.unlinkSync(fullPath);
+      throw new Error("Downloaded file is empty (0 bytes)");
+    }
+    return fullPath;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Error downloading image: ${errorMessage}`);
+  }
+}
+function generateVarId(prefix = "var") {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  let result = "";
+  for (let i = 0; i < 6; i++) {
+    const randomIndex = Math.floor(Math.random() * chars.length);
+    result += chars[randomIndex];
+  }
+  return `${prefix}_${result}`;
+}
+function generateCSSShorthand(values, {
+  ignoreZero = true,
+  suffix = "px"
+} = {}) {
+  const { top, right, bottom, left } = values;
+  if (ignoreZero && top === 0 && right === 0 && bottom === 0 && left === 0) {
+    return void 0;
+  }
+  if (top === right && right === bottom && bottom === left) {
+    return `${top}${suffix}`;
+  }
+  if (right === left) {
+    if (top === bottom) {
+      return `${top}${suffix} ${right}${suffix}`;
+    }
+    return `${top}${suffix} ${right}${suffix} ${bottom}${suffix}`;
+  }
+  return `${top}${suffix} ${right}${suffix} ${bottom}${suffix} ${left}${suffix}`;
+}
+function isVisible(element) {
+  return element.visible ?? true;
+}
+function pixelRound(num) {
+  if (isNaN(num)) {
+    throw new TypeError(`Input must be a valid number`);
+  }
+  return Number(Number(num).toFixed(2));
+}
+async function runWithConcurrency(tasks, limit) {
+  const results = new Array(tasks.length);
+  return new Promise((resolve, reject) => {
+    if (tasks.length === 0) {
+      resolve([]);
+      return;
+    }
+    let completed = 0;
+    let launched = 0;
+    let failed = false;
+    const next = () => {
+      if (failed) return;
+      if (completed === tasks.length) {
+        resolve(results);
+        return;
+      }
+      while (launched < tasks.length && launched - completed < limit) {
+        const index = launched++;
+        tasks[index]().then((result) => {
+          results[index] = result;
+          completed++;
+          next();
+        }).catch((err) => {
+          failed = true;
+          reject(err);
+        });
+      }
+    };
+    next();
+  });
+}
+const common = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  downloadFigmaImage,
+  generateCSSShorthand,
+  generateVarId,
+  isVisible,
+  pixelRound,
+  runWithConcurrency
+}, Symbol.toStringTag, { value: "Module" }));
 class FigmaService {
   apiKey;
   oauthToken;
   useOAuth;
   baseUrl = "https://api.figma.com/v1";
-  constructor({ figmaApiKey, figmaOAuthToken, useOAuth }) {
-    this.apiKey = figmaApiKey || "";
-    this.oauthToken = figmaOAuthToken || "";
-    this.useOAuth = !!useOAuth && !!this.oauthToken;
+  constructor({ figmaApiKey, figmaOAuthToken }) {
+    this.apiKey = figmaApiKey ?? "";
+    this.oauthToken = figmaOAuthToken ?? "";
+    this.useOAuth = !!this.oauthToken;
   }
   getAuthHeaders() {
     if (this.useOAuth) {
@@ -372,6 +488,7 @@ class FigmaService {
   async downloadImages(fileKey, localPath, items, options = {}) {
     if (items.length === 0) return [];
     const { pngScale = 2, svgOptions, returnBuffer = false } = options;
+    const CONCURRENCY_LIMIT = 10;
     let resolvedPath = "";
     if (!returnBuffer) {
       const sanitizedPath = path.normalize(localPath).replace(/^(\.\.(\/|\\|$))+/, "");
@@ -391,7 +508,7 @@ class FigmaService {
     );
     if (imageFills.length > 0) {
       const fillUrls = await this.getImageFillUrls(fileKey);
-      const fillDownloads = imageFills.map(
+      const fillTasks = imageFills.map(
         ({
           imageRef,
           fileName,
@@ -406,7 +523,7 @@ class FigmaService {
             );
             return null;
           }
-          return downloadAndProcessImage(
+          return () => downloadAndProcessImage(
             fileName,
             resolvedPath,
             imageUrl,
@@ -417,10 +534,10 @@ class FigmaService {
           );
         }
       ).filter(
-        (promise) => promise !== null
+        (task) => task !== null
       );
-      if (fillDownloads.length > 0) {
-        downloadPromises.push(Promise.all(fillDownloads));
+      if (fillTasks.length > 0) {
+        downloadPromises.push(runWithConcurrency(fillTasks, CONCURRENCY_LIMIT));
       }
     }
     if (renderNodes.length > 0) {
@@ -437,7 +554,7 @@ class FigmaService {
           "png",
           { pngScale }
         );
-        const pngDownloads = pngNodes.map(
+        const pngTasks = pngNodes.map(
           ({
             nodeId,
             fileName,
@@ -452,7 +569,7 @@ class FigmaService {
               );
               return null;
             }
-            return downloadAndProcessImage(
+            return () => downloadAndProcessImage(
               fileName,
               resolvedPath,
               imageUrl,
@@ -465,10 +582,12 @@ class FigmaService {
             );
           }
         ).filter(
-          (promise) => promise !== null
+          (task) => task !== null
         );
-        if (pngDownloads.length > 0) {
-          downloadPromises.push(Promise.all(pngDownloads));
+        if (pngTasks.length > 0) {
+          downloadPromises.push(
+            runWithConcurrency(pngTasks, CONCURRENCY_LIMIT)
+          );
         }
       }
       if (svgNodes.length > 0) {
@@ -478,7 +597,7 @@ class FigmaService {
           "svg",
           { svgOptions }
         );
-        const svgDownloads = svgNodes.map(
+        const svgTasks = svgNodes.map(
           ({
             nodeId,
             fileName,
@@ -493,7 +612,7 @@ class FigmaService {
               );
               return null;
             }
-            return downloadAndProcessImage(
+            return () => downloadAndProcessImage(
               fileName,
               resolvedPath,
               imageUrl,
@@ -506,10 +625,12 @@ class FigmaService {
             );
           }
         ).filter(
-          (promise) => promise !== null
+          (task) => task !== null
         );
-        if (svgDownloads.length > 0) {
-          downloadPromises.push(Promise.all(svgDownloads));
+        if (svgTasks.length > 0) {
+          downloadPromises.push(
+            runWithConcurrency(svgTasks, CONCURRENCY_LIMIT)
+          );
         }
       }
     }
@@ -541,106 +662,6 @@ class FigmaService {
     return response;
   }
 }
-async function downloadFigmaImage(fileName, localPath, imageUrl, returnBuffer = false) {
-  try {
-    const response = await fetch(imageUrl, {
-      method: "GET"
-    });
-    if (!response.ok) {
-      throw new Error(`Failed to download image: ${response.statusText}`);
-    }
-    if (returnBuffer) {
-      const arrayBuffer = await response.arrayBuffer();
-      return arrayBuffer;
-    }
-    if (!fs.existsSync(localPath)) {
-      fs.mkdirSync(localPath, { recursive: true });
-    }
-    const fullPath = path.join(localPath, fileName);
-    const reader = response.body?.getReader();
-    if (!reader) {
-      throw new Error("Failed to get response body");
-    }
-    const writer = fs.createWriteStream(fullPath);
-    return new Promise((resolve, reject) => {
-      const processStream = async () => {
-        try {
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) {
-              writer.end();
-              break;
-            }
-            writer.write(value);
-          }
-        } catch (err) {
-          writer.end();
-          fs.unlink(fullPath, () => {
-          });
-          reject(err);
-        }
-      };
-      writer.on("finish", () => {
-        resolve(fullPath);
-      });
-      writer.on("error", (err) => {
-        reader.cancel();
-        fs.unlink(fullPath, () => {
-        });
-        reject(new Error(`Failed to write image: ${err.message}`));
-      });
-      processStream();
-    });
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(`Error downloading image: ${errorMessage}`);
-  }
-}
-function generateVarId(prefix = "var") {
-  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
-  let result = "";
-  for (let i = 0; i < 6; i++) {
-    const randomIndex = Math.floor(Math.random() * chars.length);
-    result += chars[randomIndex];
-  }
-  return `${prefix}_${result}`;
-}
-function generateCSSShorthand(values, {
-  ignoreZero = true,
-  suffix = "px"
-} = {}) {
-  const { top, right, bottom, left } = values;
-  if (ignoreZero && top === 0 && right === 0 && bottom === 0 && left === 0) {
-    return void 0;
-  }
-  if (top === right && right === bottom && bottom === left) {
-    return `${top}${suffix}`;
-  }
-  if (right === left) {
-    if (top === bottom) {
-      return `${top}${suffix} ${right}${suffix}`;
-    }
-    return `${top}${suffix} ${right}${suffix} ${bottom}${suffix}`;
-  }
-  return `${top}${suffix} ${right}${suffix} ${bottom}${suffix} ${left}${suffix}`;
-}
-function isVisible(element) {
-  return element.visible ?? true;
-}
-function pixelRound(num) {
-  if (isNaN(num)) {
-    throw new TypeError(`Input must be a valid number`);
-  }
-  return Number(Number(num).toFixed(2));
-}
-const common = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  downloadFigmaImage,
-  generateCSSShorthand,
-  generateVarId,
-  isVisible,
-  pixelRound
-}, Symbol.toStringTag, { value: "Module" }));
 function hasValue(key, obj, typeGuard) {
   const isObject = typeof obj === "object" && obj !== null;
   if (!isObject || !(key in obj)) return false;
@@ -1504,7 +1525,6 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     outputFormat = "object",
     depth,
     downloadImages = false,
@@ -1527,9 +1547,8 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   const nodeIdMatch = figmaUrl.match(/node-id=([^&]+)/);
   const nodeId = nodeIdMatch ? nodeIdMatch[1].replace(/-/g, ":") : void 0;
   const figmaService = new FigmaService({
-    figmaApiKey: apiKey || "",
-    figmaOAuthToken: oauthToken || "",
-    useOAuth: useOAuth && !!oauthToken
+    figmaApiKey: apiKey,
+    figmaOAuthToken: oauthToken
   });
   try {
     Logger.log(
@@ -1624,7 +1643,6 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     pngScale = 2,
     localPath,
     enableLogging = false,
@@ -1643,9 +1661,8 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
   }
   const fileKey = urlMatch[2];
   const figmaService = new FigmaService({
-    figmaApiKey: apiKey || "",
-    figmaOAuthToken: oauthToken || "",
-    useOAuth: useOAuth && !!oauthToken
+    figmaApiKey: apiKey,
+    figmaOAuthToken: oauthToken
   });
   try {
     const processedNodes = nodes.map((node) => ({
@@ -1673,7 +1690,6 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     pngScale = 2,
     localPath,
     fileName,
@@ -1711,9 +1727,8 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     }
   }
   const figmaService = new FigmaService({
-    figmaApiKey: apiKey || "",
-    figmaOAuthToken: oauthToken || "",
-    useOAuth: useOAuth && !!oauthToken
+    figmaApiKey: apiKey,
+    figmaOAuthToken: oauthToken
   });
   try {
     Logger.log(

package/dist/index.js

@@ -263,15 +263,131 @@ function formatHeadersForCurl(headers) {
   }
   return headerArgs;
 }
+async function downloadFigmaImage(fileName, localPath, imageUrl, returnBuffer = false) {
+  const { pipeline } = await import("./__vite-browser-external-l0sNRNKZ.js");
+  const { Readable } = await import("./__vite-browser-external-l0sNRNKZ.js");
+  try {
+    const response = await fetch(imageUrl, {
+      method: "GET"
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Failed to download image: ${response.status} ${response.statusText}`
+      );
+    }
+    if (!response.body) {
+      throw new Error("Response body is empty");
+    }
+    if (returnBuffer) {
+      const arrayBuffer = await response.arrayBuffer();
+      if (arrayBuffer.byteLength === 0) {
+        throw new Error("Downloaded image buffer is empty");
+      }
+      return arrayBuffer;
+    }
+    if (!fs.existsSync(localPath)) {
+      fs.mkdirSync(localPath, { recursive: true });
+    }
+    const fullPath = path.join(localPath, fileName);
+    const fileStream = fs.createWriteStream(fullPath);
+    await pipeline(Readable.fromWeb(response.body), fileStream);
+    const stats = fs.statSync(fullPath);
+    if (stats.size === 0) {
+      fs.unlinkSync(fullPath);
+      throw new Error("Downloaded file is empty (0 bytes)");
+    }
+    return fullPath;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new Error(`Error downloading image: ${errorMessage}`);
+  }
+}
+function generateVarId(prefix = "var") {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+  let result = "";
+  for (let i = 0; i < 6; i++) {
+    const randomIndex = Math.floor(Math.random() * chars.length);
+    result += chars[randomIndex];
+  }
+  return `${prefix}_${result}`;
+}
+function generateCSSShorthand(values, {
+  ignoreZero = true,
+  suffix = "px"
+} = {}) {
+  const { top, right, bottom, left } = values;
+  if (ignoreZero && top === 0 && right === 0 && bottom === 0 && left === 0) {
+    return void 0;
+  }
+  if (top === right && right === bottom && bottom === left) {
+    return `${top}${suffix}`;
+  }
+  if (right === left) {
+    if (top === bottom) {
+      return `${top}${suffix} ${right}${suffix}`;
+    }
+    return `${top}${suffix} ${right}${suffix} ${bottom}${suffix}`;
+  }
+  return `${top}${suffix} ${right}${suffix} ${bottom}${suffix} ${left}${suffix}`;
+}
+function isVisible(element) {
+  return element.visible ?? true;
+}
+function pixelRound(num) {
+  if (isNaN(num)) {
+    throw new TypeError(`Input must be a valid number`);
+  }
+  return Number(Number(num).toFixed(2));
+}
+async function runWithConcurrency(tasks, limit) {
+  const results = new Array(tasks.length);
+  return new Promise((resolve, reject) => {
+    if (tasks.length === 0) {
+      resolve([]);
+      return;
+    }
+    let completed = 0;
+    let launched = 0;
+    let failed = false;
+    const next = () => {
+      if (failed) return;
+      if (completed === tasks.length) {
+        resolve(results);
+        return;
+      }
+      while (launched < tasks.length && launched - completed < limit) {
+        const index = launched++;
+        tasks[index]().then((result) => {
+          results[index] = result;
+          completed++;
+          next();
+        }).catch((err) => {
+          failed = true;
+          reject(err);
+        });
+      }
+    };
+    next();
+  });
+}
+const common = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  downloadFigmaImage,
+  generateCSSShorthand,
+  generateVarId,
+  isVisible,
+  pixelRound,
+  runWithConcurrency
+}, Symbol.toStringTag, { value: "Module" }));
 class FigmaService {
   apiKey;
   oauthToken;
   useOAuth;
   baseUrl = "https://api.figma.com/v1";
-  constructor({ figmaApiKey, figmaOAuthToken, useOAuth }) {
-    this.apiKey = figmaApiKey || "";
-    this.oauthToken = figmaOAuthToken || "";
-    this.useOAuth = !!useOAuth && !!this.oauthToken;
+  constructor({ figmaApiKey, figmaOAuthToken }) {
+    this.apiKey = figmaApiKey ?? "";
+    this.oauthToken = figmaOAuthToken ?? "";
+    this.useOAuth = !!this.oauthToken;
   }
   getAuthHeaders() {
     if (this.useOAuth) {
@@ -370,6 +486,7 @@ class FigmaService {
   async downloadImages(fileKey, localPath, items, options = {}) {
     if (items.length === 0) return [];
     const { pngScale = 2, svgOptions, returnBuffer = false } = options;
+    const CONCURRENCY_LIMIT = 10;
     let resolvedPath = "";
     if (!returnBuffer) {
       const sanitizedPath = path.normalize(localPath).replace(/^(\.\.(\/|\\|$))+/, "");
@@ -389,7 +506,7 @@ class FigmaService {
     );
     if (imageFills.length > 0) {
       const fillUrls = await this.getImageFillUrls(fileKey);
-      const fillDownloads = imageFills.map(
+      const fillTasks = imageFills.map(
         ({
           imageRef,
           fileName,
@@ -404,7 +521,7 @@ class FigmaService {
             );
             return null;
           }
-          return downloadAndProcessImage(
+          return () => downloadAndProcessImage(
             fileName,
             resolvedPath,
             imageUrl,
@@ -415,10 +532,10 @@ class FigmaService {
           );
         }
       ).filter(
-        (promise) => promise !== null
+        (task) => task !== null
       );
-      if (fillDownloads.length > 0) {
-        downloadPromises.push(Promise.all(fillDownloads));
+      if (fillTasks.length > 0) {
+        downloadPromises.push(runWithConcurrency(fillTasks, CONCURRENCY_LIMIT));
       }
     }
     if (renderNodes.length > 0) {
@@ -435,7 +552,7 @@ class FigmaService {
           "png",
           { pngScale }
         );
-        const pngDownloads = pngNodes.map(
+        const pngTasks = pngNodes.map(
           ({
             nodeId,
             fileName,
@@ -450,7 +567,7 @@ class FigmaService {
               );
               return null;
             }
-            return downloadAndProcessImage(
+            return () => downloadAndProcessImage(
               fileName,
               resolvedPath,
               imageUrl,
@@ -463,10 +580,12 @@ class FigmaService {
             );
           }
         ).filter(
-          (promise) => promise !== null
+          (task) => task !== null
         );
-        if (pngDownloads.length > 0) {
-          downloadPromises.push(Promise.all(pngDownloads));
+        if (pngTasks.length > 0) {
+          downloadPromises.push(
+            runWithConcurrency(pngTasks, CONCURRENCY_LIMIT)
+          );
         }
       }
       if (svgNodes.length > 0) {
@@ -476,7 +595,7 @@ class FigmaService {
           "svg",
           { svgOptions }
         );
-        const svgDownloads = svgNodes.map(
+        const svgTasks = svgNodes.map(
           ({
             nodeId,
             fileName,
@@ -491,7 +610,7 @@ class FigmaService {
               );
               return null;
             }
-            return downloadAndProcessImage(
+            return () => downloadAndProcessImage(
               fileName,
               resolvedPath,
               imageUrl,
@@ -504,10 +623,12 @@ class FigmaService {
             );
           }
         ).filter(
-          (promise) => promise !== null
+          (task) => task !== null
         );
-        if (svgDownloads.length > 0) {
-          downloadPromises.push(Promise.all(svgDownloads));
+        if (svgTasks.length > 0) {
+          downloadPromises.push(
+            runWithConcurrency(svgTasks, CONCURRENCY_LIMIT)
+          );
         }
       }
     }
@@ -539,106 +660,6 @@ class FigmaService {
     return response;
   }
 }
-async function downloadFigmaImage(fileName, localPath, imageUrl, returnBuffer = false) {
-  try {
-    const response = await fetch(imageUrl, {
-      method: "GET"
-    });
-    if (!response.ok) {
-      throw new Error(`Failed to download image: ${response.statusText}`);
-    }
-    if (returnBuffer) {
-      const arrayBuffer = await response.arrayBuffer();
-      return arrayBuffer;
-    }
-    if (!fs.existsSync(localPath)) {
-      fs.mkdirSync(localPath, { recursive: true });
-    }
-    const fullPath = path.join(localPath, fileName);
-    const reader = response.body?.getReader();
-    if (!reader) {
-      throw new Error("Failed to get response body");
-    }
-    const writer = fs.createWriteStream(fullPath);
-    return new Promise((resolve, reject) => {
-      const processStream = async () => {
-        try {
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) {
-              writer.end();
-              break;
-            }
-            writer.write(value);
-          }
-        } catch (err) {
-          writer.end();
-          fs.unlink(fullPath, () => {
-          });
-          reject(err);
-        }
-      };
-      writer.on("finish", () => {
-        resolve(fullPath);
-      });
-      writer.on("error", (err) => {
-        reader.cancel();
-        fs.unlink(fullPath, () => {
-        });
-        reject(new Error(`Failed to write image: ${err.message}`));
-      });
-      processStream();
-    });
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(`Error downloading image: ${errorMessage}`);
-  }
-}
-function generateVarId(prefix = "var") {
-  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
-  let result = "";
-  for (let i = 0; i < 6; i++) {
-    const randomIndex = Math.floor(Math.random() * chars.length);
-    result += chars[randomIndex];
-  }
-  return `${prefix}_${result}`;
-}
-function generateCSSShorthand(values, {
-  ignoreZero = true,
-  suffix = "px"
-} = {}) {
-  const { top, right, bottom, left } = values;
-  if (ignoreZero && top === 0 && right === 0 && bottom === 0 && left === 0) {
-    return void 0;
-  }
-  if (top === right && right === bottom && bottom === left) {
-    return `${top}${suffix}`;
-  }
-  if (right === left) {
-    if (top === bottom) {
-      return `${top}${suffix} ${right}${suffix}`;
-    }
-    return `${top}${suffix} ${right}${suffix} ${bottom}${suffix}`;
-  }
-  return `${top}${suffix} ${right}${suffix} ${bottom}${suffix} ${left}${suffix}`;
-}
-function isVisible(element) {
-  return element.visible ?? true;
-}
-function pixelRound(num) {
-  if (isNaN(num)) {
-    throw new TypeError(`Input must be a valid number`);
-  }
-  return Number(Number(num).toFixed(2));
-}
-const common = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
-  __proto__: null,
-  downloadFigmaImage,
-  generateCSSShorthand,
-  generateVarId,
-  isVisible,
-  pixelRound
-}, Symbol.toStringTag, { value: "Module" }));
 function hasValue(key, obj, typeGuard) {
   const isObject = typeof obj === "object" && obj !== null;
   if (!isObject || !(key in obj)) return false;
@@ -1502,7 +1523,6 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     outputFormat = "object",
     depth,
     downloadImages = false,
@@ -1525,9 +1545,8 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   const nodeIdMatch = figmaUrl.match(/node-id=([^&]+)/);
   const nodeId = nodeIdMatch ? nodeIdMatch[1].replace(/-/g, ":") : void 0;
   const figmaService = new FigmaService({
-    figmaApiKey: apiKey || "",
-    figmaOAuthToken: oauthToken || "",
-    useOAuth: useOAuth && !!oauthToken
+    figmaApiKey: apiKey,
+    figmaOAuthToken: oauthToken
   });
   try {
     Logger.log(
@@ -1622,7 +1641,6 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     pngScale = 2,
     localPath,
     enableLogging = false,
@@ -1641,9 +1659,8 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
   }
   const fileKey = urlMatch[2];
   const figmaService = new FigmaService({
-    figmaApiKey: apiKey || "",
-    figmaOAuthToken: oauthToken || "",
-    useOAuth: useOAuth && !!oauthToken
+    figmaApiKey: apiKey,
+    figmaOAuthToken: oauthToken
   });
   try {
     const processedNodes = nodes.map((node) => ({
@@ -1671,7 +1688,6 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     pngScale = 2,
     localPath,
     fileName,
@@ -1709,9 +1725,8 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     }
   }
   const figmaService = new FigmaService({
-    figmaApiKey: apiKey || "",
-    figmaOAuthToken: oauthToken || "",
-    useOAuth: useOAuth && !!oauthToken
+    figmaApiKey: apiKey,
+    figmaOAuthToken: oauthToken
   });
   try {
     Logger.log(

package/dist/lib.d.ts

@@ -1,10 +1,8 @@
 export interface FigmaMetadataOptions {
-    /** The Figma API key (Personal Access Token) */
+    /** The Figma API key (Personal Access Token). Either apiKey or oauthToken must be provided. */
     apiKey?: string;
-    /** The Figma OAuth Bearer token */
+    /** The Figma OAuth Bearer token. When provided, OAuth is used automatically. Preferred over apiKey if both are set. */
     oauthToken?: string;
-    /** Whether to use OAuth instead of API key */
-    useOAuth?: boolean;
     /** Output format for the metadata */
     outputFormat?: "json" | "yaml" | "object";
     /** Maximum depth to traverse the node tree */
@@ -72,12 +70,10 @@ export interface FigmaImageResult {
     cssVariables?: string;
 }
 export interface FigmaFrameImageOptions {
-    /** The Figma API key (Personal Access Token) */
+    /** The Figma API key (Personal Access Token). Either apiKey or oauthToken must be provided. */
     apiKey?: string;
-    /** The Figma OAuth Bearer token */
+    /** The Figma OAuth Bearer token. When provided, OAuth is used automatically. Preferred over apiKey if both are set. */
     oauthToken?: string;
-    /** Whether to use OAuth instead of API key */
-    useOAuth?: boolean;
     /** Export scale for PNG images (defaults to 2) */
     pngScale?: number;
     /** The absolute path to the directory where the image should be stored (optional if returnBuffer is true) */

package/dist/services/figma.d.ts

@@ -1,9 +1,8 @@
 import type { GetFileResponse, GetFileNodesResponse } from "@figma/rest-api-spec";
 import { type ImageProcessingResult } from "~/utils/image-processing.js";
 export type FigmaAuthOptions = {
-    figmaApiKey: string;
-    figmaOAuthToken: string;
-    useOAuth: boolean;
+    figmaApiKey?: string;
+    figmaOAuthToken?: string;
 };
 type SvgOptions = {
     outlineText: boolean;
@@ -15,7 +14,7 @@ export declare class FigmaService {
     private readonly oauthToken;
     private readonly useOAuth;
     private readonly baseUrl;
-    constructor({ figmaApiKey, figmaOAuthToken, useOAuth }: FigmaAuthOptions);
+    constructor({ figmaApiKey, figmaOAuthToken }: FigmaAuthOptions);
     private getAuthHeaders;
     /**
      * Filters out null values from Figma image responses. This ensures we only work with valid image URLs.

package/dist/utils/common.d.ts

@@ -68,3 +68,10 @@ export declare function isVisible(element: {
  * @throws TypeError If the input is not a valid number
  */
 export declare function pixelRound(num: number): number;
+/**
+ * Run a list of async tasks with a concurrency limit
+ * @param tasks - Array of functions that return a Promise
+ * @param limit - Maximum number of concurrent tasks
+ * @returns Promise resolving to array of results
+ */
+export declare function runWithConcurrency<T>(tasks: Array<() => Promise<T>>, limit: number): Promise<T[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-metadata-extractor",
-  "version": "1.0.13",
+  "version": "1.0.15",
   "description": "Extract metadata and download images from Figma files. A standalone library for accessing Figma design data and downloading frame images programmatically.",
   "type": "module",
   "main": "dist/index.cjs",