figma-metadata-extractor 1.0.1 → 1.0.3

package/README.md

@@ -10,8 +10,28 @@ npm install figma-metadata-extractor
 
 ## Quick Start
 
+### Get Metadata with Auto-Downloaded Images (LLM-Ready!)
+
+```typescript
+import { getFigmaMetadata } from 'figma-metadata-extractor';
+
+// Extract metadata AND automatically download image assets
+const metadata = await getFigmaMetadata(
+  'https://figma.com/file/ABC123/My-Design',
+  {
+    apiKey: 'your-figma-api-key',
+    outputFormat: 'object',
+    downloadImages: true,        // Auto-download image assets
+    localPath: './assets/images' // Where to save images
+  }
+);
+
+```
+
+### Get Metadata Only (No Downloads)
+
 ```typescript
-import { getFigmaMetadata, downloadFigmaImages } from 'figma-metadata-extractor';
+import { getFigmaMetadata } from 'figma-metadata-extractor';
 
 // Extract metadata from a Figma file
 const metadata = await getFigmaMetadata(
@@ -45,6 +65,20 @@ const images = await downloadFigmaImages(
 );
 
 console.log(images); // Array of download results
+
+// Download a single frame image from a Figma URL
+const frameImage = await downloadFigmaFrameImage(
+  'https://figma.com/file/ABC123/My-Design?node-id=1234-5678',
+  {
+    apiKey: 'your-figma-api-key',
+    localPath: './assets/frames',
+    fileName: 'my-frame.png',
+    format: 'png', // or 'svg'
+    pngScale: 2
+  }
+);
+
+console.log(frameImage.filePath); // Path to downloaded image
 ```
 
 ## API Reference
