figma-metadata-extractor 1.0.0 → 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/extractors/built-in.d.ts

@@ -0,0 +1,56 @@
+import type { ExtractorFn, SimplifiedNode } from "./types.js";
+import type { Node as FigmaDocumentNode } from "@figma/rest-api-spec";
+/**
+ * Extracts layout-related properties from a node.
+ */
+export declare const layoutExtractor: ExtractorFn;
+/**
+ * Extracts text content and text styling from a node.
+ */
+export declare const textExtractor: ExtractorFn;
+/**
+ * Extracts visual appearance properties (fills, strokes, effects, opacity, border radius).
+ */
+export declare const visualsExtractor: ExtractorFn;
+/**
+ * Extracts component-related properties from INSTANCE nodes.
+ */
+export declare const componentExtractor: ExtractorFn;
+/**
+ * All extractors - replicates the current parseNode behavior.
+ */
+export declare const allExtractors: ExtractorFn[];
+/**
+ * Layout and text only - useful for content analysis and layout planning.
+ */
+export declare const layoutAndText: ExtractorFn[];
+/**
+ * Text content only - useful for content audits and copy extraction.
+ */
+export declare const contentOnly: ExtractorFn[];
+/**
+ * Visuals only - useful for design system analysis and style extraction.
+ */
+export declare const visualsOnly: ExtractorFn[];
+/**
+ * Layout only - useful for structure analysis.
+ */
+export declare const layoutOnly: ExtractorFn[];
+/**
+ * Node types that can be exported as SVG images.
+ * When a FRAME, GROUP, or INSTANCE contains only these types, we can collapse it to IMAGE-SVG.
+ * Note: FRAME/GROUP/INSTANCE are NOT included here—they're only eligible if collapsed to IMAGE-SVG.
+ */
+export declare const SVG_ELIGIBLE_TYPES: Set<string>;
+/**
+ * afterChildren callback that collapses SVG-heavy containers to IMAGE-SVG.
+ *
+ * If a FRAME, GROUP, or INSTANCE contains only SVG-eligible children, the parent
+ * is marked as IMAGE-SVG and children are omitted, reducing payload size.
+ *
+ * @param node - Original Figma node
+ * @param result - SimplifiedNode being built
+ * @param children - Processed children
+ * @returns Children to include (empty array if collapsed)
+ */
+export declare function collapseSvgContainers(node: FigmaDocumentNode, result: SimplifiedNode, children: SimplifiedNode[]): SimplifiedNode[];

package/dist/extractors/design-extractor.d.ts

@@ -0,0 +1,6 @@
+import type { GetFileResponse, GetFileNodesResponse } from "@figma/rest-api-spec";
+import type { ExtractorFn, TraversalOptions, SimplifiedDesign } from "./types.js";
+/**
+ * Extract a complete SimplifiedDesign from raw Figma API response using extractors.
+ */
+export declare function simplifyRawFigmaObject(apiResponse: GetFileResponse | GetFileNodesResponse, nodeExtractors: ExtractorFn[], options?: TraversalOptions): SimplifiedDesign;

package/dist/extractors/index.d.ts

@@ -0,0 +1,4 @@
+export type { ExtractorFn, TraversalContext, TraversalOptions, GlobalVars, StyleTypes, } from "./types.js";
+export { extractFromDesign } from "./node-walker.js";
+export { simplifyRawFigmaObject } from "./design-extractor.js";
+export { layoutExtractor, textExtractor, visualsExtractor, componentExtractor, allExtractors, layoutAndText, contentOnly, visualsOnly, layoutOnly, collapseSvgContainers, SVG_ELIGIBLE_TYPES, } from "./built-in.js";

package/dist/extractors/node-walker.d.ts

