figma-metadata-extractor 1.0.10 → 1.0.12

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;
@@ -1630,6 +1695,59 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     throw new Error(`Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
+function getImageNodeInfo(metadata) {
+  if (!metadata.images || metadata.images.length === 0) {
+    return [];
+  }
+  const imageAssets = findImageAssets(metadata.nodes, metadata.globalVars);
+  return imageAssets.map((asset) => ({
+    nodeId: asset.id,
+    name: asset.name
+  }));
+}
+function enrichMetadataWithImages(metadata, imagePaths, options = {}) {
+  const { useRelativePaths = true, localPath } = options;
+  if (!metadata.images || metadata.images.length === 0) {
+    return metadata;
+  }
+  const imageAssets = findImageAssets(metadata.nodes, metadata.globalVars);
+  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})`);
+    }
+    downloadResults = imagePaths.map((filePath, index) => ({
+      filePath,
+      finalDimensions: metadata.images[index].finalDimensions,
+      wasCropped: metadata.images[index].wasCropped,
+      cssVariables: metadata.images[index].cssVariables
+    }));
+  } else {
+    downloadResults = imageAssets.map((asset) => {
+      const filePath = imagePaths[asset.id];
+      if (!filePath) {
+        throw new Error(`No image path provided for node ID: ${asset.id}`);
+      }
+      const imageMetadata = metadata.images.find((img) => img.nodeId === asset.id);
+      return {
+        filePath,
+        finalDimensions: imageMetadata?.finalDimensions || { width: 0, height: 0 },
+        wasCropped: imageMetadata?.wasCropped || false,
+        cssVariables: imageMetadata?.cssVariables
+      };
+    });
+  }
+  const enrichedNodes = enrichNodesWithImages(
+    metadata.nodes,
+    imageAssets,
+    downloadResults,
+    useRelativePaths
+  );
+  return {
+    ...metadata,
+    nodes: enrichedNodes
+  };
+}
 function sanitizeFileName(name) {
   return name.replace(/[^a-z0-9]/gi, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
 }
@@ -1706,8 +1824,10 @@ exports.componentExtractor = componentExtractor;
 exports.contentOnly = contentOnly;
 exports.downloadFigmaFrameImage = downloadFigmaFrameImage;
 exports.downloadFigmaImages = downloadFigmaImages;
+exports.enrichMetadataWithImages = enrichMetadataWithImages;
 exports.extractFromDesign = extractFromDesign;
 exports.getFigmaMetadata = getFigmaMetadata;
+exports.getImageNodeInfo = getImageNodeInfo;
 exports.layoutAndText = layoutAndText;
 exports.layoutExtractor = layoutExtractor;
 exports.layoutOnly = layoutOnly;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { getFigmaMetadata, downloadFigmaImages, downloadFigmaFrameImage, type FigmaMetadataOptions, type FigmaImageOptions, type FigmaFrameImageOptions, type FigmaImageNode, type FigmaMetadataResult, type FigmaImageResult, } from "./lib.js";
+export { getFigmaMetadata, downloadFigmaImages, downloadFigmaFrameImage, enrichMetadataWithImages, getImageNodeInfo, type FigmaMetadataOptions, type FigmaImageOptions, type FigmaFrameImageOptions, type FigmaImageNode, type FigmaMetadataResult, type FigmaImageResult, } from "./lib.js";
 export type { SimplifiedDesign } from "./extractors/types.js";
 export type { ExtractorFn, TraversalContext, TraversalOptions, GlobalVars, StyleTypes, } from "./extractors/index.js";
 export { extractFromDesign, simplifyRawFigmaObject, layoutExtractor, textExtractor, visualsExtractor, componentExtractor, allExtractors, layoutAndText, contentOnly, visualsOnly, layoutOnly, collapseSvgContainers, } from "./extractors/index.js";

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;
@@ -1628,6 +1693,59 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     throw new Error(`Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
+function getImageNodeInfo(metadata) {
+  if (!metadata.images || metadata.images.length === 0) {
+    return [];
+  }
+  const imageAssets = findImageAssets(metadata.nodes, metadata.globalVars);
+  return imageAssets.map((asset) => ({
+    nodeId: asset.id,
+    name: asset.name
+  }));
+}
+function enrichMetadataWithImages(metadata, imagePaths, options = {}) {
+  const { useRelativePaths = true, localPath } = options;
+  if (!metadata.images || metadata.images.length === 0) {
+    return metadata;
+  }
+  const imageAssets = findImageAssets(metadata.nodes, metadata.globalVars);
+  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})`);
+    }
+    downloadResults = imagePaths.map((filePath, index) => ({
+      filePath,
+      finalDimensions: metadata.images[index].finalDimensions,
+      wasCropped: metadata.images[index].wasCropped,
+      cssVariables: metadata.images[index].cssVariables
+    }));
+  } else {
+    downloadResults = imageAssets.map((asset) => {
+      const filePath = imagePaths[asset.id];
+      if (!filePath) {
+        throw new Error(`No image path provided for node ID: ${asset.id}`);
+      }
+      const imageMetadata = metadata.images.find((img) => img.nodeId === asset.id);
+      return {
+        filePath,
+        finalDimensions: imageMetadata?.finalDimensions || { width: 0, height: 0 },
+        wasCropped: imageMetadata?.wasCropped || false,
+        cssVariables: imageMetadata?.cssVariables
+      };
+    });
+  }
+  const enrichedNodes = enrichNodesWithImages(
+    metadata.nodes,
+    imageAssets,
+    downloadResults,
+    useRelativePaths
+  );
+  return {
+    ...metadata,
+    nodes: enrichedNodes
+  };
+}
 function sanitizeFileName(name) {
   return name.replace(/[^a-z0-9]/gi, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
 }
@@ -1705,8 +1823,10 @@ export {
   contentOnly,
   downloadFigmaFrameImage,
   downloadFigmaImages,
+  enrichMetadataWithImages,
   extractFromDesign,
   getFigmaMetadata,
+  getImageNodeInfo,
   layoutAndText,
   layoutExtractor,
   layoutOnly,

package/package.json

@@ -1,69 +1,69 @@
 {
-    "name": "figma-metadata-extractor",
-    "version": "1.0.10",
-    "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.12",
+  "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"
+  }
+}