@@ -63,9 +97,24 @@ Extracts comprehensive metadata from a Figma file including layout, content, vis
 - `useOAuth?: boolean` - Whether to use OAuth instead of API key
 - `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)
+- `imageFormat?: 'png' | 'svg'` - Image format for downloads (default: 'png')
+- `pngScale?: number` - Export scale for PNG images (default: 2)
 
 **Returns:** Promise<FigmaMetadataResult | string>
 
+When `downloadImages` is true, nodes with image assets will include a `downloadedImage` property:
+```typescript
+{
+  filePath: string;           // Absolute path
+  relativePath: string;       // Relative path for code
+  dimensions: { width, height };
+  markdown: string;           // ![name](path)
+  html: string;              // <img src="..." />
+}
+```
+
 ### `downloadFigmaImages(figmaUrl, nodes, options)`
 
 Downloads SVG and PNG images from a Figma file.
@@ -90,6 +139,25 @@ Downloads SVG and PNG images from a Figma file.
 
 **Returns:** Promise<FigmaImageResult[]>
 
+### `downloadFigmaFrameImage(figmaUrl, options)`
+
+Downloads a single frame image from a Figma URL that contains a node-id parameter.
+
+**Parameters:**
+- `figmaUrl` (string): The Figma URL with node-id parameter (e.g., `https://figma.com/file/ABC123/My-Design?node-id=1234-5678`)
+- `options` (FigmaFrameImageOptions): Configuration options
+
+**Options:**
+- `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)
+- `format?: 'png' | 'svg'` - Image format to download (default: 'png')
+- `pngScale?: number` - Export scale for PNG images (default: 2)
+
+**Returns:** Promise<FigmaImageResult>
+
 ## Authentication
 
 You need either a Figma API key or OAuth token:
@@ -104,6 +172,50 @@ You need either a Figma API key or OAuth token:
 2. Use the bearer token in the `oauthToken` option
 3. Set `useOAuth: true`
 
+## Usage Examples
+
+### Download Frame Image from Figma URL
+
+The easiest way to download a frame image is to copy the Figma URL directly from your browser when viewing a specific frame:
+
+```typescript
+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';
+
+const result = await downloadFigmaFrameImage(figmaUrl, {
+  apiKey: 'your-figma-api-key',
+  localPath: './downloads',
+  fileName: 'my-frame.png',
+  format: 'png',
+  pngScale: 2 // High resolution
+});
+
+console.log(`Downloaded to: ${result.filePath}`);
+console.log(`Dimensions: ${result.finalDimensions.width}x${result.finalDimensions.height}`);
+```
+
+### Download Multiple Frame Images
+
+```typescript
+import { downloadFigmaImages } from 'figma-metadata-extractor';
+
+// For multiple frames, use the batch download function
+const results = await downloadFigmaImages(
+  'https://figma.com/file/ABC123/My-Design',
+  [
+    { nodeId: '1234:5678', fileName: 'frame1.png' },
+    { nodeId: '9876:5432', fileName: 'frame2.svg' },
+    { nodeId: '1111:2222', fileName: 'frame3.png' }
+  ],
+  {
+    apiKey: 'your-figma-api-key',
+    localPath: './frames'
+  }
+);
+```
+
 ## Advanced Usage
 
 The library also exports the underlying extractor system for custom processing:

package/dist/index.cjs

@@ -1365,7 +1365,17 @@ function collapseSvgContainers(node, result, children) {
   return children;
 }
 async function getFigmaMetadata(figmaUrl, options = {}) {
-  const { apiKey, oauthToken, useOAuth = false, outputFormat = "object", depth } = options;
+  const {
+    apiKey,
+    oauthToken,
+    useOAuth = false,
+    outputFormat = "object",
+    depth,
+    downloadImages = false,
+    localPath,
+    imageFormat = "png",
+    pngScale = 2
+  } = options;
   if (!apiKey && !oauthToken) {
     throw new Error("Either apiKey or oauthToken is required");
   }
@@ -1399,11 +1409,33 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
       `Successfully extracted data: ${simplifiedDesign.nodes.length} nodes, ${Object.keys(simplifiedDesign.globalVars?.styles || {}).length} styles`
     );
     const { nodes, globalVars, ...metadata } = simplifiedDesign;
-    const result = {
+    let result = {
       metadata,
       nodes,
       globalVars
     };
+    if (downloadImages) {
+      if (!localPath) {
+        throw new Error("localPath is required when downloadImages is true");
+      }
+      Logger.log("Discovering and downloading image assets...");
+      const imageAssets = findImageAssets(nodes, globalVars);
+      Logger.log(`Found ${imageAssets.length} image assets to download`);
+      if (imageAssets.length > 0) {
+        const imageNodes = imageAssets.map((asset) => ({
+          nodeId: asset.id,
+          fileName: sanitizeFileName(asset.name) + `.${imageFormat}`
+        }));
+        const downloadResults = await figmaService.downloadImages(
+          fileKey,
+          localPath,
+          imageNodes,
+          { pngScale: imageFormat === "png" ? pngScale : void 0 }
+        );
+        result.nodes = enrichNodesWithImages(nodes, imageAssets, downloadResults);
+        Logger.log(`Successfully downloaded and enriched ${downloadResults.length} images`);
+      }
+    }
     if (outputFormat === "json") {
       return JSON.stringify(result, null, 2);
     } else if (outputFormat === "yaml") {
@@ -1446,10 +1478,116 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
     throw new Error(`Failed to download images: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
