figma-metadata-extractor 1.0.12 → 1.0.13

package/dist/index.cjs

@@ -1537,14 +1537,25 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
     );
     let rawApiResponse;
     if (nodeId) {
-      rawApiResponse = await figmaService.getRawNode(fileKey, nodeId, depth || void 0);
+      rawApiResponse = await figmaService.getRawNode(
+        fileKey,
+        nodeId,
+        depth || void 0
+      );
     } else {
-      rawApiResponse = await figmaService.getRawFile(fileKey, depth || void 0);
+      rawApiResponse = await figmaService.getRawFile(
+        fileKey,
+        depth || void 0
+      );
     }
-    const simplifiedDesign = simplifyRawFigmaObject(rawApiResponse, allExtractors, {
-      maxDepth: depth || void 0,
-      afterChildren: collapseSvgContainers
-    });
+    const simplifiedDesign = simplifyRawFigmaObject(
+      rawApiResponse,
+      allExtractors,
+      {
+        maxDepth: depth || void 0,
+        afterChildren: collapseSvgContainers
+      }
+    );
     Logger.log(
       `Successfully extracted data: ${simplifiedDesign.nodes.length} nodes, ${Object.keys(simplifiedDesign.globalVars?.styles || {}).length} styles`
     );
@@ -1556,7 +1567,9 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
     };
     if (downloadImages) {
       if (!returnBuffer && !localPath) {
-        throw new Error("localPath is required when downloadImages is true and returnBuffer is false");
+        throw new Error(
+          "localPath is required when downloadImages is true and returnBuffer is false"
+        );
       }
       Logger.log("Discovering and downloading image assets...");
       const imageAssets = findImageAssets(nodes, globalVars);
@@ -1577,10 +1590,20 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
         );
         if (returnBuffer) {
           result.images = downloadResults;
-          Logger.log(`Successfully downloaded ${downloadResults.length} images as buffers`);
+          Logger.log(
+            `Successfully downloaded ${downloadResults.length} images as buffers`
+          );
         } else {
-          result.nodes = enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths, localPath);
-          Logger.log(`Successfully downloaded and enriched ${downloadResults.length} images`);
+          result.nodes = enrichNodesWithImages(
+            nodes,
+            imageAssets,
+            downloadResults,
+            useRelativePaths,
+            localPath
+          );
+          Logger.log(
+            `Successfully downloaded and enriched ${downloadResults.length} images`
+          );
         }
       }
     }
@@ -1598,7 +1621,15 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   }
 }
 async function downloadFigmaImages(figmaUrl, nodes, options) {
-  const { apiKey, oauthToken, useOAuth = false, pngScale = 2, localPath, enableLogging = false, returnBuffer = false } = options;
+  const {
+    apiKey,
+    oauthToken,
+    useOAuth = false,
+    pngScale = 2,
+    localPath,
+    enableLogging = false,
+    returnBuffer = false
+  } = options;
   Logger.enableLogging = enableLogging;
   if (!apiKey && !oauthToken) {
     throw new Error("Either apiKey or oauthToken is required");
@@ -1621,14 +1652,21 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
       ...node,
       nodeId: node.nodeId.replace(/-/g, ":")
     }));
