figma-metadata-extractor 1.0.6 → 1.0.7

package/README.md

@@ -135,10 +135,14 @@ 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`.
+
 ### `downloadFigmaFrameImage(figmaUrl, options)`
 
 Downloads a single frame image from a Figma URL that contains a node-id parameter.
@@ -151,13 +155,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 +197,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 +210,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 +253,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 {
@@ -1455,11 +1524,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 +1547,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 +1566,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 +1586,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 +1601,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);

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 {
@@ -1453,11 +1522,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 +1545,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 +1564,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 +1584,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 +1599,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);

package/dist/lib.d.ts

@@ -31,8 +31,10 @@ export interface FigmaMetadataOptions {
 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' */
@@ -56,7 +58,8 @@ export interface FigmaMetadataResult {
     globalVars: any;
 }
 export interface FigmaImageResult {
-    filePath: string;
+    filePath?: string;
+    buffer?: ArrayBuffer;
     finalDimensions: {
         width: number;
         height: number;
@@ -73,14 +76,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

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.7",
     "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",