figma-metadata-extractor 1.0.6 → 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.
@@ -135,10 +207,50 @@ Downloads SVG and PNG images from a Figma file.
 
 **Additional Options:**
 - `pngScale?: number` - Export scale for PNG images (default: 2)
-- `localPath: string` - Absolute path to save images
+- `localPath?: string` - Absolute path to save images (optional if returnBuffer is true)
+- `returnBuffer?: boolean` - Return images as ArrayBuffer instead of saving to disk (default: false)
+- `enableLogging?: boolean` - Enable JSON debug log files (default: false)
 
 **Returns:** Promise<FigmaImageResult[]>
 
+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.
@@ -151,13 +263,22 @@ Downloads a single frame image from a Figma URL that contains a node-id paramete
 - `apiKey?: string` - Figma API key (Personal Access Token)
 - `oauthToken?: string` - Figma OAuth Bearer token  
 - `useOAuth?: boolean` - Whether to use OAuth instead of API key
-- `localPath: string` - Absolute path to save the image
-- `fileName: string` - Local filename (must end with .png or .svg)
+- `localPath?: string` - Absolute path to save the image (optional if returnBuffer is true)
+- `fileName?: string` - Local filename (must end with .png or .svg, optional if returnBuffer is true)
 - `format?: 'png' | 'svg'` - Image format to download (default: 'png')
 - `pngScale?: number` - Export scale for PNG images (default: 2)
+- `returnBuffer?: boolean` - Return image as ArrayBuffer instead of saving to disk (default: false)
+- `enableLogging?: boolean` - Enable JSON debug log files (default: false)
 
 **Returns:** Promise<FigmaImageResult>
 
+**Result Properties:**
+- `filePath?: string` - Path to saved file (only when returnBuffer is false)
+- `buffer?: ArrayBuffer` - Image data as ArrayBuffer (only when returnBuffer is true)
+- `finalDimensions: { width: number; height: number }` - Image dimensions
+- `wasCropped: boolean` - Whether the image was cropped
+- `cssVariables?: string` - CSS variables for dimensions (if requested)
+
 ## Authentication
 
 You need either a Figma API key or OAuth token:
@@ -184,6 +305,7 @@ import { downloadFigmaFrameImage } from 'figma-metadata-extractor';
 // Copy this URL from Figma when viewing a frame
 const figmaUrl = 'https://www.figma.com/design/ABC123/My-Design?node-id=1234-5678&t=xyz123';
 