@@ -0,0 +1,15 @@
+import type { Node as FigmaDocumentNode } from "@figma/rest-api-spec";
+import type { ExtractorFn, TraversalOptions, GlobalVars, SimplifiedNode } from "./types.js";
+/**
+ * Extract data from Figma nodes using a flexible, single-pass approach.
+ *
+ * @param nodes - The Figma nodes to process
+ * @param extractors - Array of extractor functions to apply during traversal
+ * @param options - Traversal options (filtering, depth limits, etc.)
+ * @param globalVars - Global variables for style deduplication
+ * @returns Object containing processed nodes and updated global variables
+ */
+export declare function extractFromDesign(nodes: FigmaDocumentNode[], extractors: ExtractorFn[], options?: TraversalOptions, globalVars?: GlobalVars): {
+    nodes: SimplifiedNode[];
+    globalVars: GlobalVars;
+};

package/dist/extractors/types.d.ts

@@ -0,0 +1,72 @@
+import type { Node as FigmaDocumentNode, Style } from "@figma/rest-api-spec";
+import type { SimplifiedTextStyle } from "~/transformers/text.js";
+import type { SimplifiedLayout } from "~/transformers/layout.js";
+import type { SimplifiedFill, SimplifiedStroke } from "~/transformers/style.js";
+import type { SimplifiedEffects } from "~/transformers/effects.js";
+import type { ComponentProperties, SimplifiedComponentDefinition, SimplifiedComponentSetDefinition } from "~/transformers/component.js";
+export type StyleTypes = SimplifiedTextStyle | SimplifiedFill[] | SimplifiedLayout | SimplifiedStroke | SimplifiedEffects | string;
+export type GlobalVars = {
+    styles: Record<string, StyleTypes>;
+};
+export interface TraversalContext {
+    globalVars: GlobalVars & {
+        extraStyles?: Record<string, Style>;
+    };
+    currentDepth: number;
+    parent?: FigmaDocumentNode;
+}
+export interface TraversalOptions {
+    maxDepth?: number;
+    nodeFilter?: (node: FigmaDocumentNode) => boolean;
+    /**
+     * Called after children are processed, allowing modification of the parent node
+     * and control over which children to include in the output.
+     *
+     * @param node - Original Figma node
+     * @param result - SimplifiedNode being built (can be mutated)
+     * @param children - Processed children
+     * @returns Children to include (return empty array to omit children)
+     */
+    afterChildren?: (node: FigmaDocumentNode, result: SimplifiedNode, children: SimplifiedNode[]) => SimplifiedNode[];
+}
+/**
+ * An extractor function that can modify a SimplifiedNode during traversal.
+ *
+ * @param node - The current Figma node being processed
+ * @param result - SimplifiedNode object being built—this can be mutated inside the extractor
+ * @param context - Traversal context including globalVars and parent info. This can also be mutated inside the extractor.
+ */
+export type ExtractorFn = (node: FigmaDocumentNode, result: SimplifiedNode, context: TraversalContext) => void;
+export interface SimplifiedDesign {
+    name: string;
+    nodes: SimplifiedNode[];
+    components: Record<string, SimplifiedComponentDefinition>;
+    componentSets: Record<string, SimplifiedComponentSetDefinition>;
+    globalVars: GlobalVars;
+}
+export interface SimplifiedNode {
+    id: string;
+    name: string;
+    type: string;
+    text?: string;
+    textStyle?: string;
+    fills?: string;
+    styles?: string;
+    strokes?: string;
+    strokeWeight?: string;
+    strokeDashes?: number[];
+    strokeWeights?: string;
+    effects?: string;
+    opacity?: number;
+    borderRadius?: string;
+    layout?: string;
+    componentId?: string;
+    componentProperties?: ComponentProperties[];
+    children?: SimplifiedNode[];
+}
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}

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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +1,92 @@
+export interface FigmaMetadataOptions {
+    /** 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;
+    /** Output format for the metadata */
+    outputFormat?: "json" | "yaml" | "object";
+    /** Maximum depth to traverse the node tree */
+    depth?: number;
+}
+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;
+}
+export interface FigmaImageNode {
+    /** The ID of the Figma node, formatted as '1234:5678' */
+    nodeId: string;
+    /** If a node has an imageRef fill, include this variable */
+    imageRef?: string;
+    /** The local filename for saving the image (must end with .png or .svg) */
+    fileName: string;
+    /** Whether this image needs cropping based on its transform matrix */
+    needsCropping?: boolean;
+    /** Figma transform matrix for image cropping */
+    cropTransform?: number[][];
+    /** Whether this image requires dimension information for CSS variables */
+    requiresImageDimensions?: boolean;
+    /** Suffix to add to filename for unique cropped images */
+    filenameSuffix?: string;
+}
+export interface FigmaMetadataResult {
+    metadata: any;
+    nodes: any[];
+    globalVars: any;
+}
+export interface FigmaImageResult {
+    filePath: string;
+    finalDimensions: {
+        width: number;
+        height: number;
+    };
+    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
+ *
+ * @param figmaUrl - The Figma file URL (e.g., https://figma.com/file/ABC123/...)
+ * @param options - Configuration options including API credentials
+ * @returns Promise resolving to the extracted metadata
+ */
+export declare function getFigmaMetadata(figmaUrl: string, options?: FigmaMetadataOptions): Promise<FigmaMetadataResult | string>;
+/**
+ * Download images from a Figma file
+ *
+ * @param figmaUrl - The Figma file URL
+ * @param nodes - Array of image nodes to download
+ * @param options - Configuration options including API credentials and local path
+ * @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/dist/services/figma.d.ts

@@ -0,0 +1,75 @@
+import type { GetFileResponse, GetFileNodesResponse } from "@figma/rest-api-spec";
+import { type ImageProcessingResult } from "~/utils/image-processing.js";
+export type FigmaAuthOptions = {
+    figmaApiKey: string;
+    figmaOAuthToken: string;
+    useOAuth: boolean;
+};
+type SvgOptions = {
+    outlineText: boolean;
+    includeId: boolean;
+    simplifyStroke: boolean;
+};
+export declare class FigmaService {
+    private readonly apiKey;
+    private readonly oauthToken;
+    private readonly useOAuth;
+    private readonly baseUrl;
+    constructor({ figmaApiKey, figmaOAuthToken, useOAuth }: FigmaAuthOptions);
+    private getAuthHeaders;
+    /**
+     * Filters out null values from Figma image responses. This ensures we only work with valid image URLs.
+     */
+    private filterValidImages;
+    private request;
+    /**
+     * Builds URL query parameters for SVG image requests.
+     */
+    private buildSvgQueryParams;
+    /**
+     * Gets download URLs for image fills without downloading them.
+     *
+     * @returns Map of imageRef to download URL
+     */
+    getImageFillUrls(fileKey: string): Promise<Record<string, string>>;
+    /**
+     * Gets download URLs for rendered nodes without downloading them.
+     *
+     * @returns Map of node ID to download URL
+     */
+    getNodeRenderUrls(fileKey: string, nodeIds: string[], format: "png" | "svg", options?: {
+        pngScale?: number;
+        svgOptions?: SvgOptions;
+    }): Promise<Record<string, string>>;
+    /**
+     * Download images method with post-processing support for cropping and returning image dimensions.
+     *
+     * Supports:
+     * - Image fills vs rendered nodes (based on imageRef vs nodeId)
+     * - PNG vs SVG format (based on filename extension)
+     * - Image cropping based on transform matrices
+     * - CSS variable generation for image dimensions
+     *
+     * @returns Array of local file paths for successfully downloaded images
+     */
+    downloadImages(fileKey: string, localPath: string, items: Array<{
+        imageRef?: string;
+        nodeId?: string;
+        fileName: string;
+        needsCropping?: boolean;
+        cropTransform?: any;
+        requiresImageDimensions?: boolean;
+    }>, options?: {
+        pngScale?: number;
+        svgOptions?: SvgOptions;
+    }): Promise<ImageProcessingResult[]>;
+    /**
+     * Get raw Figma API response for a file (for use with flexible extractors)
+     */
+    getRawFile(fileKey: string, depth?: number | null): Promise<GetFileResponse>;
+    /**
+     * Get raw Figma API response for specific nodes (for use with flexible extractors)
+     */
+    getRawNode(fileKey: string, nodeId: string, depth?: number | null): Promise<GetFileNodesResponse>;
+}
+export {};

package/dist/transformers/component.d.ts

@@ -0,0 +1,26 @@
+import type { Component, ComponentPropertyType, ComponentSet } from "@figma/rest-api-spec";
+export interface ComponentProperties {
+    name: string;
+    value: string;
+    type: ComponentPropertyType;
+}
+export interface SimplifiedComponentDefinition {
+    id: string;
+    key: string;
+    name: string;
+    componentSetId?: string;
+}
+export interface SimplifiedComponentSetDefinition {
+    id: string;
+    key: string;
+    name: string;
+    description?: string;
+}
+/**
+ * Remove unnecessary component properties and convert to simplified format.
+ */
+export declare function simplifyComponents(aggregatedComponents: Record<string, Component>): Record<string, SimplifiedComponentDefinition>;
+/**
+ * Remove unnecessary component set properties and convert to simplified format.
+ */
+export declare function simplifyComponentSets(aggregatedComponentSets: Record<string, ComponentSet>): Record<string, SimplifiedComponentSetDefinition>;

package/dist/transformers/effects.d.ts

@@ -0,0 +1,8 @@
+import type { Node as FigmaDocumentNode } from "@figma/rest-api-spec";
+export type SimplifiedEffects = {
+    boxShadow?: string;
+    filter?: string;
+    backdropFilter?: string;
+    textShadow?: string;
+};
+export declare function buildSimplifiedEffects(n: FigmaDocumentNode): SimplifiedEffects;

package/dist/transformers/layout.d.ts

@@ -0,0 +1,26 @@
+import type { Node as FigmaDocumentNode } from "@figma/rest-api-spec";
+export interface SimplifiedLayout {
+    mode: "none" | "row" | "column";
+    justifyContent?: "flex-start" | "flex-end" | "center" | "space-between" | "baseline" | "stretch";
+    alignItems?: "flex-start" | "flex-end" | "center" | "space-between" | "baseline" | "stretch";
+    alignSelf?: "flex-start" | "flex-end" | "center" | "stretch";
+    wrap?: boolean;
+    gap?: string;
+    locationRelativeToParent?: {
+        x: number;
+        y: number;
+    };
+    dimensions?: {
+        width?: number;
+        height?: number;
+        aspectRatio?: number;
+    };
+    padding?: string;
+    sizing?: {
+        horizontal?: "fixed" | "fill" | "hug";
+        vertical?: "fixed" | "fill" | "hug";
+    };
+    overflowScroll?: ("x" | "y")[];
+    position?: "absolute";
+}
+export declare function buildSimplifiedLayout(n: FigmaDocumentNode, parent?: FigmaDocumentNode): SimplifiedLayout;

package/dist/transformers/style.d.ts

@@ -0,0 +1,119 @@
+import type { Node as FigmaDocumentNode, Paint, RGBA, Transform } from "@figma/rest-api-spec";
+export type CSSRGBAColor = `rgba(${number}, ${number}, ${number}, ${number})`;
+export type CSSHexColor = `#${string}`;
+export interface ColorValue {
+    hex: CSSHexColor;
+    opacity: number;
+}
+/**
+ * Simplified image fill with CSS properties and processing metadata
+ *
+ * This type represents an image fill that can be used as either:
+ * - background-image (when parent node has children)
+ * - <img> tag (when parent node has no children)
+ *
+ * The CSS properties are mutually exclusive based on usage context.
+ */
+export type SimplifiedImageFill = {
+    type: "IMAGE";
+    imageRef: string;
+    scaleMode: "FILL" | "FIT" | "TILE" | "STRETCH";
+    /**
+     * For TILE mode, the scaling factor relative to original image size
+     */
+    scalingFactor?: number;
+    backgroundSize?: string;
+    backgroundRepeat?: string;
+    isBackground?: boolean;
+    objectFit?: string;
+    imageDownloadArguments?: {
+        /**
+         * Whether image needs cropping based on transform
+         */
+        needsCropping: boolean;
+        /**
+         * Whether CSS variables for dimensions are needed to calculate the background size for TILE mode
+         *
+         * Figma bases scalingFactor on the image's original size. In CSS, background size (as a percentage)
+         * is calculated based on the size of the container. We need to pass back the original dimensions
+         * after processing to calculate the intended background size when translated to code.
+         */
+        requiresImageDimensions: boolean;
+        /**
+         * Figma's transform matrix for Sharp processing
+         */
+        cropTransform?: Transform;
+        /**
+         * Suggested filename suffix to make cropped images unique
+         * When the same imageRef is used multiple times with different crops,
+         * this helps avoid overwriting conflicts
+         */
+        filenameSuffix?: string;
+    };
+};
+export type SimplifiedGradientFill = {
+    type: "GRADIENT_LINEAR" | "GRADIENT_RADIAL" | "GRADIENT_ANGULAR" | "GRADIENT_DIAMOND";
+    gradient: string;
+};
+export type SimplifiedPatternFill = {
+    type: "PATTERN";
+    patternSource: {
+        /**
+         * Hardcode to expect PNG for now, consider SVG detection in the future.
+         *
+         * SVG detection is a bit challenging because the nodeId in question isn't
+         * guaranteed to be included in the response we're working with. No guaranteed
+         * way to look into it and see if it's only composed of vector shapes.
+         */
+        type: "IMAGE-PNG";
+        nodeId: string;
+    };
+    backgroundRepeat: string;
+    backgroundSize: string;
+    backgroundPosition: string;
+};
+export type SimplifiedFill = SimplifiedImageFill | SimplifiedGradientFill | SimplifiedPatternFill | CSSRGBAColor | CSSHexColor;
+export type SimplifiedStroke = {
+    colors: SimplifiedFill[];
+    strokeWeight?: string;
+    strokeDashes?: number[];
+    strokeWeights?: string;
+};
+/**
+ * Build simplified stroke information from a Figma node
+ *
+ * @param n - The Figma node to extract stroke information from
+ * @param hasChildren - Whether the node has children (affects paint processing)
+ * @returns Simplified stroke object with colors and properties
+ */
+export declare function buildSimplifiedStrokes(n: FigmaDocumentNode, hasChildren?: boolean): SimplifiedStroke;
+/**
+ * Convert a Figma paint (solid, image, gradient) to a SimplifiedFill
+ * @param raw - The Figma paint to convert
+ * @param hasChildren - Whether the node has children (determines CSS properties)
+ * @returns The converted SimplifiedFill
+ */
+export declare function parsePaint(raw: Paint, hasChildren?: boolean): SimplifiedFill;
+/**
+ * Convert hex color value and opacity to rgba format
+ * @param hex - Hexadecimal color value (e.g., "#FF0000" or "#F00")
+ * @param opacity - Opacity value (0-1)
+ * @returns Color string in rgba format
+ */
+export declare function hexToRgba(hex: string, opacity?: number): string;
+/**
+ * Convert color from RGBA to { hex, opacity }
+ *
+ * @param color - The color to convert, including alpha channel
+ * @param opacity - The opacity of the color, if not included in alpha channel
+ * @returns The converted color
+ **/
+export declare function convertColor(color: RGBA, opacity?: number): ColorValue;
+/**
+ * Convert color from Figma RGBA to rgba(#, #, #, #) CSS format
+ *
+ * @param color - The color to convert, including alpha channel
+ * @param opacity - The opacity of the color, if not included in alpha channel
+ * @returns The converted color
+ **/
+export declare function formatRGBAColor(color: RGBA, opacity?: number): CSSRGBAColor;

package/dist/transformers/text.d.ts

@@ -0,0 +1,30 @@
+import type { Node as FigmaDocumentNode } from "@figma/rest-api-spec";
+export type SimplifiedTextStyle = Partial<{
+    fontFamily: string;
+    fontWeight: number;
+    fontSize: number;
+    lineHeight: string;
+    letterSpacing: string;
+    textCase: string;
+    textAlignHorizontal: string;
+    textAlignVertical: string;
+}>;
+export declare function isTextNode(n: FigmaDocumentNode): n is Extract<FigmaDocumentNode, {
+    type: "TEXT";
+}>;
+export declare function hasTextStyle(n: FigmaDocumentNode): n is FigmaDocumentNode & {
+    style: Extract<FigmaDocumentNode, {
+        style: any;
+    }>["style"];
+};
+export declare function extractNodeText(n: FigmaDocumentNode): string | undefined;
+export declare function extractTextStyle(n: FigmaDocumentNode): Partial<{
+    fontFamily: string;
+    fontWeight: number;
+    fontSize: number;
+    lineHeight: string;
+    letterSpacing: string;
+    textCase: string;
+    textAlignHorizontal: string;
+    textAlignVertical: string;
+}> | undefined;

package/dist/utils/common.d.ts

@@ -0,0 +1,69 @@
+export type StyleId = `${string}_${string}` & {
+    __brand: "StyleId";
+};
+/**
+ * Download Figma image and save it locally
+ * @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
+ * @throws Error if download fails
+ */
+export declare function downloadFigmaImage(fileName: string, localPath: string, imageUrl: string): Promise<string>;
+/**
+ * Remove keys with empty arrays or empty objects from an object.
+ * @param input - The input object or value.
+ * @returns The processed object or the original value.
+ */
+export declare function removeEmptyKeys<T>(input: T): T;
+/**
+ * Generate a 6-character random variable ID
+ * @param prefix - ID prefix
+ * @returns A 6-character random ID string with prefix
+ */
+export declare function generateVarId(prefix?: string): StyleId;
+/**
+ * Generate a CSS shorthand for values that come with top, right, bottom, and left
+ *
+ * input: { top: 10, right: 10, bottom: 10, left: 10 }
+ * output: "10px"
+ *
+ * input: { top: 10, right: 20, bottom: 10, left: 20 }
+ * output: "10px 20px"
+ *
+ * input: { top: 10, right: 20, bottom: 30, left: 40 }
+ * output: "10px 20px 30px 40px"
+ *
+ * @param values - The values to generate the shorthand for
+ * @returns The generated shorthand
+ */
+export declare function generateCSSShorthand(values: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}, { ignoreZero, suffix, }?: {
+    /**
+     * If true and all values are 0, return undefined. Defaults to true.
+     */
+    ignoreZero?: boolean;
+    /**
+     * The suffix to add to the shorthand. Defaults to "px".
+     */
+    suffix?: string;
+}): string | undefined;
+/**
+ * Check if an element is visible
+ * @param element - The item to check
+ * @returns True if the item is visible, false otherwise
+ */
+export declare function isVisible(element: {
+    visible?: boolean;
+}): boolean;
+/**
+ * Rounds a number to two decimal places, suitable for pixel value processing.
+ * @param num The number to be rounded.
+ * @returns The rounded number with two decimal places.
+ * @throws TypeError If the input is not a valid number
+ */
+export declare function pixelRound(num: number): number;

