figma-metadata-extractor 1.0.14 → 1.0.16

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/index.cjs

@@ -386,10 +386,10 @@ class FigmaService {
   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) {
@@ -499,143 +499,67 @@ class FigmaService {
         );
       }
     }
-    const downloadPromises = [];
-    const imageFills = items.filter(
-      (item) => !!item.imageRef
-    );
-    const renderNodes = items.filter(
-      (item) => !!item.nodeId
-    );
-    if (imageFills.length > 0) {
-      const fillUrls = await this.getImageFillUrls(fileKey);
-      const fillTasks = imageFills.map(
-        ({
-          imageRef,
-          fileName,
-          needsCropping,
-          cropTransform,
-          requiresImageDimensions
-        }) => {
-          const imageUrl = fillUrls[imageRef];
-          if (!imageUrl) {
-            Logger.log(
-              `Skipping image fill with missing URL for imageRef: ${imageRef}`
-            );
-            return null;
-          }
-          return () => downloadAndProcessImage(
-            fileName,
-            resolvedPath,
-            imageUrl,
-            needsCropping,
-            cropTransform,
-            requiresImageDimensions,
-            returnBuffer
-          );
+    const imageRefs = [
+      ...new Set(items.map((i) => i.imageRef).filter((r) => !!r))
+    ];
+    const pngNodeIds = items.filter(
+      (i) => !i.imageRef && i.nodeId && !i.fileName.toLowerCase().endsWith(".svg")
+    ).map((i) => i.nodeId);
+    const svgNodeIds = items.filter(
+      (i) => !i.imageRef && i.nodeId && i.fileName.toLowerCase().endsWith(".svg")
+    ).map((i) => i.nodeId);
+    const [fillUrls, pngUrls, svgUrls] = await Promise.all([
+      imageRefs.length > 0 ? this.getImageFillUrls(fileKey) : Promise.resolve({}),
+      pngNodeIds.length > 0 ? this.getNodeRenderUrls(fileKey, pngNodeIds, "png", { pngScale }) : Promise.resolve({}),
+      svgNodeIds.length > 0 ? this.getNodeRenderUrls(fileKey, svgNodeIds, "svg", { svgOptions }) : Promise.resolve({})
+    ]);
+    const tasks = items.map((item) => {
+      const {
+        imageRef,
+        nodeId,
+        fileName,
+        needsCropping,
+        cropTransform,
+        requiresImageDimensions
+      } = item;
+      let imageUrl;
+      if (imageRef) {
+        imageUrl = fillUrls[imageRef];
+      } else if (nodeId) {
+        if (fileName.toLowerCase().endsWith(".svg")) {
+          imageUrl = svgUrls[nodeId];
+        } else {
+          imageUrl = pngUrls[nodeId];
         }
-      ).filter(
-        (task) => task !== null
-      );
-      if (fillTasks.length > 0) {
-        downloadPromises.push(runWithConcurrency(fillTasks, CONCURRENCY_LIMIT));
       }
-    }
-    if (renderNodes.length > 0) {
-      const pngNodes = renderNodes.filter(
-        (node) => !node.fileName.toLowerCase().endsWith(".svg")
-      );
-      const svgNodes = renderNodes.filter(
-        (node) => node.fileName.toLowerCase().endsWith(".svg")
-      );
-      if (pngNodes.length > 0) {
-        const pngUrls = await this.getNodeRenderUrls(
-          fileKey,
-          pngNodes.map((n) => n.nodeId),
-          "png",
-          { pngScale }
-        );
-        const pngTasks = pngNodes.map(
-          ({
-            nodeId,
-            fileName,
-            needsCropping,
-            cropTransform,
-            requiresImageDimensions
-          }) => {
-            const imageUrl = pngUrls[nodeId];
-            if (!imageUrl) {
-              Logger.log(
-                `Skipping PNG render with missing URL for nodeId: ${nodeId}`
-              );
-              return null;
-            }
-            return () => downloadAndProcessImage(
-              fileName,
-              resolvedPath,
-              imageUrl,
-              needsCropping,
-              cropTransform,
-              requiresImageDimensions,
-              returnBuffer
-            ).then(
-              (result) => ({ ...result, nodeId })
-            );
-          }
-        ).filter(
-          (task) => task !== null
-        );
-        if (pngTasks.length > 0) {
-          downloadPromises.push(
-            runWithConcurrency(pngTasks, CONCURRENCY_LIMIT)
+      if (!imageUrl) {
+        return () => {
+          Logger.log(
+            `Skipping missing image for ${imageRef ? `imageRef: ${imageRef}` : `nodeId: ${nodeId}`}`
           );
-        }
-      }
-      if (svgNodes.length > 0) {
-        const svgUrls = await this.getNodeRenderUrls(
-          fileKey,
-          svgNodes.map((n) => n.nodeId),
-          "svg",
-          { svgOptions }
-        );
-        const svgTasks = svgNodes.map(
-          ({
+          return Promise.resolve({
             nodeId,
-            fileName,
-            needsCropping,
-            cropTransform,
-            requiresImageDimensions
-          }) => {
-            const imageUrl = svgUrls[nodeId];
-            if (!imageUrl) {
-              Logger.log(
-                `Skipping SVG render with missing URL for nodeId: ${nodeId}`
-              );
-              return null;
-            }
-            return () => downloadAndProcessImage(
-              fileName,
-              resolvedPath,
-              imageUrl,
-              needsCropping,
-              cropTransform,
-              requiresImageDimensions,
-              returnBuffer
-            ).then(
-              (result) => ({ ...result, nodeId })
-            );
-          }
-        ).filter(
-          (task) => task !== null
-        );
-        if (svgTasks.length > 0) {
-          downloadPromises.push(
-            runWithConcurrency(svgTasks, CONCURRENCY_LIMIT)
-          );
-        }
+            originalDimensions: { width: 0, height: 0 },
+            finalDimensions: { width: 0, height: 0 },
+            wasCropped: false,
+            processingLog: ["Skipped: URL not found"]
+          });
+        };
       }
-    }
-    const results = await Promise.all(downloadPromises);
-    return results.flat();
+      return async () => {
+        const result = await downloadAndProcessImage(
+          fileName,
+          resolvedPath,
+          imageUrl,
+          needsCropping,
+          cropTransform,
+          requiresImageDimensions,
+          returnBuffer
+        );
+        return { ...result, nodeId };
+      };
+    });
+    return runWithConcurrency(tasks, CONCURRENCY_LIMIT);
   }
   /**
    * Get raw Figma API response for a file (for use with flexible extractors)
@@ -1525,7 +1449,6 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     outputFormat = "object",
     depth,
     downloadImages = false,
@@ -1548,9 +1471,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(
@@ -1598,7 +1520,11 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
       if (imageAssets.length > 0) {
         const imageNodes = imageAssets.map((asset) => ({
           nodeId: asset.id,
-          fileName: sanitizeFileName(asset.name) + `.${imageFormat}`
+          imageRef: asset.imageRef,
+          fileName: sanitizeFileName(asset.name) + (asset.filenameSuffix ? `-${asset.filenameSuffix}` : "") + `.${imageFormat}`,
+          needsCropping: asset.needsCropping,
+          cropTransform: asset.cropTransform,
+          requiresImageDimensions: asset.requiresImageDimensions
         }));
         const downloadResults = await figmaService.downloadImages(
           fileKey,
@@ -1645,7 +1571,6 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     pngScale = 2,
     localPath,
     enableLogging = false,
@@ -1664,9 +1589,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) => ({
@@ -1694,7 +1618,6 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     pngScale = 2,
     localPath,
     fileName,
@@ -1732,9 +1655,8 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     }
   }
   const figmaService = new FigmaService({
-    figmaApiKey: apiKey || "",
-    figmaOAuthToken: oauthToken || "",
-    useOAuth: useOAuth && !!oauthToken
+    figmaApiKey: apiKey,
+    figmaOAuthToken: oauthToken
   });
   try {
     Logger.log(
@@ -1837,28 +1759,37 @@ function sanitizeFileName(name) {
   return name.replace(/[^a-z0-9]/gi, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
 }
 function findImageAssets(nodes, globalVars) {
-  const images = [];
+  const assets = [];
   function traverse(node) {
-    const isImageAsset = node.type === "IMAGE-SVG" || hasImageFill(node, globalVars);
-    if (isImageAsset) {
-      images.push(node);
+    if (node.type === "IMAGE-SVG") {
+      assets.push({
+        ...node,
+        id: node.id,
+        name: node.name,
+        type: "render"
+      });
+    } else if (node.fills && typeof node.fills === "string") {
+      const fillData = globalVars?.styles?.[node.fills];
+      if (Array.isArray(fillData)) {
+        const imageFill = fillData.find((f) => f.type === "IMAGE");
+        if (imageFill) {
+          assets.push({
+            ...node,
+            id: node.id,
+            name: node.name,
+            type: "fill",
+            imageRef: imageFill.imageRef,
+            ...imageFill.imageDownloadArguments
+          });
+        }
+      }
     }
     if (node.children && Array.isArray(node.children)) {
       node.children.forEach(traverse);
     }
   }
   nodes.forEach(traverse);
-  return images;
-}
-function hasImageFill(node, globalVars) {
-  if (!node.fills || typeof node.fills !== "string") {
-    return false;
-  }
-  const fillData = globalVars?.styles?.[node.fills];
-  if (!fillData || !Array.isArray(fillData)) {
-    return false;
-  }
-  return fillData.some((fill) => fill?.type === "IMAGE");
+  return assets;
 }
 function enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths = true, localPath) {
   const imageMap = /* @__PURE__ */ new Map();

package/dist/index.js

@@ -384,10 +384,10 @@ class FigmaService {
   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) {
@@ -497,143 +497,67 @@ class FigmaService {
         );
       }
     }
-    const downloadPromises = [];
-    const imageFills = items.filter(
-      (item) => !!item.imageRef
-    );
-    const renderNodes = items.filter(
-      (item) => !!item.nodeId
-    );
-    if (imageFills.length > 0) {
-      const fillUrls = await this.getImageFillUrls(fileKey);
-      const fillTasks = imageFills.map(
-        ({
-          imageRef,
-          fileName,
-          needsCropping,
-          cropTransform,
-          requiresImageDimensions
-        }) => {
-          const imageUrl = fillUrls[imageRef];
-          if (!imageUrl) {
-            Logger.log(
-              `Skipping image fill with missing URL for imageRef: ${imageRef}`
-            );
-            return null;
-          }
-          return () => downloadAndProcessImage(
-            fileName,
-            resolvedPath,
-            imageUrl,
-            needsCropping,
-            cropTransform,
-            requiresImageDimensions,
-            returnBuffer
-          );
+    const imageRefs = [
+      ...new Set(items.map((i) => i.imageRef).filter((r) => !!r))
+    ];
+    const pngNodeIds = items.filter(
+      (i) => !i.imageRef && i.nodeId && !i.fileName.toLowerCase().endsWith(".svg")
+    ).map((i) => i.nodeId);
+    const svgNodeIds = items.filter(
+      (i) => !i.imageRef && i.nodeId && i.fileName.toLowerCase().endsWith(".svg")
+    ).map((i) => i.nodeId);
+    const [fillUrls, pngUrls, svgUrls] = await Promise.all([
+      imageRefs.length > 0 ? this.getImageFillUrls(fileKey) : Promise.resolve({}),
+      pngNodeIds.length > 0 ? this.getNodeRenderUrls(fileKey, pngNodeIds, "png", { pngScale }) : Promise.resolve({}),
+      svgNodeIds.length > 0 ? this.getNodeRenderUrls(fileKey, svgNodeIds, "svg", { svgOptions }) : Promise.resolve({})
+    ]);
+    const tasks = items.map((item) => {
+      const {
+        imageRef,
+        nodeId,
+        fileName,
+        needsCropping,
+        cropTransform,
+        requiresImageDimensions
+      } = item;
+      let imageUrl;
+      if (imageRef) {
+        imageUrl = fillUrls[imageRef];
+      } else if (nodeId) {
+        if (fileName.toLowerCase().endsWith(".svg")) {
+          imageUrl = svgUrls[nodeId];
+        } else {
+          imageUrl = pngUrls[nodeId];
         }
-      ).filter(
-        (task) => task !== null
-      );
-      if (fillTasks.length > 0) {
-        downloadPromises.push(runWithConcurrency(fillTasks, CONCURRENCY_LIMIT));
       }
-    }
-    if (renderNodes.length > 0) {
-      const pngNodes = renderNodes.filter(
-        (node) => !node.fileName.toLowerCase().endsWith(".svg")
-      );
-      const svgNodes = renderNodes.filter(
-        (node) => node.fileName.toLowerCase().endsWith(".svg")
-      );
-      if (pngNodes.length > 0) {
-        const pngUrls = await this.getNodeRenderUrls(
-          fileKey,
-          pngNodes.map((n) => n.nodeId),
-          "png",
-          { pngScale }
-        );
-        const pngTasks = pngNodes.map(
-          ({
-            nodeId,
-            fileName,
-            needsCropping,
-            cropTransform,
-            requiresImageDimensions
-          }) => {
-            const imageUrl = pngUrls[nodeId];
-            if (!imageUrl) {
-              Logger.log(
-                `Skipping PNG render with missing URL for nodeId: ${nodeId}`
-              );
-              return null;
-            }
-            return () => downloadAndProcessImage(
-              fileName,
-              resolvedPath,
-              imageUrl,
-              needsCropping,
-              cropTransform,
-              requiresImageDimensions,
-              returnBuffer
-            ).then(
-              (result) => ({ ...result, nodeId })
-            );
-          }
-        ).filter(
-          (task) => task !== null
-        );
-        if (pngTasks.length > 0) {
-          downloadPromises.push(
-            runWithConcurrency(pngTasks, CONCURRENCY_LIMIT)
+      if (!imageUrl) {
+        return () => {
+          Logger.log(
+            `Skipping missing image for ${imageRef ? `imageRef: ${imageRef}` : `nodeId: ${nodeId}`}`
           );
-        }
-      }
-      if (svgNodes.length > 0) {
-        const svgUrls = await this.getNodeRenderUrls(
-          fileKey,
-          svgNodes.map((n) => n.nodeId),
-          "svg",
-          { svgOptions }
-        );
-        const svgTasks = svgNodes.map(
-          ({
+          return Promise.resolve({
             nodeId,
-            fileName,
-            needsCropping,
-            cropTransform,
-            requiresImageDimensions
-          }) => {
-            const imageUrl = svgUrls[nodeId];
-            if (!imageUrl) {
-              Logger.log(
-                `Skipping SVG render with missing URL for nodeId: ${nodeId}`
-              );
-              return null;
-            }
-            return () => downloadAndProcessImage(
-              fileName,
-              resolvedPath,
-              imageUrl,
-              needsCropping,
-              cropTransform,
-              requiresImageDimensions,
-              returnBuffer
-            ).then(
-              (result) => ({ ...result, nodeId })
-            );
-          }
-        ).filter(
-          (task) => task !== null
-        );
-        if (svgTasks.length > 0) {
-          downloadPromises.push(
-            runWithConcurrency(svgTasks, CONCURRENCY_LIMIT)
-          );
-        }
+            originalDimensions: { width: 0, height: 0 },
+            finalDimensions: { width: 0, height: 0 },
+            wasCropped: false,
+            processingLog: ["Skipped: URL not found"]
+          });
+        };
       }
-    }
-    const results = await Promise.all(downloadPromises);
-    return results.flat();
+      return async () => {
+        const result = await downloadAndProcessImage(
+          fileName,
+          resolvedPath,
+          imageUrl,
+          needsCropping,
+          cropTransform,
+          requiresImageDimensions,
+          returnBuffer
+        );
+        return { ...result, nodeId };
+      };
+    });
+    return runWithConcurrency(tasks, CONCURRENCY_LIMIT);
   }
   /**
    * Get raw Figma API response for a file (for use with flexible extractors)
@@ -1523,7 +1447,6 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     outputFormat = "object",
     depth,
     downloadImages = false,
@@ -1546,9 +1469,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(
@@ -1596,7 +1518,11 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
       if (imageAssets.length > 0) {
         const imageNodes = imageAssets.map((asset) => ({
           nodeId: asset.id,
-          fileName: sanitizeFileName(asset.name) + `.${imageFormat}`
+          imageRef: asset.imageRef,
+          fileName: sanitizeFileName(asset.name) + (asset.filenameSuffix ? `-${asset.filenameSuffix}` : "") + `.${imageFormat}`,
+          needsCropping: asset.needsCropping,
+          cropTransform: asset.cropTransform,
+          requiresImageDimensions: asset.requiresImageDimensions
         }));
         const downloadResults = await figmaService.downloadImages(
           fileKey,
@@ -1643,7 +1569,6 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     pngScale = 2,
     localPath,
     enableLogging = false,
@@ -1662,9 +1587,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) => ({
@@ -1692,7 +1616,6 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
   const {
     apiKey,
     oauthToken,
-    useOAuth = false,
     pngScale = 2,
     localPath,
     fileName,
@@ -1730,9 +1653,8 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     }
   }
   const figmaService = new FigmaService({
-    figmaApiKey: apiKey || "",
-    figmaOAuthToken: oauthToken || "",
-    useOAuth: useOAuth && !!oauthToken
+    figmaApiKey: apiKey,
+    figmaOAuthToken: oauthToken
   });
   try {
     Logger.log(
@@ -1835,28 +1757,37 @@ function sanitizeFileName(name) {
   return name.replace(/[^a-z0-9]/gi, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
 }
 function findImageAssets(nodes, globalVars) {
-  const images = [];
+  const assets = [];
   function traverse(node) {
-    const isImageAsset = node.type === "IMAGE-SVG" || hasImageFill(node, globalVars);
-    if (isImageAsset) {
-      images.push(node);
+    if (node.type === "IMAGE-SVG") {
+      assets.push({
+        ...node,
+        id: node.id,
+        name: node.name,
+        type: "render"
+      });
+    } else if (node.fills && typeof node.fills === "string") {
+      const fillData = globalVars?.styles?.[node.fills];
+      if (Array.isArray(fillData)) {
+        const imageFill = fillData.find((f) => f.type === "IMAGE");
+        if (imageFill) {
+          assets.push({
+            ...node,
+            id: node.id,
+            name: node.name,
+            type: "fill",
+            imageRef: imageFill.imageRef,
+            ...imageFill.imageDownloadArguments
+          });
+        }
+      }
     }
     if (node.children && Array.isArray(node.children)) {
       node.children.forEach(traverse);
     }
   }
   nodes.forEach(traverse);
-  return images;
-}
-function hasImageFill(node, globalVars) {
-  if (!node.fills || typeof node.fills !== "string") {
-    return false;
-  }
-  const fillData = globalVars?.styles?.[node.fills];
-  if (!fillData || !Array.isArray(fillData)) {
-    return false;
-  }
-  return fillData.some((fill) => fill?.type === "IMAGE");
+  return assets;
 }
 function enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths = true, localPath) {
   const imageMap = /* @__PURE__ */ new Map();

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-metadata-extractor",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "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",