+// Save to disk
 const result = await downloadFigmaFrameImage(figmaUrl, {
   apiKey: 'your-figma-api-key',
   localPath: './downloads',
@@ -196,6 +318,29 @@ console.log(`Downloaded to: ${result.filePath}`);
 console.log(`Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`);
 ```
 
+### Get Frame Image as ArrayBuffer (No Disk Write)
+
+If you want to process the image in memory without saving to disk:
+
+```typescript
+import { downloadFigmaFrameImage } from 'figma-metadata-extractor';
+
+const figmaUrl = 'https://www.figma.com/design/ABC123/My-Design?node-id=1234-5678';
+
+// Get as ArrayBuffer
+const result = await downloadFigmaFrameImage(figmaUrl, {
+  apiKey: 'your-figma-api-key',
+  returnBuffer: true,
+  format: 'png'
+});
+
+console.log(`Buffer size: ${result.buffer.byteLength} bytes`);
+console.log(`Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`);
+
+// Use the buffer directly (e.g., upload to cloud storage, process with sharp, etc.)
+// const processedImage = await sharp(Buffer.from(result.buffer)).resize(100, 100).toBuffer();
+```
+
 ### Download Multiple Frame Images
 
 ```typescript
@@ -216,6 +361,31 @@ const results = await downloadFigmaImages(
 );
 ```
 
+### Download Multiple Images as Buffers
+
+```typescript
+import { downloadFigmaImages } from 'figma-metadata-extractor';
+
+// Get multiple images as ArrayBuffers
+const results = await downloadFigmaImages(
+  'https://figma.com/file/ABC123/My-Design',
+  [
+    { nodeId: '1234:5678', fileName: 'frame1.png' },
+    { nodeId: '9876:5432', fileName: 'frame2.png' }
+  ],
+  {
+    apiKey: 'your-figma-api-key',
+    returnBuffer: true
+  }
+);
+
+// Process each buffer
+results.forEach((result, index) => {
+  console.log(`Image ${index}: ${result.buffer.byteLength} bytes`);
+  // Upload to S3, process with sharp, etc.
+});
+```
+
 ## Advanced Usage
 
 The library also exports the underlying extractor system for custom processing:

package/dist/index.cjs

@@ -64,11 +64,69 @@ async function getImageDimensions(imagePath) {
     return { width: 1e3, height: 1e3 };
   }
 }
-async function downloadAndProcessImage(fileName, localPath, imageUrl, needsCropping = false, cropTransform, requiresImageDimensions = false) {
+async function downloadAndProcessImage(fileName, localPath, imageUrl, needsCropping = false, cropTransform, requiresImageDimensions = false, returnBuffer = false) {
   const { Logger: Logger2 } = await Promise.resolve().then(() => logger);
   const processingLog = [];
   const { downloadFigmaImage: downloadFigmaImage2 } = await Promise.resolve().then(() => common);
-  const originalPath = await downloadFigmaImage2(fileName, localPath, imageUrl);
+  const downloadResult = await downloadFigmaImage2(fileName, localPath, imageUrl, returnBuffer);
+  if (returnBuffer && downloadResult instanceof ArrayBuffer) {
+    Logger2.log(`Downloaded image as buffer (${downloadResult.byteLength} bytes)`);
+    let imageBuffer = Buffer.from(downloadResult);
+    let sharpImage = sharp(imageBuffer);
+    const metadata = await sharpImage.metadata();
+    const originalDimensions2 = {
+      width: metadata.width || 0,
+      height: metadata.height || 0
+    };
+    Logger2.log(`Original dimensions: ${originalDimensions2.width}x${originalDimensions2.height}`);
+    let wasCropped2 = false;
+    let cropRegion2;
+    let finalDimensions2 = originalDimensions2;
+    if (needsCropping && cropTransform) {
+      Logger2.log("Applying crop transform to buffer...");
+      const scaleX = cropTransform[0]?.[0] ?? 1;
+      const scaleY = cropTransform[1]?.[1] ?? 1;
+      const translateX = cropTransform[0]?.[2] ?? 0;
+      const translateY = cropTransform[1]?.[2] ?? 0;
+      const cropLeft = Math.max(0, Math.round(translateX * originalDimensions2.width));
+      const cropTop = Math.max(0, Math.round(translateY * originalDimensions2.height));
+      const cropWidth = Math.min(
+        originalDimensions2.width - cropLeft,
+        Math.round(scaleX * originalDimensions2.width)
+      );
+      const cropHeight = Math.min(
+        originalDimensions2.height - cropTop,
+        Math.round(scaleY * originalDimensions2.height)
+      );
+      if (cropWidth > 0 && cropHeight > 0) {
+        cropRegion2 = { left: cropLeft, top: cropTop, width: cropWidth, height: cropHeight };
+        const croppedBuffer = await sharpImage.extract({
+          left: cropLeft,
+          top: cropTop,
+          width: cropWidth,
+          height: cropHeight
+        }).toBuffer();
+        imageBuffer = croppedBuffer;
+        wasCropped2 = true;
+        finalDimensions2 = { width: cropWidth, height: cropHeight };
+        Logger2.log(`Cropped to region: ${cropLeft}, ${cropTop}, ${cropWidth}x${cropHeight}`);
+      }
+    }
+    let cssVariables2;
+    if (requiresImageDimensions) {
+      cssVariables2 = generateImageCSSVariables(finalDimensions2);
+    }
+    return {
+      buffer: imageBuffer.buffer.slice(imageBuffer.byteOffset, imageBuffer.byteOffset + imageBuffer.byteLength),
+      originalDimensions: originalDimensions2,
+      finalDimensions: finalDimensions2,
+      wasCropped: wasCropped2,
+      cropRegion: cropRegion2,
+      cssVariables: cssVariables2,
+      processingLog
+    };
+  }
+  const originalPath = downloadResult;
   Logger2.log(`Downloaded original image: ${originalPath}`);
   const originalDimensions = await getImageDimensions(originalPath);
   Logger2.log(`Original dimensions: ${originalDimensions.width}x${originalDimensions.height}`);
@@ -302,17 +360,21 @@ class FigmaService {
    * - PNG vs SVG format (based on filename extension)
    * - Image cropping based on transform matrices
    * - CSS variable generation for image dimensions
+   * - Returning as ArrayBuffer instead of saving to disk
    *
    * @returns Array of local file paths for successfully downloaded images
    */
   async downloadImages(fileKey, localPath, items, options = {}) {
     if (items.length === 0) return [];
-    const sanitizedPath = path.normalize(localPath).replace(/^(\.\.(\/|\\|$))+/, "");
-    const resolvedPath = path.resolve(sanitizedPath);
-    if (!resolvedPath.startsWith(path.resolve(process.cwd()))) {
-      throw new Error("Invalid path specified. Directory traversal is not allowed.");
+    const { pngScale = 2, svgOptions, returnBuffer = false } = options;
+    let resolvedPath = "";
+    if (!returnBuffer) {
+      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.");
+      }
     }
-    const { pngScale = 2, svgOptions } = options;
     const downloadPromises = [];
     const imageFills = items.filter(
       (item) => !!item.imageRef
@@ -330,7 +392,8 @@ class FigmaService {
           imageUrl,
           needsCropping,
           cropTransform,
-          requiresImageDimensions
+          requiresImageDimensions,
+          returnBuffer
         ) : null;
       }).filter((promise) => promise !== null);
       if (fillDownloads.length > 0) {
@@ -355,7 +418,8 @@ class FigmaService {
             imageUrl,
             needsCropping,
             cropTransform,
-            requiresImageDimensions
+            requiresImageDimensions,
+            returnBuffer
           ) : null;
         }).filter((promise) => promise !== null);
         if (pngDownloads.length > 0) {
@@ -377,7 +441,8 @@ class FigmaService {
             imageUrl,
             needsCropping,
             cropTransform,
-            requiresImageDimensions
+            requiresImageDimensions,
+            returnBuffer
           ) : null;
         }).filter((promise) => promise !== null);
         if (svgDownloads.length > 0) {
@@ -411,23 +476,27 @@ class FigmaService {
     return response;
   }
 }
-async function downloadFigmaImage(fileName, localPath, imageUrl) {
+async function downloadFigmaImage(fileName, localPath, imageUrl, returnBuffer = false) {
   try {
-    if (!fs.existsSync(localPath)) {
-      fs.mkdirSync(localPath, { recursive: true });
-    }
-    const fullPath = path.join(localPath, fileName);
     const response = await fetch(imageUrl, {
       method: "GET"
     });
     if (!response.ok) {
       throw new Error(`Failed to download image: ${response.statusText}`);
     }
-    const writer = fs.createWriteStream(fullPath);
+    if (returnBuffer) {
+      const arrayBuffer = await response.arrayBuffer();
+      return arrayBuffer;
+    }
+    if (!fs.existsSync(localPath)) {
+      fs.mkdirSync(localPath, { recursive: true });
+    }
+    const fullPath = path.join(localPath, fileName);
     const reader = response.body?.getReader();
     if (!reader) {
       throw new Error("Failed to get response body");
     }
+    const writer = fs.createWriteStream(fullPath);
     return new Promise((resolve, reject) => {
       const processStream = async () => {
         try {
@@ -1378,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) {
@@ -1420,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);
@@ -1433,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") {
@@ -1455,11 +1533,14 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   }
 }
 async function downloadFigmaImages(figmaUrl, nodes, options) {
-  const { apiKey, oauthToken, useOAuth = false, pngScale = 2, localPath, enableLogging = 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");
   }
+  if (!returnBuffer && !localPath) {
+    throw new Error("localPath is required when returnBuffer is false");
+  }
   const urlMatch = figmaUrl.match(/figma\.com\/(file|design)\/([a-zA-Z0-9]+)/);
   if (!urlMatch) {
     throw new Error("Invalid Figma URL format");
@@ -1475,8 +1556,9 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
       ...node,
       nodeId: node.nodeId.replace(/-/g, ":")
     }));
-    const results = await figmaService.downloadImages(fileKey, localPath, processedNodes, {
-      pngScale
+    const results = await figmaService.downloadImages(fileKey, localPath || "", processedNodes, {
+      pngScale,
+      returnBuffer
     });
     return results;
   } catch (error) {
@@ -1493,12 +1575,16 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     localPath,
     fileName,
     format = "png",
-    enableLogging = false
+    enableLogging = false,
+    returnBuffer = false
   } = options;
   Logger.enableLogging = enableLogging;
   if (!apiKey && !oauthToken) {
     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");
+  }
   const urlMatch = figmaUrl.match(/figma\.com\/(file|design)\/([a-zA-Z0-9]+)/);
   if (!urlMatch) {
     throw new Error("Invalid Figma URL format");
@@ -1509,9 +1595,11 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     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, ":");
-  const expectedExtension = `.${format}`;
-  if (!fileName.toLowerCase().endsWith(expectedExtension)) {
-    throw new Error(`Filename must end with ${expectedExtension} for ${format} format`);
+  if (fileName) {
+    const expectedExtension = `.${format}`;
+    if (!fileName.toLowerCase().endsWith(expectedExtension)) {
+      throw new Error(`Filename must end with ${expectedExtension} for ${format} format`);
+    }
   }
   const figmaService = new FigmaService({
     figmaApiKey: apiKey || "",
@@ -1522,15 +1610,20 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     Logger.log(`Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`);
     const imageNode = {
       nodeId,
-      fileName
+      fileName: fileName || `temp.${format}`
     };
-    const results = await figmaService.downloadImages(fileKey, localPath, [imageNode], {
-      pngScale: format === "png" ? pngScale : void 0
+    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}`);
     }
