figma-metadata-extractor 1.0.8 → 1.0.10

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));

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));

package/dist/lib.d.ts

@@ -61,6 +61,7 @@ export interface FigmaMetadataResult {
     images?: FigmaImageResult[];
 }
 export interface FigmaImageResult {
+    nodeId?: string;
     filePath?: string;
     buffer?: ArrayBuffer;
     finalDimensions: {
@@ -97,7 +98,13 @@ export interface FigmaFrameImageOptions {
  * @param options - Configuration options including API credentials
  * @returns Promise resolving to the extracted metadata
  */
-export declare function getFigmaMetadata(figmaUrl: string, options?: FigmaMetadataOptions): Promise<FigmaMetadataResult | string>;
+export declare function getFigmaMetadata(figmaUrl: string, options: FigmaMetadataOptions & {
+    outputFormat: 'json';
+}): Promise<string>;
+export declare function getFigmaMetadata(figmaUrl: string, options: FigmaMetadataOptions & {
+    outputFormat: 'yaml';
+}): Promise<string>;
+export declare function getFigmaMetadata(figmaUrl: string, options?: FigmaMetadataOptions): Promise<FigmaMetadataResult>;
 /**
  * Download images from a Figma file
  *
@@ -115,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.8",
+    "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",