figma-metadata-extractor 1.0.7 → 1.0.8

package/README.md

@@ -8,6 +8,15 @@ A TypeScript library for extracting metadata and downloading images from Figma f
 npm install figma-metadata-extractor
 ```
 
+## Features
+
+- 🎨 Extract comprehensive metadata from Figma files
+- 📦 Auto-download image assets (to disk or as buffers)
+- 🔄 Support for both file-based and buffer-based workflows
+- 🎯 Enrich metadata with image paths and markup
+- 🔐 Support for both API keys and OAuth tokens
+- 📝 Multiple output formats (JSON, YAML, object)
+
 ## Quick Start
 
 ### Get Metadata with Auto-Downloaded Images (LLM-Ready!)
@@ -15,7 +24,7 @@ npm install figma-metadata-extractor
 ```typescript
 import { getFigmaMetadata } from 'figma-metadata-extractor';
 
-// Extract metadata AND automatically download image assets
+// Extract metadata AND automatically download image assets to disk
 const metadata = await getFigmaMetadata(
   'https://figma.com/file/ABC123/My-Design',
   {
@@ -26,6 +35,55 @@ const metadata = await getFigmaMetadata(
   }
 );
 
+// Nodes are enriched with downloadedImage property
+metadata.nodes.forEach(node => {
+  if (node.downloadedImage) {
+    console.log(node.downloadedImage.filePath);
+    console.log(node.downloadedImage.markdown); // ![name](path)
+  }
+});
+```
+
+### Get Images as Buffers (No Disk Write)
+
+```typescript
+import { getFigmaMetadata, enrichMetadataWithImages } from 'figma-metadata-extractor';
+import fs from 'fs/promises';
+
+// Get metadata with images as ArrayBuffers
+const result = await getFigmaMetadata(
+  'https://figma.com/file/ABC123/My-Design',
+  {
+    apiKey: 'your-figma-api-key',
+    downloadImages: true,
+    returnBuffer: true  // Get images as ArrayBuffer
+  }
+);
+
+// Images are returned separately, metadata is not enriched
+console.log(`Downloaded ${result.images.length} images as buffers`);
+
+// Process buffers (upload to S3, convert format, etc.)
+const savedPaths: string[] = [];
+for (const image of result.images) {
+  // Example: Save to disk after processing
+  const buffer = Buffer.from(image.buffer);
+  const path = `./processed/${Date.now()}.png`;
+  await fs.writeFile(path, buffer);
+  savedPaths.push(path);
+}
+
+// Optionally enrich metadata with saved file paths
+const enrichedMetadata = enrichMetadataWithImages(result, savedPaths, {
+  useRelativePaths: true
+});
+
+// Now nodes have downloadedImage properties
+enrichedMetadata.nodes.forEach(node => {
+  if (node.downloadedImage) {
+    console.log(node.downloadedImage.markdown);
+  }
+});
 ```
 
 ### Get Metadata Only (No Downloads)
@@ -98,13 +156,25 @@ Extracts comprehensive metadata from a Figma file including layout, content, vis
 - `outputFormat?: 'json' | 'yaml' | 'object'` - Output format (default: 'object')
 - `depth?: number` - Maximum depth to traverse the node tree
 - `downloadImages?: boolean` - Automatically download image assets and enrich metadata (default: false)
-- `localPath?: string` - Local path for downloaded images (required if downloadImages is true)
+- `localPath?: string` - Local path for downloaded images (optional if returnBuffer is true)
 - `imageFormat?: 'png' | 'svg'` - Image format for downloads (default: 'png')
 - `pngScale?: number` - Export scale for PNG images (default: 2)
+- `returnBuffer?: boolean` - Return images as ArrayBuffer instead of saving to disk (default: false)
+- `enableLogging?: boolean` - Enable JSON debug log files (default: false)
 
 **Returns:** Promise<FigmaMetadataResult | string>
 
-When `downloadImages` is true, nodes with image assets will include a `downloadedImage` property:
+**FigmaMetadataResult:**
+```typescript
+{
+  metadata: any;              // File metadata
+  nodes: any[];               // Design nodes
+  globalVars: any;            // Styles, colors, etc.
+  images?: FigmaImageResult[]; // Only present when downloadImages: true and returnBuffer: true
+}
+```
+
+When `downloadImages: true` and `returnBuffer: false`, nodes with image assets will include a `downloadedImage` property:
 ```typescript
 {
   filePath: string;           // Absolute path
@@ -115,6 +185,8 @@ When `downloadImages` is true, nodes with image assets will include a `downloade
 }
 ```
 
+When `downloadImages: true` and `returnBuffer: true`, images are returned in the `images` array and nodes are NOT enriched. Use `enrichMetadataWithImages()` to enrich them later after saving buffers to disk.
+
 ### `downloadFigmaImages(figmaUrl, nodes, options)`
 
 Downloads SVG and PNG images from a Figma file.
@@ -143,6 +215,42 @@ Downloads SVG and PNG images from a Figma file.
 
 When `returnBuffer` is true, each result will contain a `buffer` property instead of `filePath`.
 
+### `enrichMetadataWithImages(metadata, imagePaths, options)`
+
+Enriches metadata with saved image file paths after saving buffers to disk.
+
+**Parameters:**
+- `metadata` (FigmaMetadataResult): The metadata result from getFigmaMetadata with returnBuffer: true
+- `imagePaths` (string[]): Array of file paths where images were saved (must match order of metadata.images)
+- `options` (object): Configuration options
+  - `useRelativePaths?: boolean | string` - How to generate paths (default: true)
+  - `localPath?: string` - Base path for relative path calculation
+
+**Returns:** FigmaMetadataResult with enriched nodes
+
+**Example:**
+```typescript
+// Get metadata with buffers
+const result = await getFigmaMetadata(url, {
+  apiKey: 'key',
+  downloadImages: true,
+  returnBuffer: true
+});
+
+// Save buffers to disk
+const paths = await Promise.all(
+  result.images.map((img, i) => 
+    fs.writeFile(`./images/img-${i}.png`, Buffer.from(img.buffer))
+      .then(() => `./images/img-${i}.png`)
+  )
+);
+
+// Enrich metadata with file paths
+const enriched = enrichMetadataWithImages(result, paths, {
+  useRelativePaths: true
+});
+```
+
 ### `downloadFigmaFrameImage(figmaUrl, options)`
 
 Downloads a single frame image from a Figma URL that contains a node-id parameter.

package/dist/index.cjs

@@ -1447,7 +1447,8 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
     imageFormat = "png",
     pngScale = 2,
     useRelativePaths = true,
-    enableLogging = false
+    enableLogging = false,
+    returnBuffer = false
   } = options;
   Logger.enableLogging = enableLogging;
   if (!apiKey && !oauthToken) {
@@ -1489,8 +1490,8 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
       globalVars
     };
     if (downloadImages) {
-      if (!localPath) {
-        throw new Error("localPath is required when downloadImages is true");
+      if (!returnBuffer && !localPath) {
+        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);
@@ -1502,12 +1503,20 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
         }));
         const downloadResults = await figmaService.downloadImages(
           fileKey,
-          localPath,
+          localPath || "",
           imageNodes,
-          { pngScale: imageFormat === "png" ? pngScale : void 0 }
+          {
+            pngScale: imageFormat === "png" ? pngScale : void 0,
+            returnBuffer
+          }
         );