package/dist/utils/fetch-with-retry.d.ts

@@ -0,0 +1,12 @@
+type RequestOptions = RequestInit & {
+    /**
+     * Force format of headers to be a record of strings, e.g. { "Authorization": "Bearer 123" }
+     *
+     * Avoids complexity of needing to deal with `instanceof Headers`, which is not supported in some environments.
+     */
+    headers?: Record<string, string>;
+};
+export declare function fetchWithRetry<T extends {
+    status?: number;
+}>(url: string, options?: RequestOptions): Promise<T>;
+export {};

package/dist/utils/identity.d.ts

@@ -0,0 +1,23 @@
+import type { Rectangle, HasLayoutTrait, StrokeWeights, HasFramePropertiesTrait } from "@figma/rest-api-spec";
+import { isTruthy } from "remeda";
+import type { CSSHexColor, CSSRGBAColor } from "~/transformers/style.js";
+export { isTruthy };
+export declare function hasValue<K extends PropertyKey, T>(key: K, obj: unknown, typeGuard?: (val: unknown) => val is T): obj is Record<K, T>;
+export declare function isFrame(val: unknown): val is HasFramePropertiesTrait;
+export declare function isLayout(val: unknown): val is HasLayoutTrait;
+/**
+ * Checks if:
+ * 1. A node is a child to an auto layout frame
+ * 2. The child adheres to the auto layout rules—i.e. it's not absolutely positioned
+ *
+ * @param node - The node to check.
+ * @param parent - The parent node.
+ * @returns True if the node is a child of an auto layout frame, false otherwise.
+ */
+export declare function isInAutoLayoutFlow(node: unknown, parent: unknown): boolean;
+export declare function isStrokeWeights(val: unknown): val is StrokeWeights;
+export declare function isRectangle<T, K extends string>(key: K, obj: T): obj is T & {
+    [P in K]: Rectangle;
+};
+export declare function isRectangleCornerRadii(val: unknown): val is number[];
+export declare function isCSSColorValue(val: unknown): val is CSSRGBAColor | CSSHexColor;

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