+async function downloadFigmaFrameImage(figmaUrl, options) {
+  const {
+    apiKey,
+    oauthToken,
+    useOAuth = false,
+    pngScale = 2,
+    localPath,
+    fileName,
+    format = "png"
+  } = options;
+  if (!apiKey && !oauthToken) {
+    throw new Error("Either apiKey or oauthToken is required");
+  }
+  const urlMatch = figmaUrl.match(/figma\.com\/(file|design)\/([a-zA-Z0-9]+)/);
+  if (!urlMatch) {
+    throw new Error("Invalid Figma URL format");
+  }
+  const fileKey = urlMatch[2];
+  const nodeIdMatch = figmaUrl.match(/node-id=([^&]+)/);
+  if (!nodeIdMatch) {
+    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`);
+  }
+  const figmaService = new FigmaService({
+    figmaApiKey: apiKey || "",
+    figmaOAuthToken: oauthToken || "",
+    useOAuth: useOAuth && !!oauthToken
+  });
+  try {
+    Logger.log(`Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`);
+    const imageNode = {
+      nodeId,
+      fileName
+    };
+    const results = await figmaService.downloadImages(fileKey, localPath, [imageNode], {
+      pngScale: format === "png" ? pngScale : void 0
+    });
+    if (results.length === 0) {
+      throw new Error(`Failed to download image for frame ${nodeId}`);
+    }
+    Logger.log(`Successfully downloaded frame image to: ${results[0].filePath}`);
+    return results[0];
+  } catch (error) {
+    Logger.error(`Error downloading frame image from ${fileKey}:`, error);
+    throw new Error(`Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function sanitizeFileName(name) {
+  return name.replace(/[^a-z0-9]/gi, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+function findImageAssets(nodes, globalVars) {
+  const images = [];
+  function traverse(node) {
+    const isImageAsset = node.type === "IMAGE-SVG" || hasImageFill(node, globalVars);
+    if (isImageAsset) {
+      images.push(node);
+    }
+    if (node.children && Array.isArray(node.children)) {
+      node.children.forEach(traverse);
+    }
+  }
+  nodes.forEach(traverse);
+  return images;
+}
+function hasImageFill(node, globalVars) {
+  if (!node.fills || typeof node.fills !== "string") {
+    return false;
+  }
+  const fillData = globalVars?.styles?.[node.fills];
+  if (!fillData || !Array.isArray(fillData)) {
+    return false;
+  }
+  return fillData.some((fill) => fill?.type === "IMAGE");
+}
+function enrichNodesWithImages(nodes, imageAssets, downloadResults) {
+  const imageMap = /* @__PURE__ */ new Map();
+  imageAssets.forEach((asset, index) => {
+    const result = downloadResults[index];
+    if (result) {
+      imageMap.set(asset.id, {
+        filePath: result.filePath,
+        relativePath: result.filePath.replace(process.cwd(), "."),
+        dimensions: result.finalDimensions,
+        wasCropped: result.wasCropped,
+        markdown: `![${asset.name}](${result.filePath.replace(process.cwd(), ".")})`,
+        html: `<img src="${result.filePath.replace(process.cwd(), ".")}" alt="${asset.name}" width="${result.finalDimensions.width}" height="${result.finalDimensions.height}">`
+      });
+    }
+  });
+  function enrichNode(node) {
+    const enriched = { ...node };
+    if (imageMap.has(node.id)) {
+      enriched.downloadedImage = imageMap.get(node.id);
+    }
+    if (node.children && Array.isArray(node.children)) {
+      enriched.children = node.children.map(enrichNode);
+    }
+    return enriched;
+  }
+  return nodes.map(enrichNode);
+}
 exports.allExtractors = allExtractors;
 exports.collapseSvgContainers = collapseSvgContainers;
 exports.componentExtractor = componentExtractor;
 exports.contentOnly = contentOnly;
+exports.downloadFigmaFrameImage = downloadFigmaFrameImage;
 exports.downloadFigmaImages = downloadFigmaImages;
 exports.extractFromDesign = extractFromDesign;
 exports.getFigmaMetadata = getFigmaMetadata;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { getFigmaMetadata, downloadFigmaImages, type FigmaMetadataOptions, type FigmaImageOptions, type FigmaImageNode, type FigmaMetadataResult, type FigmaImageResult, } from "./lib.js";
+export { getFigmaMetadata, downloadFigmaImages, downloadFigmaFrameImage, type FigmaMetadataOptions, type FigmaImageOptions, type FigmaFrameImageOptions, type FigmaImageNode, type FigmaMetadataResult, type FigmaImageResult, } from "./lib.js";
 export type { SimplifiedDesign } from "./extractors/types.js";
 export type { ExtractorFn, TraversalContext, TraversalOptions, GlobalVars, StyleTypes, } from "./extractors/index.js";
 export { extractFromDesign, simplifyRawFigmaObject, layoutExtractor, textExtractor, visualsExtractor, componentExtractor, allExtractors, layoutAndText, contentOnly, visualsOnly, layoutOnly, collapseSvgContainers, } from "./extractors/index.js";

package/dist/index.js

@@ -1363,7 +1363,17 @@ function collapseSvgContainers(node, result, children) {
   return children;
 }
 async function getFigmaMetadata(figmaUrl, options = {}) {
-  const { apiKey, oauthToken, useOAuth = false, outputFormat = "object", depth } = options;
+  const {
+    apiKey,
+    oauthToken,
+    useOAuth = false,
+    outputFormat = "object",
+    depth,
+    downloadImages = false,
+    localPath,
+    imageFormat = "png",
+    pngScale = 2
+  } = options;
   if (!apiKey && !oauthToken) {
     throw new Error("Either apiKey or oauthToken is required");
   }
@@ -1397,11 +1407,33 @@ async function getFigmaMetadata(figmaUrl, options = {}) {
       `Successfully extracted data: ${simplifiedDesign.nodes.length} nodes, ${Object.keys(simplifiedDesign.globalVars?.styles || {}).length} styles`
     );
     const { nodes, globalVars, ...metadata } = simplifiedDesign;
-    const result = {
+    let result = {
       metadata,
       nodes,
       globalVars
     };
+    if (downloadImages) {
+      if (!localPath) {
+        throw new Error("localPath is required when downloadImages is true");
+      }
+      Logger.log("Discovering and downloading image assets...");
+      const imageAssets = findImageAssets(nodes, globalVars);
+      Logger.log(`Found ${imageAssets.length} image assets to download`);
+      if (imageAssets.length > 0) {
+        const imageNodes = imageAssets.map((asset) => ({
+          nodeId: asset.id,
+          fileName: sanitizeFileName(asset.name) + `.${imageFormat}`
+        }));
+        const downloadResults = await figmaService.downloadImages(
+          fileKey,
+          localPath,
+          imageNodes,
+          { pngScale: imageFormat === "png" ? pngScale : void 0 }
+        );
+        result.nodes = enrichNodesWithImages(nodes, imageAssets, downloadResults);
+        Logger.log(`Successfully downloaded and enriched ${downloadResults.length} images`);
+      }
+    }
     if (outputFormat === "json") {
       return JSON.stringify(result, null, 2);
     } else if (outputFormat === "yaml") {
@@ -1444,11 +1476,117 @@ async function downloadFigmaImages(figmaUrl, nodes, options) {
     throw new Error(`Failed to download images: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
+async function downloadFigmaFrameImage(figmaUrl, options) {
+  const {
+    apiKey,
+    oauthToken,
+    useOAuth = false,
+    pngScale = 2,
+    localPath,
+    fileName,
+    format = "png"
+  } = options;
+  if (!apiKey && !oauthToken) {
+    throw new Error("Either apiKey or oauthToken is required");
+  }
+  const urlMatch = figmaUrl.match(/figma\.com\/(file|design)\/([a-zA-Z0-9]+)/);
+  if (!urlMatch) {
+    throw new Error("Invalid Figma URL format");
+  }
+  const fileKey = urlMatch[2];
+  const nodeIdMatch = figmaUrl.match(/node-id=([^&]+)/);
+  if (!nodeIdMatch) {
+    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`);
+  }
+  const figmaService = new FigmaService({
+    figmaApiKey: apiKey || "",
+    figmaOAuthToken: oauthToken || "",
+    useOAuth: useOAuth && !!oauthToken
+  });
+  try {
+    Logger.log(`Downloading ${format.toUpperCase()} image for frame ${nodeId} from file ${fileKey}`);
+    const imageNode = {
+      nodeId,
+      fileName
+    };
+    const results = await figmaService.downloadImages(fileKey, localPath, [imageNode], {
+      pngScale: format === "png" ? pngScale : void 0
+    });
+    if (results.length === 0) {
+      throw new Error(`Failed to download image for frame ${nodeId}`);
+    }
+    Logger.log(`Successfully downloaded frame image to: ${results[0].filePath}`);
+    return results[0];
+  } catch (error) {
+    Logger.error(`Error downloading frame image from ${fileKey}:`, error);
+    throw new Error(`Failed to download frame image: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function sanitizeFileName(name) {
+  return name.replace(/[^a-z0-9]/gi, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+function findImageAssets(nodes, globalVars) {
+  const images = [];
+  function traverse(node) {
+    const isImageAsset = node.type === "IMAGE-SVG" || hasImageFill(node, globalVars);
+    if (isImageAsset) {
+      images.push(node);
+    }
+    if (node.children && Array.isArray(node.children)) {
+      node.children.forEach(traverse);
+    }
+  }
+  nodes.forEach(traverse);
+  return images;
+}
+function hasImageFill(node, globalVars) {
+  if (!node.fills || typeof node.fills !== "string") {
+    return false;
+  }
+  const fillData = globalVars?.styles?.[node.fills];
+  if (!fillData || !Array.isArray(fillData)) {
+    return false;
+  }
+  return fillData.some((fill) => fill?.type === "IMAGE");
+}
+function enrichNodesWithImages(nodes, imageAssets, downloadResults) {
+  const imageMap = /* @__PURE__ */ new Map();
+  imageAssets.forEach((asset, index) => {
+    const result = downloadResults[index];
+    if (result) {
+      imageMap.set(asset.id, {
+        filePath: result.filePath,
+        relativePath: result.filePath.replace(process.cwd(), "."),
+        dimensions: result.finalDimensions,
+        wasCropped: result.wasCropped,
+        markdown: `![${asset.name}](${result.filePath.replace(process.cwd(), ".")})`,
+        html: `<img src="${result.filePath.replace(process.cwd(), ".")}" alt="${asset.name}" width="${result.finalDimensions.width}" height="${result.finalDimensions.height}">`
+      });
+    }
+  });
+  function enrichNode(node) {
+    const enriched = { ...node };
+    if (imageMap.has(node.id)) {
+      enriched.downloadedImage = imageMap.get(node.id);
+    }
+    if (node.children && Array.isArray(node.children)) {
+      enriched.children = node.children.map(enrichNode);
+    }
+    return enriched;
+  }
+  return nodes.map(enrichNode);
+}
 export {
   allExtractors,
   collapseSvgContainers,
   componentExtractor,
   contentOnly,
+  downloadFigmaFrameImage,
   downloadFigmaImages,
   extractFromDesign,
   getFigmaMetadata,

package/dist/lib.d.ts

@@ -9,6 +9,14 @@ export interface FigmaMetadataOptions {
     outputFormat?: "json" | "yaml" | "object";
     /** Maximum depth to traverse the node tree */
     depth?: number;
+    /** Automatically download image assets and enrich metadata with file paths */
+    downloadImages?: boolean;
+    /** Local path for downloaded images (required if downloadImages is true) */
+    localPath?: string;
+    /** Image format for downloads (defaults to 'png') */
+    imageFormat?: 'png' | 'svg';
+    /** Export scale for PNG images (defaults to 2) */
+    pngScale?: number;
 }
 export interface FigmaImageOptions {
     /** Export scale for PNG images (defaults to 2) */
@@ -46,6 +54,22 @@ export interface FigmaImageResult {
     wasCropped: boolean;
     cssVariables?: string;
 }
+export interface FigmaFrameImageOptions {
+    /** The Figma API key (Personal Access Token) */
+    apiKey?: string;
+    /** The Figma OAuth Bearer token */
+    oauthToken?: string;
+    /** Whether to use OAuth instead of API key */
+    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;
+    /** Image format to download (defaults to 'png') */
+    format?: 'png' | 'svg';
+}
 /**
  * Extract metadata from a Figma file or specific nodes
  *
@@ -63,6 +87,14 @@ export declare function getFigmaMetadata(figmaUrl: string, options?: FigmaMetada
  * @returns Promise resolving to array of download results
  */
 export declare function downloadFigmaImages(figmaUrl: string, nodes: FigmaImageNode[], options: FigmaMetadataOptions & FigmaImageOptions): Promise<FigmaImageResult[]>;
+/**
+ * Download a frame image from a Figma URL
+ *
+ * @param figmaUrl - The Figma URL containing the frame (with node-id parameter)
+ * @param options - Configuration options including API credentials, local path, and filename
+ * @returns Promise resolving to the download result
+ */
+export declare function downloadFigmaFrameImage(figmaUrl: string, options: FigmaFrameImageOptions): Promise<FigmaImageResult>;
 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,7 +1,7 @@
 {
     "name": "figma-metadata-extractor",
-    "version": "1.0.1",
-    "description": "Extract metadata and download images from Figma files. A standalone library for accessing Figma design data programmatically.",
+    "version": "1.0.3",
+    "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",
     "module": "dist/index.js",