-    Logger.log(`Successfully downloaded frame image to: ${results[0].filePath}`);
+    if (returnBuffer) {
+      Logger.log(`Successfully downloaded frame image as buffer`);
+    } else {
+      Logger.log(`Successfully downloaded frame image to: ${results[0].filePath}`);
+    }
     return results[0];
   } catch (error) {
     Logger.error(`Error downloading frame image from ${fileKey}:`, error);
@@ -1568,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

@@ -62,11 +62,69 @@ async function getImageDimensions(imagePath) {
     return { width: 1e3, height: 1e3 };
   }
 }
-async function downloadAndProcessImage(fileName, localPath, imageUrl, needsCropping = false, cropTransform, requiresImageDimensions = false) {
+async function downloadAndProcessImage(fileName, localPath, imageUrl, needsCropping = false, cropTransform, requiresImageDimensions = false, returnBuffer = false) {
   const { Logger: Logger2 } = await Promise.resolve().then(() => logger);
   const processingLog = [];
   const { downloadFigmaImage: downloadFigmaImage2 } = await Promise.resolve().then(() => common);
-  const originalPath = await downloadFigmaImage2(fileName, localPath, imageUrl);
+  const downloadResult = await downloadFigmaImage2(fileName, localPath, imageUrl, returnBuffer);
+  if (returnBuffer && downloadResult instanceof ArrayBuffer) {
+    Logger2.log(`Downloaded image as buffer (${downloadResult.byteLength} bytes)`);
+    let imageBuffer = Buffer.from(downloadResult);
+    let sharpImage = sharp(imageBuffer);
+    const metadata = await sharpImage.metadata();
+    const originalDimensions2 = {
+      width: metadata.width || 0,
+      height: metadata.height || 0
+    };
+    Logger2.log(`Original dimensions: ${originalDimensions2.width}x${originalDimensions2.height}`);
+    let wasCropped2 = false;
+    let cropRegion2;
+    let finalDimensions2 = originalDimensions2;
+    if (needsCropping && cropTransform) {
+      Logger2.log("Applying crop transform to buffer...");
+      const scaleX = cropTransform[0]?.[0] ?? 1;
+      const scaleY = cropTransform[1]?.[1] ?? 1;
+      const translateX = cropTransform[0]?.[2] ?? 0;
+      const translateY = cropTransform[1]?.[2] ?? 0;
+      const cropLeft = Math.max(0, Math.round(translateX * originalDimensions2.width));
+      const cropTop = Math.max(0, Math.round(translateY * originalDimensions2.height));
+      const cropWidth = Math.min(
+        originalDimensions2.width - cropLeft,
+        Math.round(scaleX * originalDimensions2.width)
+      );
+      const cropHeight = Math.min(
+        originalDimensions2.height - cropTop,
+        Math.round(scaleY * originalDimensions2.height)
+      );
+      if (cropWidth > 0 && cropHeight > 0) {
+        cropRegion2 = { left: cropLeft, top: cropTop, width: cropWidth, height: cropHeight };
+        const croppedBuffer = await sharpImage.extract({
+          left: cropLeft,
+          top: cropTop,
+          width: cropWidth,
+          height: cropHeight
+        }).toBuffer();
+        imageBuffer = croppedBuffer;
+        wasCropped2 = true;
+        finalDimensions2 = { width: cropWidth, height: cropHeight };
+        Logger2.log(`Cropped to region: ${cropLeft}, ${cropTop}, ${cropWidth}x${cropHeight}`);
+      }
+    }
+    let cssVariables2;
+    if (requiresImageDimensions) {
+      cssVariables2 = generateImageCSSVariables(finalDimensions2);
+    }
+    return {
+      buffer: imageBuffer.buffer.slice(imageBuffer.byteOffset, imageBuffer.byteOffset + imageBuffer.byteLength),
+      originalDimensions: originalDimensions2,
+      finalDimensions: finalDimensions2,
+      wasCropped: wasCropped2,
+      cropRegion: cropRegion2,
+      cssVariables: cssVariables2,
+      processingLog
+    };
+  }
+  const originalPath = downloadResult;
   Logger2.log(`Downloaded original image: ${originalPath}`);
   const originalDimensions = await getImageDimensions(originalPath);
   Logger2.log(`Original dimensions: ${originalDimensions.width}x${originalDimensions.height}`);
@@ -300,17 +358,21 @@ class FigmaService {
    * - PNG vs SVG format (based on filename extension)
    * - Image cropping based on transform matrices
    * - CSS variable generation for image dimensions
+   * - Returning as ArrayBuffer instead of saving to disk
    *
    * @returns Array of local file paths for successfully downloaded images
    */
   async downloadImages(fileKey, localPath, items, options = {}) {
     if (items.length === 0) return [];
-    const sanitizedPath = path.normalize(localPath).replace(/^(\.\.(\/|\\|$))+/, "");
-    const resolvedPath = path.resolve(sanitizedPath);
-    if (!resolvedPath.startsWith(path.resolve(process.cwd()))) {
-      throw new Error("Invalid path specified. Directory traversal is not allowed.");
+    const { pngScale = 2, svgOptions, returnBuffer = false } = options;
+    let resolvedPath = "";
+    if (!returnBuffer) {
+      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.");
+      }
     }
-    const { pngScale = 2, svgOptions } = options;
     const downloadPromises = [];
     const imageFills = items.filter(
       (item) => !!item.imageRef
@@ -328,7 +390,8 @@ class FigmaService {
           imageUrl,
           needsCropping,
           cropTransform,
-          requiresImageDimensions
+          requiresImageDimensions,
+          returnBuffer
         ) : null;
       }).filter((promise) => promise !== null);
       if (fillDownloads.length > 0) {
@@ -353,7 +416,8 @@ class FigmaService {
             imageUrl,
             needsCropping,
             cropTransform,
-            requiresImageDimensions
+            requiresImageDimensions,
+            returnBuffer
           ) : null;
         }).filter((promise) => promise !== null);
         if (pngDownloads.length > 0) {
@@ -375,7 +439,8 @@ class FigmaService {
             imageUrl,
             needsCropping,
             cropTransform,
-            requiresImageDimensions
+            requiresImageDimensions,
+            returnBuffer
           ) : null;
         }).filter((promise) => promise !== null);
         if (svgDownloads.length > 0) {
@@ -409,23 +474,27 @@ class FigmaService {
     return response;
   }
 }
-async function downloadFigmaImage(fileName, localPath, imageUrl) {
+async function downloadFigmaImage(fileName, localPath, imageUrl, returnBuffer = false) {
   try {
-    if (!fs.existsSync(localPath)) {
-      fs.mkdirSync(localPath, { recursive: true });
-    }
-    const fullPath = path.join(localPath, fileName);
     const response = await fetch(imageUrl, {
       method: "GET"
     });
     if (!response.ok) {
       throw new Error(`Failed to download image: ${response.statusText}`);
     }
-    const writer = fs.createWriteStream(fullPath);
+    if (returnBuffer) {
+      const arrayBuffer = await response.arrayBuffer();
+      return arrayBuffer;
+    }
+    if (!fs.existsSync(localPath)) {
+      fs.mkdirSync(localPath, { recursive: true });
+    }
+    const fullPath = path.join(localPath, fileName);
     const reader = response.body?.getReader();
     if (!reader) {
       throw new Error("Failed to get response body");
     }
+    const writer = fs.createWriteStream(fullPath);
     return new Promise((resolve, reject) => {
       const processStream = async () => {
         try {
@@ -1376,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) {
@@ -1418,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);
@@ -1431,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") {
@@ -1453,11 +1531,14 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
   }
 }
 async function downloadFigmaImages(figmaUrl, nodes, options) {
-  const { apiKey, oauthToken, useOAuth = false, pngScale = 2, localPath, enableLogging = 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");
   }
+  if (!returnBuffer && !localPath) {
+    throw new Error("localPath is required when returnBuffer is false");
+  }
   const urlMatch = figmaUrl.match(/figma\.com\/(file|design)\/([a-zA-Z0-9]+)/);
   if (!urlMatch) {
     throw new Error("Invalid Figma URL format");
@@ -1473,8 +1554,9 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
       ...node,
       nodeId: node.nodeId.replace(/-/g, ":")
     }));
-    const results = await figmaService.downloadImages(fileKey, localPath, processedNodes, {
-      pngScale
+    const results = await figmaService.downloadImages(fileKey, localPath || "", processedNodes, {
+      pngScale,
+      returnBuffer
     });
     return results;
   } catch (error) {
@@ -1491,12 +1573,16 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     localPath,
     fileName,
     format = "png",
-    enableLogging = false
+    enableLogging = false,
+    returnBuffer = false
   } = options;
   Logger.enableLogging = enableLogging;
   if (!apiKey && !oauthToken) {
     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");
+  }
   const urlMatch = figmaUrl.match(/figma\.com\/(file|design)\/([a-zA-Z0-9]+)/);
   if (!urlMatch) {
     throw new Error("Invalid Figma URL format");
@@ -1507,9 +1593,11 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     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, ":");
-  const expectedExtension = `.${format}`;
-  if (!fileName.toLowerCase().endsWith(expectedExtension)) {
-    throw new Error(`Filename must end with ${expectedExtension} for ${format} format`);
+  if (fileName) {
+    const expectedExtension = `.${format}`;
+    if (!fileName.toLowerCase().endsWith(expectedExtension)) {
+      throw new Error(`Filename must end with ${expectedExtension} for ${format} format`);
+    }
   }
   const figmaService = new FigmaService({
     figmaApiKey: apiKey || "",
@@ -1520,15 +1608,20 @@ async function downloadFigmaFrameImage(figmaUrl, options) {
     Logger.log(`Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`);
     const imageNode = {
       nodeId,
-      fileName
+      fileName: fileName || `temp.${format}`
     };
-    const results = await figmaService.downloadImages(fileKey, localPath, [imageNode], {
-      pngScale: format === "png" ? pngScale : void 0
+    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}`);
     }
-    Logger.log(`Successfully downloaded frame image to: ${results[0].filePath}`);
+    if (returnBuffer) {
+      Logger.log(`Successfully downloaded frame image as buffer`);
+    } else {
+      Logger.log(`Successfully downloaded frame image to: ${results[0].filePath}`);
+    }
     return results[0];
   } catch (error) {
     Logger.error(`Error downloading frame image from ${fileKey}:`, error);
@@ -1566,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,12 +27,16 @@ 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) */
     pngScale?: number;
-    /** The absolute path to the directory where images should be stored */
-    localPath: string;
+    /** The absolute path to the directory where images should be stored (optional if returnBuffer is true) */
+    localPath?: string;
+    /** Return images as ArrayBuffer instead of saving to disk (defaults to false) */
+    returnBuffer?: boolean;
 }
 export interface FigmaImageNode {
     /** The ID of the Figma node, formatted as '1234:5678' */
@@ -54,9 +58,11 @@ export interface FigmaMetadataResult {
     metadata: any;
     nodes: any[];
     globalVars: any;
+    images?: FigmaImageResult[];
 }
 export interface FigmaImageResult {
-    filePath: string;
+    filePath?: string;
+    buffer?: ArrayBuffer;
     finalDimensions: {
         width: number;
         height: number;
@@ -73,14 +79,16 @@ export interface FigmaFrameImageOptions {
     useOAuth?: boolean;
     /** Export scale for PNG images (defaults to 2) */
     pngScale?: number;
-    /** The absolute path to the directory where the image should be stored */
-    localPath: string;
-    /** The filename for the downloaded image (must end with .png or .svg) */
-    fileName: string;
+    /** The absolute path to the directory where the image should be stored (optional if returnBuffer is true) */
+    localPath?: string;
+    /** 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';
     /** Enable JSON debug log files (defaults to false) */
     enableLogging?: boolean;
+    /** Return image as ArrayBuffer instead of saving to disk (defaults to false) */
+    returnBuffer?: boolean;
 }
 /**
  * Extract metadata from a Figma file or specific nodes
@@ -107,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/dist/services/figma.d.ts

@@ -49,6 +49,7 @@ export declare class FigmaService {
      * - PNG vs SVG format (based on filename extension)
      * - Image cropping based on transform matrices
      * - CSS variable generation for image dimensions
+     * - Returning as ArrayBuffer instead of saving to disk
      *
      * @returns Array of local file paths for successfully downloaded images
      */
@@ -62,6 +63,7 @@ export declare class FigmaService {
     }>, options?: {
         pngScale?: number;
         svgOptions?: SvgOptions;
+        returnBuffer?: boolean;
     }): Promise<ImageProcessingResult[]>;
     /**
      * Get raw Figma API response for a file (for use with flexible extractors)

package/dist/utils/common.d.ts

@@ -2,14 +2,15 @@ export type StyleId = `${string}_${string}` & {
     __brand: "StyleId";
 };
 /**
- * Download Figma image and save it locally
+ * Download Figma image and save it locally or return as buffer
  * @param fileName - The filename to save as
  * @param localPath - The local path to save to
  * @param imageUrl - Image URL (images[nodeId])
- * @returns A Promise that resolves to the full file path where the image was saved
+ * @param returnBuffer - If true, return ArrayBuffer instead of saving to disk
+ * @returns A Promise that resolves to the full file path where the image was saved, or ArrayBuffer if returnBuffer is true
  * @throws Error if download fails
  */
-export declare function downloadFigmaImage(fileName: string, localPath: string, imageUrl: string): Promise<string>;
+export declare function downloadFigmaImage(fileName: string, localPath: string, imageUrl: string, returnBuffer?: boolean): Promise<string | ArrayBuffer>;
 /**
  * Remove keys with empty arrays or empty objects from an object.
  * @param input - The input object or value.

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

@@ -16,7 +16,8 @@ export declare function getImageDimensions(imagePath: string): Promise<{
     height: number;
 }>;
 export type ImageProcessingResult = {
-    filePath: string;
+    filePath?: string;
+    buffer?: ArrayBuffer;
     originalDimensions: {
         width: number;
         height: number;
@@ -43,9 +44,10 @@ export type ImageProcessingResult = {
  * @param needsCropping - Whether to apply crop transform
  * @param cropTransform - Transform matrix for cropping
  * @param requiresImageDimensions - Whether to generate dimension metadata
+ * @param returnBuffer - If true, return ArrayBuffer instead of saving to disk
  * @returns Promise<ImageProcessingResult> - Detailed processing information
  */
-export declare function downloadAndProcessImage(fileName: string, localPath: string, imageUrl: string, needsCropping?: boolean, cropTransform?: Transform, requiresImageDimensions?: boolean): Promise<ImageProcessingResult>;
+export declare function downloadAndProcessImage(fileName: string, localPath: string, imageUrl: string, needsCropping?: boolean, cropTransform?: Transform, requiresImageDimensions?: boolean, returnBuffer?: boolean): Promise<ImageProcessingResult>;
 /**
  * Create CSS custom properties for image dimensions
  * @param imagePath - Path to the image file

package/package.json

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