figma-metadata-extractor 1.0.1 → 1.0.2

package/README.md

@@ -11,7 +11,7 @@ npm install figma-metadata-extractor
 ## Quick Start
 
 ```typescript
-import { getFigmaMetadata, downloadFigmaImages } from 'figma-metadata-extractor';
+import { getFigmaMetadata, downloadFigmaImages, downloadFigmaFrameImage } from 'figma-metadata-extractor';
 
 // Extract metadata from a Figma file
 const metadata = await getFigmaMetadata(
@@ -45,6 +45,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
@@ -90,6 +104,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 +137,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

@@ -1446,10 +1446,62 @@ 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)}`);
+  }
+}
 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

@@ -1444,11 +1444,63 @@ 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)}`);
+  }
+}
 export {
   allExtractors,
   collapseSvgContainers,
   componentExtractor,
   contentOnly,
+  downloadFigmaFrameImage,
   downloadFigmaImages,
   extractFromDesign,
   getFigmaMetadata,

package/dist/lib.d.ts

@@ -46,6 +46,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 +79,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.2",
+    "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",