-    const results = await figmaService.downloadImages(fileKey, localPath || "", processedNodes, {
-      pngScale,
-      returnBuffer
-    });
+    const results = await figmaService.downloadImages(
+      fileKey,
+      localPath || "",
+      processedNodes,
+      {
+        pngScale,
+        returnBuffer
+      }
+    );
     return results;
   } catch (error) {
     Logger.error(`Error downloading images from ${fileKey}:`, error);
-    throw new Error(`Failed to download images: ${error instanceof Error ? error.message : String(error)}`);
+    throw new Error(
+      `Failed to download images: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
 }
 async function downloadFigmaFrameImage(figmaUrl, options) {
@@ -1648,7 +1686,9 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     throw new Error("Either apiKey or oauthToken is required");
   }
   if (!returnBuffer && (!localPath || !fileName)) {
-    throw new Error("localPath and fileName are required when returnBuffer is false");
+    throw new Error(
+      "localPath and fileName are required when returnBuffer is false"
+    );
   }
   const urlMatch = figmaUrl.match(/figma\.com\/(file|design)\/([a-zA-Z0-9]+)/);
   if (!urlMatch) {
@@ -1657,13 +1697,17 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
   const fileKey = urlMatch[2];
   const nodeIdMatch = figmaUrl.match(/node-id=([^&]+)/);
   if (!nodeIdMatch) {
-    throw new Error("No frame node-id found in URL. Please provide a Figma URL with a node-id parameter (e.g., ?node-id=123-456)");
+    throw new Error(
+      "No frame node-id found in URL. Please provide a Figma URL with a node-id parameter (e.g., ?node-id=123-456)"
+    );
   }
   const nodeId = nodeIdMatch[1].replace(/-/g, ":");
   if (fileName) {
     const expectedExtension = `.${format}`;
     if (!fileName.toLowerCase().endsWith(expectedExtension)) {
-      throw new Error(`Filename must end with ${expectedExtension} for ${format} format`);
+      throw new Error(
+        `Filename must end with ${expectedExtension} for ${format} format`
+      );
     }
   }
   const figmaService = new FigmaService({
@@ -1672,27 +1716,38 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     useOAuth: useOAuth && !!oauthToken
   });
   try {
-    Logger.log(`Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`);
+    Logger.log(
+      `Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`
+    );
     const imageNode = {
       nodeId,
       fileName: fileName || `temp.${format}`
     };
-    const results = await figmaService.downloadImages(fileKey, localPath || "", [imageNode], {
-      pngScale: format === "png" ? pngScale : void 0,
-      returnBuffer
-    });
+    const results = await figmaService.downloadImages(
+      fileKey,
+      localPath || "",
+      [imageNode],
+      {
+        pngScale: format === "png" ? pngScale : void 0,
+        returnBuffer
+      }
+    );
     if (results.length === 0) {
       throw new Error(`Failed to download image for frame ${nodeId}`);
     }
     if (returnBuffer) {
       Logger.log(`Successfully downloaded frame image as buffer`);
     } else {
-      Logger.log(`Successfully downloaded frame image to: ${results[0].filePath}`);
+      Logger.log(
+        `Successfully downloaded frame image to: ${results[0].filePath}`
+      );
     }
     return results[0];
   } catch (error) {
     Logger.error(`Error downloading frame image from ${fileKey}:`, error);
-    throw new Error(`Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`);
+    throw new Error(
+      `Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
 }
 function getImageNodeInfo(metadata) {
@@ -1714,7 +1769,9 @@ function enrichMetadataWithImages(metadata, imagePaths, options = {}) {
   let downloadResults;
   if (Array.isArray(imagePaths)) {
     if (imagePaths.length !== metadata.images.length) {
-      throw new Error(`Number of image paths (${imagePaths.length}) must match number of images (${metadata.images.length})`);
+      throw new Error(
+        `Number of image paths (${imagePaths.length}) must match number of images (${metadata.images.length})`
+      );
     }
     downloadResults = imagePaths.map((filePath, index) => ({
       filePath,
@@ -1726,16 +1783,23 @@ function enrichMetadataWithImages(metadata, imagePaths, options = {}) {
     downloadResults = imageAssets.map((asset) => {
       const filePath = imagePaths[asset.id];
       if (!filePath) {
-        throw new Error(`No image path provided for node ID: ${asset.id}`);
+        return null;
       }
-      const imageMetadata = metadata.images.find((img) => img.nodeId === asset.id);
+      const imageMetadata = metadata.images.find(
+        (img) => img.nodeId === asset.id
+      );
       return {
         filePath,
-        finalDimensions: imageMetadata?.finalDimensions || { width: 0, height: 0 },
+        finalDimensions: imageMetadata?.finalDimensions || {
+          width: 0,
+          height: 0
+        },
         wasCropped: imageMetadata?.wasCropped || false,
         cssVariables: imageMetadata?.cssVariables
       };
-    });
+    }).filter(
+      (result) => result !== null
+    );
   }
   const enrichedNodes = enrichNodesWithImages(
     metadata.nodes,

package/dist/index.js

@@ -1535,14 +1535,25 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
     );
     let rawApiResponse;
     if (nodeId) {
-      rawApiResponse = await figmaService.getRawNode(fileKey, nodeId, depth || void 0);
+      rawApiResponse = await figmaService.getRawNode(
+        fileKey,
+        nodeId,
+        depth || void 0
+      );
     } else {
-      rawApiResponse = await figmaService.getRawFile(fileKey, depth || void 0);
+      rawApiResponse = await figmaService.getRawFile(
+        fileKey,
+        depth || void 0
+      );
     }
-    const simplifiedDesign = simplifyRawFigmaObject(rawApiResponse, allExtractors, {
-      maxDepth: depth || void 0,
-      afterChildren: collapseSvgContainers
-    });
+    const simplifiedDesign = simplifyRawFigmaObject(
+      rawApiResponse,
+      allExtractors,
+      {
+        maxDepth: depth || void 0,
+        afterChildren: collapseSvgContainers
+      }
+    );
     Logger.log(
       `Successfully extracted data: ${simplifiedDesign.nodes.length} nodes, ${Object.keys(simplifiedDesign.globalVars?.styles || {}).length} styles`
     );
@@ -1554,7 +1565,9 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
     };
     if (downloadImages) {
       if (!returnBuffer && !localPath) {
-        throw new Error("localPath is required when downloadImages is true and returnBuffer is false");
+        throw new Error(
+          "localPath is required when downloadImages is true and returnBuffer is false"
+        );
       }
       Logger.log("Discovering and downloading image assets...");
       const imageAssets = findImageAssets(nodes, globalVars);
@@ -1575,10 +1588,20 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
         );
         if (returnBuffer) {
           result.images = downloadResults;
-          Logger.log(`Successfully downloaded ${downloadResults.length} images as buffers`);
+          Logger.log(
+            `Successfully downloaded ${downloadResults.length} images as buffers`
+          );
         } else {
-          result.nodes = enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths, localPath);
-          Logger.log(`Successfully downloaded and enriched ${downloadResults.length} images`);
+          result.nodes = enrichNodesWithImages(
+            nodes,
+            imageAssets,
+            downloadResults,
+            useRelativePaths,
+            localPath
+          );
+          Logger.log(
+            `Successfully downloaded and enriched ${downloadResults.length} images`
+          );
         }
       }
     }
@@ -1596,7 +1619,15 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   }
 }
 async function downloadFigmaImages(figmaUrl, nodes, options) {
-  const { apiKey, oauthToken, useOAuth = false, pngScale = 2, localPath, enableLogging = false, returnBuffer = false } = options;
+  const {
+    apiKey,
+    oauthToken,
+    useOAuth = false,
+    pngScale = 2,
+    localPath,
+    enableLogging = false,
+    returnBuffer = false
+  } = options;
   Logger.enableLogging = enableLogging;
   if (!apiKey && !oauthToken) {
     throw new Error("Either apiKey or oauthToken is required");
@@ -1619,14 +1650,21 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
       ...node,
       nodeId: node.nodeId.replace(/-/g, ":")
     }));