@@ -0,0 +1,57 @@
+import type { Transform } from "@figma/rest-api-spec";
+/**
+ * Apply crop transform to an image based on Figma's transformation matrix
+ * @param imagePath - Path to the original image file
+ * @param cropTransform - Figma transform matrix [[scaleX, skewX, translateX], [skewY, scaleY, translateY]]
+ * @returns Promise<string> - Path to the cropped image
+ */
+export declare function applyCropTransform(imagePath: string, cropTransform: Transform): Promise<string>;
+/**
+ * Get image dimensions from a file
+ * @param imagePath - Path to the image file
+ * @returns Promise<{width: number, height: number}>
+ */
+export declare function getImageDimensions(imagePath: string): Promise<{
+    width: number;
+    height: number;
+}>;
+export type ImageProcessingResult = {
+    filePath: string;
+    originalDimensions: {
+        width: number;
+        height: number;
+    };
+    finalDimensions: {
+        width: number;
+        height: number;
+    };
+    wasCropped: boolean;
+    cropRegion?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    cssVariables?: string;
+    processingLog: string[];
+};
+/**
+ * Enhanced image download with post-processing
+ * @param fileName - The filename to save as
+ * @param localPath - The local path to save to
+ * @param imageUrl - Image URL
+ * @param needsCropping - Whether to apply crop transform
+ * @param cropTransform - Transform matrix for cropping
+ * @param requiresImageDimensions - Whether to generate dimension metadata
+ * @returns Promise<ImageProcessingResult> - Detailed processing information
+ */
+export declare function downloadAndProcessImage(fileName: string, localPath: string, imageUrl: string, needsCropping?: boolean, cropTransform?: Transform, requiresImageDimensions?: boolean): Promise<ImageProcessingResult>;
+/**
+ * Create CSS custom properties for image dimensions
+ * @param imagePath - Path to the image file
+ * @returns Promise<string> - CSS custom properties
+ */
+export declare function generateImageCSSVariables({ width, height, }: {
+    width: number;
+    height: number;
+}): string;

package/dist/utils/logger.d.ts

@@ -0,0 +1,6 @@
+export declare const Logger: {
+    isHTTP: boolean;
+    log: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+};
+export declare function writeLogs(name: string, value: any): void;

package/package.json

@@ -1,16 +1,16 @@
 {
     "name": "figma-metadata-extractor",
-    "version": "1.0.0",
-    "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",
     "types": "dist/index.d.ts",
     "exports": {
         ".": {
+            "types": "./dist/index.d.ts",
             "import": "./dist/index.js",
-            "require": "./dist/index.cjs",
-            "types": "./dist/index.d.ts"
+            "require": "./dist/index.cjs"
         }
     },
     "files": [
@@ -19,7 +19,7 @@
         "example.js"
     ],
     "scripts": {
-        "build": "vite build && tsc --emitDeclarationOnly --outDir dist",
+        "build": "vite build && tsc --project tsconfig.declarations.json",
         "typecheck": "tsc --noEmit",
         "test": "jest",
         "dev": "vite build --watch",