-        result.nodes = enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths, localPath);
-        Logger.log(`Successfully downloaded and enriched ${downloadResults.length} images`);
+        if (returnBuffer) {
+          result.images = downloadResults;
+          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`);
+        }
       }
     }
     if (outputFormat === "json") {
@@ -1652,7 +1661,7 @@ function enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativeP
   const imageMap = /* @__PURE__ */ new Map();
   imageAssets.forEach((asset, index) => {
     const result = downloadResults[index];
-    if (result) {
+    if (result && result.filePath) {
       let pathForMarkup;
       if (useRelativePaths === false) {
         pathForMarkup = result.filePath;

package/dist/index.js

@@ -1445,7 +1445,8 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
     imageFormat = "png",
     pngScale = 2,
     useRelativePaths = true,
-    enableLogging = false
+    enableLogging = false,
+    returnBuffer = false
   } = options;
   Logger.enableLogging = enableLogging;
   if (!apiKey && !oauthToken) {
@@ -1487,8 +1488,8 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
       globalVars
     };
     if (downloadImages) {
-      if (!localPath) {
-        throw new Error("localPath is required when downloadImages is true");
+      if (!returnBuffer && !localPath) {
+        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);
@@ -1500,12 +1501,20 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
         }));
         const downloadResults = await figmaService.downloadImages(
           fileKey,
-          localPath,
+          localPath || "",
           imageNodes,
-          { pngScale: imageFormat === "png" ? pngScale : void 0 }
+          {
+            pngScale: imageFormat === "png" ? pngScale : void 0,
+            returnBuffer
+          }
         );
-        result.nodes = enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativePaths, localPath);
-        Logger.log(`Successfully downloaded and enriched ${downloadResults.length} images`);
+        if (returnBuffer) {
+          result.images = downloadResults;
+          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`);
+        }
       }
     }
     if (outputFormat === "json") {
@@ -1650,7 +1659,7 @@ function enrichNodesWithImages(nodes, imageAssets, downloadResults, useRelativeP
   const imageMap = /* @__PURE__ */ new Map();
   imageAssets.forEach((asset, index) => {
     const result = downloadResults[index];
-    if (result) {
+    if (result && result.filePath) {
       let pathForMarkup;
       if (useRelativePaths === false) {
         pathForMarkup = result.filePath;

package/dist/lib.d.ts

@@ -27,6 +27,8 @@ export interface FigmaMetadataOptions {
     useRelativePaths?: boolean | string;
     /** Enable JSON debug log files (defaults to false) */
     enableLogging?: boolean;
+    /** Return images as ArrayBuffer instead of saving to disk (defaults to false) */
+    returnBuffer?: boolean;
 }
 export interface FigmaImageOptions {
     /** Export scale for PNG images (defaults to 2) */
@@ -56,6 +58,7 @@ export interface FigmaMetadataResult {
     metadata: any;
     nodes: any[];
     globalVars: any;
+    images?: FigmaImageResult[];
 }
 export interface FigmaImageResult {
     filePath?: string;
@@ -112,6 +115,20 @@ 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>;
+/**
+ * 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 options - Options for path generation
+ * @returns Enriched metadata with downloadedImage properties on nodes
+ */
+export declare function enrichMetadataWithImages(metadata: FigmaMetadataResult, imagePaths: string[], options?: {
+    useRelativePaths?: boolean | string;
+    localPath?: string;
+}): FigmaMetadataResult;
 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/package.json

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