-    const results = await figmaService.downloadImages(fileKey, localPath || "", processedNodes, {
-      pngScale,
-      returnBuffer
-    });
+    const results = await figmaService.downloadImages(
+      fileKey,
+      localPath || "",
+      processedNodes,
+      {
+        pngScale,
+        returnBuffer
+      }
+    );
     return results;
   } catch (error) {
     Logger.error(`Error downloading images from ${fileKey}:`, error);
-    throw new Error(`Failed to download images: ${error instanceof Error ? error.message : String(error)}`);
+    throw new Error(
+      `Failed to download images: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
 }
 async function downloadFigmaFrameImage(figmaUrl, options) {
@@ -1646,7 +1684,9 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     throw new Error("Either apiKey or oauthToken is required");
   }
   if (!returnBuffer && (!localPath || !fileName)) {
-    throw new Error("localPath and fileName are required when returnBuffer is false");
+    throw new Error(
+      "localPath and fileName are required when returnBuffer is false"
+    );
   }
   const urlMatch = figmaUrl.match(/figma\.com\/(file|design)\/([a-zA-Z0-9]+)/);
   if (!urlMatch) {
@@ -1655,13 +1695,17 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
   const fileKey = urlMatch[2];
   const nodeIdMatch = figmaUrl.match(/node-id=([^&]+)/);
   if (!nodeIdMatch) {
-    throw new Error("No frame node-id found in URL. Please provide a Figma URL with a node-id parameter (e.g., ?node-id=123-456)");
+    throw new Error(
+      "No frame node-id found in URL. Please provide a Figma URL with a node-id parameter (e.g., ?node-id=123-456)"
+    );
   }
   const nodeId = nodeIdMatch[1].replace(/-/g, ":");
   if (fileName) {
     const expectedExtension = `.${format}`;
     if (!fileName.toLowerCase().endsWith(expectedExtension)) {
-      throw new Error(`Filename must end with ${expectedExtension} for ${format} format`);
+      throw new Error(
+        `Filename must end with ${expectedExtension} for ${format} format`
+      );
     }
   }
   const figmaService = new FigmaService({
@@ -1670,27 +1714,38 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     useOAuth: useOAuth && !!oauthToken
   });
   try {
-    Logger.log(`Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`);
+    Logger.log(
+      `Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`
+    );
     const imageNode = {
       nodeId,
       fileName: fileName || `temp.${format}`
     };
-    const results = await figmaService.downloadImages(fileKey, localPath || "", [imageNode], {
-      pngScale: format === "png" ? pngScale : void 0,
-      returnBuffer
-    });
+    const results = await figmaService.downloadImages(
+      fileKey,
+      localPath || "",
+      [imageNode],
+      {
+        pngScale: format === "png" ? pngScale : void 0,
+        returnBuffer
+      }
+    );
     if (results.length === 0) {
       throw new Error(`Failed to download image for frame ${nodeId}`);
     }
     if (returnBuffer) {
       Logger.log(`Successfully downloaded frame image as buffer`);
     } else {
-      Logger.log(`Successfully downloaded frame image to: ${results[0].filePath}`);
+      Logger.log(
+        `Successfully downloaded frame image to: ${results[0].filePath}`
+      );
     }
     return results[0];
   } catch (error) {
     Logger.error(`Error downloading frame image from ${fileKey}:`, error);
-    throw new Error(`Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`);
+    throw new Error(
+      `Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`
+    );
   }
 }
 function getImageNodeInfo(metadata) {
@@ -1712,7 +1767,9 @@ function enrichMetadataWithImages(metadata, imagePaths, options = {}) {
   let downloadResults;
   if (Array.isArray(imagePaths)) {
     if (imagePaths.length !== metadata.images.length) {
-      throw new Error(`Number of image paths (${imagePaths.length}) must match number of images (${metadata.images.length})`);
+      throw new Error(
+        `Number of image paths (${imagePaths.length}) must match number of images (${metadata.images.length})`
+      );
     }
     downloadResults = imagePaths.map((filePath, index) => ({
       filePath,
@@ -1724,16 +1781,23 @@ function enrichMetadataWithImages(metadata, imagePaths, options = {}) {
     downloadResults = imageAssets.map((asset) => {
       const filePath = imagePaths[asset.id];
       if (!filePath) {
-        throw new Error(`No image path provided for node ID: ${asset.id}`);
+        return null;
       }
-      const imageMetadata = metadata.images.find((img) => img.nodeId === asset.id);
+      const imageMetadata = metadata.images.find(
+        (img) => img.nodeId === asset.id
+      );
       return {
         filePath,
-        finalDimensions: imageMetadata?.finalDimensions || { width: 0, height: 0 },
+        finalDimensions: imageMetadata?.finalDimensions || {
+          width: 0,
+          height: 0
+        },
         wasCropped: imageMetadata?.wasCropped || false,
         cssVariables: imageMetadata?.cssVariables
       };
-    });
+    }).filter(
+      (result) => result !== null
+    );
   }
   const enrichedNodes = enrichNodesWithImages(
     metadata.nodes,

package/dist/lib.d.ts

@@ -14,7 +14,7 @@ export interface FigmaMetadataOptions {
     /** Local path for downloaded images (required if downloadImages is true) */
     localPath?: string;
     /** Image format for downloads (defaults to 'png') */
-    imageFormat?: 'png' | 'svg';
+    imageFormat?: "png" | "svg";
     /** Export scale for PNG images (defaults to 2) */
     pngScale?: number;
     /**
@@ -85,7 +85,7 @@ export interface FigmaFrameImageOptions {
     /** The filename for the downloaded image (must end with .png or .svg, optional if returnBuffer is true) */
     fileName?: string;
     /** Image format to download (defaults to 'png') */
-    format?: 'png' | 'svg';
+    format?: "png" | "svg";
     /** Enable JSON debug log files (defaults to false) */
     enableLogging?: boolean;
     /** Return image as ArrayBuffer instead of saving to disk (defaults to false) */
@@ -99,10 +99,10 @@ export interface FigmaFrameImageOptions {
  * @returns Promise resolving to the extracted metadata
  */
 export declare function getFigmaMetadata(figmaUrl: string, options: FigmaMetadataOptions & {
-    outputFormat: 'json';
+    outputFormat: "json";
 }): Promise<string>;
 export declare function getFigmaMetadata(figmaUrl: string, options: FigmaMetadataOptions & {
-    outputFormat: 'yaml';
+    outputFormat: "yaml";
 }): Promise<string>;
 export declare function getFigmaMetadata(figmaUrl: string, options?: FigmaMetadataOptions): Promise<FigmaMetadataResult>;
 /**
@@ -155,6 +155,7 @@ export declare function getImageNodeInfo(metadata: FigmaMetadataResult): Array<{
  * Enrich metadata with saved image file paths
  *
  * Use this function after saving images from buffers to disk to add file path information to the metadata.
+ * When using the object format, missing image paths for node IDs are skipped rather than throwing errors.
  *
  * @param metadata - The metadata result from getFigmaMetadata
  * @param imagePaths - Array of file paths (ordered) OR object mapping node IDs to paths/URLs
@@ -167,6 +168,7 @@ export declare function getImageNodeInfo(metadata: FigmaMetadataResult): Array<{
  * const enriched = enrichMetadataWithImages(metadata, ['/path/to/img1.png', '/path/to/img2.png']);
  *
  * // Object format (keyed by node ID) - useful after uploading to CDN
+ * // Missing node IDs are automatically skipped
  * const enriched = enrichMetadataWithImages(metadata, {
  *   '123:456': 'https://cdn.example.com/icon.png',
  *   '789:012': 'https://cdn.example.com/logo.png'

package/package.json

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