figma-metadata-extractor 1.0.9 → 1.0.11

package/dist/index.cjs

@@ -420,7 +420,7 @@ class FigmaService {
             cropTransform,
             requiresImageDimensions,
             returnBuffer
-          ) : null;
+          ).then((result) => ({ ...result, nodeId })) : null;
         }).filter((promise) => promise !== null);
         if (pngDownloads.length > 0) {
           downloadPromises.push(Promise.all(pngDownloads));
@@ -443,7 +443,7 @@ class FigmaService {
             cropTransform,
             requiresImageDimensions,
             returnBuffer
-          ) : null;
+          ).then((result) => ({ ...result, nodeId })) : null;
         }).filter((promise) => promise !== null);
         if (svgDownloads.length > 0) {
           downloadPromises.push(Promise.all(svgDownloads));
@@ -1630,6 +1630,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 +1759,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

@@ -418,7 +418,7 @@ class FigmaService {
             cropTransform,
             requiresImageDimensions,
             returnBuffer
-          ) : null;
+          ).then((result) => ({ ...result, nodeId })) : null;
         }).filter((promise) => promise !== null);
         if (pngDownloads.length > 0) {
           downloadPromises.push(Promise.all(pngDownloads));
@@ -441,7 +441,7 @@ class FigmaService {
             cropTransform,
             requiresImageDimensions,
             returnBuffer
-          ) : null;
+          ).then((result) => ({ ...result, nodeId })) : null;
         }).filter((promise) => promise !== null);
         if (svgDownloads.length > 0) {
           downloadPromises.push(Promise.all(svgDownloads));
@@ -1628,6 +1628,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 +1758,10 @@ export {
   contentOnly,
   downloadFigmaFrameImage,
   downloadFigmaImages,
+  enrichMetadataWithImages,
   extractFromDesign,
   getFigmaMetadata,
+  getImageNodeInfo,
   layoutAndText,
   layoutExtractor,
   layoutOnly,

package/dist/lib.d.ts

@@ -61,6 +61,7 @@ export interface FigmaMetadataResult {
     images?: FigmaImageResult[];
 }
 export interface FigmaImageResult {
+    nodeId?: string;
     filePath?: string;
     buffer?: ArrayBuffer;
     finalDimensions: {
@@ -121,17 +122,58 @@ export declare function downloadFigmaImages(figmaUrl: string, nodes: FigmaImageN
  * @returns Promise resolving to the download result
  */
 export declare function downloadFigmaFrameImage(figmaUrl: string, options: FigmaFrameImageOptions): Promise<FigmaImageResult>;
+/**
+ * Get image node information from metadata
+ *
+ * Returns an array of objects containing node IDs and names for all images in the metadata.
+ * Use this to create a mapping between node IDs and uploaded URLs.
+ *
+ * @param metadata - The metadata result from getFigmaMetadata
+ * @returns Array of objects with nodeId and name for each image
+ *
+ * @example
+ * ```typescript
+ * const imageInfo = getImageNodeInfo(metadata);
+ * // [{ nodeId: '123:456', name: 'icon' }, { nodeId: '789:012', name: 'logo' }]
+ *
+ * // Upload images and create mapping
+ * const urlMap: Record<string, string> = {};
+ * for (const info of imageInfo) {
+ *   const url = await uploadToS3(metadata.images.find(img => img.nodeId === info.nodeId).buffer);
+ *   urlMap[info.nodeId] = url;
+ * }
+ *
+ * // Enrich metadata with URLs
+ * const enriched = enrichMetadataWithImages(metadata, urlMap);
+ * ```
+ */
+export declare function getImageNodeInfo(metadata: FigmaMetadataResult): Array<{
+    nodeId: string;
+    name: string;
+}>;
 /**
  * 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.
  *
  * @param metadata - The metadata result from getFigmaMetadata
- * @param imagePaths - Array of file paths corresponding to the images array
+ * @param imagePaths - Array of file paths (ordered) OR object mapping node IDs to paths/URLs
  * @param options - Options for path generation
  * @returns Enriched metadata with downloadedImage properties on nodes
+ *
+ * @example
+ * ```typescript
+ * // Array format (ordered)
+ * const enriched = enrichMetadataWithImages(metadata, ['/path/to/img1.png', '/path/to/img2.png']);
+ *
+ * // Object format (keyed by node ID) - useful after uploading to CDN
+ * const enriched = enrichMetadataWithImages(metadata, {
+ *   '123:456': 'https://cdn.example.com/icon.png',
+ *   '789:012': 'https://cdn.example.com/logo.png'
+ * });
+ * ```
  */
-export declare function enrichMetadataWithImages(metadata: FigmaMetadataResult, imagePaths: string[], options?: {
+export declare function enrichMetadataWithImages(metadata: FigmaMetadataResult, imagePaths: string[] | Record<string, string>, options?: {
     useRelativePaths?: boolean | string;
     localPath?: string;
 }): FigmaMetadataResult;

package/dist/utils/image-processing.d.ts

@@ -16,6 +16,7 @@ export declare function getImageDimensions(imagePath: string): Promise<{
     height: number;
 }>;
 export type ImageProcessingResult = {
+    nodeId?: string;
     filePath?: string;
     buffer?: ArrayBuffer;
     originalDimensions: {

package/package.json

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