figma-metadata-extractor 1.0.11 → 1.0.13

package/dist/index.cjs

@@ -289,15 +289,20 @@ class FigmaService {
    */
   filterValidImages(images) {
     if (!images) return {};
-    return Object.fromEntries(Object.entries(images).filter(([, value]) => !!value));
+    return Object.fromEntries(
+      Object.entries(images).filter(([, value]) => !!value)
+    );
   }
   async request(endpoint) {
     try {
       Logger.log(`Calling ${this.baseUrl}${endpoint}`);
       const headers = this.getAuthHeaders();
-      return await fetchWithRetry(`${this.baseUrl}${endpoint}`, {
-        headers
-      });
+      return await fetchWithRetry(
+        `${this.baseUrl}${endpoint}`,
+        {
+          headers
+        }
+      );
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new Error(
@@ -372,7 +377,9 @@ class FigmaService {
       const sanitizedPath = path.normalize(localPath).replace(/^(\.\.(\/|\\|$))+/, "");
       resolvedPath = path.resolve(sanitizedPath);
       if (!resolvedPath.startsWith(path.resolve(process.cwd()))) {
-        throw new Error("Invalid path specified. Directory traversal is not allowed.");
+        throw new Error(
+          "Invalid path specified. Directory traversal is not allowed."
+        );
       }
     }
     const downloadPromises = [];
@@ -384,25 +391,45 @@ class FigmaService {
     );
     if (imageFills.length > 0) {
       const fillUrls = await this.getImageFillUrls(fileKey);
-      const fillDownloads = imageFills.map(({ imageRef, fileName, needsCropping, cropTransform, requiresImageDimensions }) => {
-        const imageUrl = fillUrls[imageRef];
-        return imageUrl ? downloadAndProcessImage(
+      const fillDownloads = imageFills.map(
+        ({
+          imageRef,
           fileName,
-          resolvedPath,
-          imageUrl,
           needsCropping,
           cropTransform,
-          requiresImageDimensions,
-          returnBuffer
-        ) : null;
-      }).filter((promise) => promise !== null);
+          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
+          );
+        }
+      ).filter(
+        (promise) => promise !== null
+      );
       if (fillDownloads.length > 0) {
         downloadPromises.push(Promise.all(fillDownloads));
       }
     }
     if (renderNodes.length > 0) {
-      const pngNodes = renderNodes.filter((node) => !node.fileName.toLowerCase().endsWith(".svg"));
-      const svgNodes = renderNodes.filter((node) => node.fileName.toLowerCase().endsWith(".svg"));
+      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,
@@ -410,18 +437,36 @@ class FigmaService {
           "png",
           { pngScale }
         );
-        const pngDownloads = pngNodes.map(({ nodeId, fileName, needsCropping, cropTransform, requiresImageDimensions }) => {
-          const imageUrl = pngUrls[nodeId];
-          return imageUrl ? downloadAndProcessImage(
+        const pngDownloads = pngNodes.map(
+          ({
+            nodeId,
             fileName,
-            resolvedPath,
-            imageUrl,
             needsCropping,
             cropTransform,
-            requiresImageDimensions,
-            returnBuffer
-          ).then((result) => ({ ...result, nodeId })) : null;
-        }).filter((promise) => promise !== null);
+            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(
+          (promise) => promise !== null
+        );
         if (pngDownloads.length > 0) {
           downloadPromises.push(Promise.all(pngDownloads));
         }
@@ -433,18 +478,36 @@ class FigmaService {
           "svg",
           { svgOptions }
         );
-        const svgDownloads = svgNodes.map(({ nodeId, fileName, needsCropping, cropTransform, requiresImageDimensions }) => {
-          const imageUrl = svgUrls[nodeId];
-          return imageUrl ? downloadAndProcessImage(
+        const svgDownloads = svgNodes.map(
+          ({
+            nodeId,
             fileName,
-            resolvedPath,
-            imageUrl,
             needsCropping,
             cropTransform,
-            requiresImageDimensions,
-            returnBuffer
-          ).then((result) => ({ ...result, nodeId })) : null;
-        }).filter((promise) => promise !== null);
+            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(
+          (promise) => promise !== null
+        );
         if (svgDownloads.length > 0) {
           downloadPromises.push(Promise.all(svgDownloads));
         }
@@ -458,7 +521,9 @@ class FigmaService {
    */
   async getRawFile(fileKey, depth) {
     const endpoint = `/files/${fileKey}${depth ? `?depth=${depth}` : ""}`;
-    Logger.log(`Retrieving raw Figma file: ${fileKey} (depth: ${depth ?? "default"})`);
+    Logger.log(
+      `Retrieving raw Figma file: ${fileKey} (depth: ${depth ?? "default"})`
+    );
     const response = await this.request(endpoint);
     writeLogs("figma-raw.json", response);
     return response;
@@ -1472,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`
     );
@@ -1491,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);
@@ -1512,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`
+          );
         }
       }
     }
@@ -1533,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");
@@ -1556,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) {
@@ -1583,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) {
@@ -1592,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({
@@ -1607,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) {
@@ -1649,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,
@@ -1661,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

@@ -287,15 +287,20 @@ class FigmaService {
    */
   filterValidImages(images) {
     if (!images) return {};
-    return Object.fromEntries(Object.entries(images).filter(([, value]) => !!value));
+    return Object.fromEntries(
+      Object.entries(images).filter(([, value]) => !!value)
+    );
   }
   async request(endpoint) {
     try {
       Logger.log(`Calling ${this.baseUrl}${endpoint}`);
       const headers = this.getAuthHeaders();
-      return await fetchWithRetry(`${this.baseUrl}${endpoint}`, {
-        headers
-      });
+      return await fetchWithRetry(
+        `${this.baseUrl}${endpoint}`,
+        {
+          headers
+        }
+      );
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       throw new Error(
@@ -370,7 +375,9 @@ class FigmaService {
       const sanitizedPath = path.normalize(localPath).replace(/^(\.\.(\/|\\|$))+/, "");
       resolvedPath = path.resolve(sanitizedPath);
       if (!resolvedPath.startsWith(path.resolve(process.cwd()))) {
-        throw new Error("Invalid path specified. Directory traversal is not allowed.");
+        throw new Error(
+          "Invalid path specified. Directory traversal is not allowed."
+        );
       }
     }
     const downloadPromises = [];
@@ -382,25 +389,45 @@ class FigmaService {
     );
     if (imageFills.length > 0) {
       const fillUrls = await this.getImageFillUrls(fileKey);
-      const fillDownloads = imageFills.map(({ imageRef, fileName, needsCropping, cropTransform, requiresImageDimensions }) => {
-        const imageUrl = fillUrls[imageRef];
-        return imageUrl ? downloadAndProcessImage(
+      const fillDownloads = imageFills.map(
+        ({
+          imageRef,
           fileName,
-          resolvedPath,
-          imageUrl,
           needsCropping,
           cropTransform,
-          requiresImageDimensions,
-          returnBuffer
-        ) : null;
-      }).filter((promise) => promise !== null);
+          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
+          );
+        }
+      ).filter(
+        (promise) => promise !== null
+      );
       if (fillDownloads.length > 0) {
         downloadPromises.push(Promise.all(fillDownloads));
       }
     }
     if (renderNodes.length > 0) {
-      const pngNodes = renderNodes.filter((node) => !node.fileName.toLowerCase().endsWith(".svg"));
-      const svgNodes = renderNodes.filter((node) => node.fileName.toLowerCase().endsWith(".svg"));
+      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,
@@ -408,18 +435,36 @@ class FigmaService {
           "png",
           { pngScale }
         );
-        const pngDownloads = pngNodes.map(({ nodeId, fileName, needsCropping, cropTransform, requiresImageDimensions }) => {
-          const imageUrl = pngUrls[nodeId];
-          return imageUrl ? downloadAndProcessImage(
+        const pngDownloads = pngNodes.map(
+          ({
+            nodeId,
             fileName,
-            resolvedPath,
-            imageUrl,
             needsCropping,
             cropTransform,
-            requiresImageDimensions,
-            returnBuffer
-          ).then((result) => ({ ...result, nodeId })) : null;
-        }).filter((promise) => promise !== null);
+            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(
+          (promise) => promise !== null
+        );
         if (pngDownloads.length > 0) {
           downloadPromises.push(Promise.all(pngDownloads));
         }
@@ -431,18 +476,36 @@ class FigmaService {
           "svg",
           { svgOptions }
         );
-        const svgDownloads = svgNodes.map(({ nodeId, fileName, needsCropping, cropTransform, requiresImageDimensions }) => {
-          const imageUrl = svgUrls[nodeId];
-          return imageUrl ? downloadAndProcessImage(
+        const svgDownloads = svgNodes.map(
+          ({
+            nodeId,
             fileName,
-            resolvedPath,
-            imageUrl,
             needsCropping,
             cropTransform,
-            requiresImageDimensions,
-            returnBuffer
-          ).then((result) => ({ ...result, nodeId })) : null;
-        }).filter((promise) => promise !== null);
+            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(
+          (promise) => promise !== null
+        );
         if (svgDownloads.length > 0) {
           downloadPromises.push(Promise.all(svgDownloads));
         }
@@ -456,7 +519,9 @@ class FigmaService {
    */
   async getRawFile(fileKey, depth) {
     const endpoint = `/files/${fileKey}${depth ? `?depth=${depth}` : ""}`;
-    Logger.log(`Retrieving raw Figma file: ${fileKey} (depth: ${depth ?? "default"})`);
+    Logger.log(
+      `Retrieving raw Figma file: ${fileKey} (depth: ${depth ?? "default"})`
+    );
     const response = await this.request(endpoint);
     writeLogs("figma-raw.json", response);
     return response;
@@ -1470,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`
     );
@@ -1489,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);
@@ -1510,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`
+          );
         }
       }
     }
@@ -1531,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");
@@ -1554,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) {
@@ -1581,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) {
@@ -1590,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({
@@ -1605,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) {
@@ -1647,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,
@@ -1659,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,69 +1,69 @@
 {
-    "name": "figma-metadata-extractor",
-    "version": "1.0.11",
-    "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",
-    "module": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.js",
-            "require": "./dist/index.cjs"
-        }
-    },
-    "files": [
-        "dist",
-        "README.md",
-        "example.js"
-    ],
-    "scripts": {
-        "build": "vite build && tsc --project tsconfig.declarations.json",
-        "typecheck": "tsc --noEmit",
-        "test": "jest",
-        "dev": "vite build --watch",
-        "lint": "eslint .",
-        "format": "prettier --write \"src/**/*.ts\"",
-        "prepack": "npm run build"
-    },
-    "engines": {
-        "node": ">=18.0.0"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/mikmokpok/figma-context-extractor.git"
-    },
-    "keywords": [
-        "figma",
-        "design",
-        "metadata",
-        "extractor",
-        "typescript",
-        "api",
-        "images"
-    ],
-    "author": "",
-    "license": "MIT",
-    "dependencies": {
-        "@figma/rest-api-spec": "^0.33.0",
-        "js-yaml": "^4.1.0",
-        "remeda": "^2.20.1",
-        "sharp": "^0.34.3",
-        "zod": "^3.24.2"
-    },
-    "devDependencies": {
-        "@types/jest": "^29.5.14",
-        "@types/js-yaml": "^4.0.9",
-        "@types/node": "^20.17.0",
-        "@typescript-eslint/eslint-plugin": "^8.24.0",
-        "@typescript-eslint/parser": "^8.24.0",
-        "eslint": "^9.20.1",
-        "eslint-config-prettier": "^10.0.1",
-        "jest": "^29.7.0",
-        "prettier": "^3.5.0",
-        "ts-jest": "^29.2.5",
-        "typescript": "^5.7.3",
-        "vite": "^6.4.1"
+  "name": "figma-metadata-extractor",
+  "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",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
-}
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "example.js"
+  ],
+  "scripts": {
+    "build": "vite build && tsc --project tsconfig.declarations.json",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "dev": "vite build --watch",
+    "lint": "eslint .",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mikmokpok/figma-context-extractor.git"
+  },
+  "keywords": [
+    "figma",
+    "design",
+    "metadata",
+    "extractor",
+    "typescript",
+    "api",
+    "images"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@figma/rest-api-spec": "^0.33.0",
+    "js-yaml": "^4.1.0",
+    "remeda": "^2.20.1",
+    "sharp": "^0.34.3",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.17.0",
+    "@typescript-eslint/eslint-plugin": "^8.24.0",
+    "@typescript-eslint/parser": "^8.24.0",
+    "eslint": "^9.20.1",
+    "eslint-config-prettier": "^10.0.1",
+    "jest": "^29.7.0",
+    "prettier": "^3.5.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.3",
+    "vite": "^6.4.1"
+  }
+}