@visual-layer/figma-rest 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,67 @@
+export interface FigmaBbox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FigmaNode {
+    id: string;
+    name: string;
+    type: string;
+    visible?: boolean;
+    absoluteBoundingBox?: FigmaBbox;
+    absoluteRenderBounds?: FigmaBbox;
+    characters?: string;
+    children?: FigmaNode[];
+    componentPropertyDefinitions?: Record<string, unknown>;
+    /** Passthrough for any other Figma fields. */
+    [k: string]: unknown;
+}
+export interface FigmaNodeResult {
+    document: FigmaNode;
+    version: string;
+}
+export interface FigmaClient {
+    getFileNodes(fileKey: string, nodeIds: readonly string[]): Promise<FigmaNodeResult>;
+    getNodeImage(fileKey: string, nodeIds: readonly string[], opts?: {
+        format?: 'png' | 'jpg';
+        scale?: number;
+    }): Promise<Record<string, string | null>>;
+}
+export declare class FigmaClientError extends Error {
+    readonly retryAfterMs?: number | undefined;
+    readonly code: string;
+    constructor(code: string, message: string, retryAfterMs?: number | undefined);
+}
+export interface HttpFigmaOptions {
+    token?: string;
+    fetch?: typeof fetch;
+    maxRetries?: number;
+    baseUrl?: string;
+}
+export declare class HttpFigmaClient implements FigmaClient {
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly baseUrl;
+    constructor(opts?: HttpFigmaOptions);
+    getFileNodes(fileKey: string, nodeIds: readonly string[]): Promise<FigmaNodeResult>;
+    getNodeImage(fileKey: string, nodeIds: readonly string[], opts?: {
+        format?: 'png' | 'jpg';
+        scale?: number;
+    }): Promise<Record<string, string | null>>;
+    private requestJson;
+}
+export interface MockEntry {
+    document: FigmaNode;
+    version: string;
+    images?: Record<string, string | null>;
+}
+export declare class MockFigmaClient implements FigmaClient {
+    private files;
+    constructor(files: Record<string, MockEntry>);
+    getFileNodes(fileKey: string, nodeIds: readonly string[]): Promise<FigmaNodeResult>;
+    getNodeImage(fileKey: string, nodeIds: readonly string[]): Promise<Record<string, string | null>>;
+}
+export declare function findNode(root: FigmaNode, id: string): FigmaNode | null;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -0,0 +1,136 @@
+/**
+ * Figma REST client. HttpFigmaClient talks to api.figma.com; MockFigmaClient
+ * serves fixture JSON with no network. Both implement FigmaClient so capture
+ * logic is identical against real or mocked data.
+ *
+ * Failure modes (§18.7):
+ *  - missing_token: no FIGMA_TOKEN configured
+ *  - auth_failed: 401/403
+ *  - rate_limited: 429 (honors Retry-After up to the retry cap)
+ */
+import { ErrorCodes } from '@visual-layer/core';
+export class FigmaClientError extends Error {
+    retryAfterMs;
+    code;
+    constructor(code, message, retryAfterMs) {
+        super(`${code}: ${message}`);
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'FigmaClientError';
+        this.code = code;
+    }
+}
+const API = 'https://api.figma.com';
+export class HttpFigmaClient {
+    token;
+    fetchImpl;
+    maxRetries;
+    baseUrl;
+    constructor(opts = {}) {
+        this.token = opts.token ?? process.env['FIGMA_TOKEN'];
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.maxRetries = opts.maxRetries ?? 3;
+        this.baseUrl = opts.baseUrl ?? API;
+    }
+    async getFileNodes(fileKey, nodeIds) {
+        // Figma /nodes expects comma-separated ids; encode each id individually and join with a
+        // literal comma so the separator survives URL encoding (encodeURIComponent would turn it into %2C).
+        const ids = nodeIds.map((id) => encodeURIComponent(id)).join(',');
+        const url = `${this.baseUrl}/v1/files/${encodeURIComponent(fileKey)}/nodes?ids=${ids}`;
+        const body = await this.requestJson(url);
+        const entry = body?.nodes?.[nodeIds[0]];
+        if (!entry)
+            throw new FigmaClientError(ErrorCodes.node_not_found, `node ${nodeIds[0]} not found in file ${fileKey}`);
+        return { document: entry.document, version: String(body?.version ?? '') };
+    }
+    async getNodeImage(fileKey, nodeIds, opts = {}) {
+        const ids = nodeIds.map((id) => encodeURIComponent(id)).join(',');
+        const params = new URLSearchParams();
+        params.set('ids', ids);
+        if (opts.format)
+            params.set('format', opts.format);
+        if (opts.scale)
+            params.set('scale', String(opts.scale));
+        const url = `${this.baseUrl}/v1/images/${encodeURIComponent(fileKey)}?${params.toString()}`;
+        const body = await this.requestJson(url);
+        return (body?.images ?? {});
+    }
+    async requestJson(url) {
+        if (!this.token) {
+            throw new FigmaClientError(ErrorCodes.missing_token, 'FIGMA_TOKEN not set');
+        }
+        let lastErr;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const res = await this.fetchImpl(url, { headers: { 'X-Figma-Token': this.token } });
+            if (res.status === 401 || res.status === 403) {
+                throw new FigmaClientError(ErrorCodes.auth_failed, `figma auth failed (${res.status})`);
+            }
+            if (res.status === 429) {
+                const retryAfter = parseRetryAfter(res.headers.get('retry-after'));
+                if (attempt < this.maxRetries) {
+                    await sleep(retryAfter);
+                    continue;
+                }
+                throw new FigmaClientError(ErrorCodes.rate_limited, 'figma rate limit exceeded', retryAfter);
+            }
+            if (!res.ok) {
+                lastErr = new FigmaClientError('figma_http_error', `figma ${res.status}`);
+                if (attempt < this.maxRetries && res.status >= 500) {
+                    await sleep(backoffMs(attempt));
+                    continue;
+                }
+                throw lastErr;
+            }
+            return await res.json();
+        }
+        throw lastErr ?? new FigmaClientError('figma_http_error', 'figma request failed');
+    }
+}
+export class MockFigmaClient {
+    files;
+    constructor(files) {
+        this.files = files;
+    }
+    async getFileNodes(fileKey, nodeIds) {
+        const entry = this.files[fileKey];
+        if (!entry)
+            throw new FigmaClientError(ErrorCodes.node_not_found, `file ${fileKey} not in mock`);
+        const id = nodeIds[0];
+        if (id !== entry.document.id && !findNode(entry.document, id)) {
+            throw new FigmaClientError(ErrorCodes.node_not_found, `node ${id} not in mock file ${fileKey}`);
+        }
+        return { document: entry.document, version: entry.version };
+    }
+    async getNodeImage(fileKey, nodeIds) {
+        const entry = this.files[fileKey];
+        const images = entry?.images ?? {};
+        const out = {};
+        for (const id of nodeIds)
+            out[id] = images[id] ?? null;
+        return out;
+    }
+}
+export function findNode(root, id) {
+    if (root.id === id)
+        return root;
+    for (const c of root.children ?? []) {
+        const hit = findNode(c, id);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+function parseRetryAfter(h) {
+    if (!h)
+        return backoffMs(0);
+    const secs = Number(h);
+    if (Number.isFinite(secs))
+        return Math.min(secs * 1000, 10_000);
+    return backoffMs(0);
+}
+function backoffMs(attempt) {
+    return Math.min(1000 * 2 ** attempt, 8000);
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @visual-layer/figma-rest public surface.
+ */
+export * from './client.js';
+export * from './normalize.js';
+export declare const FIGMA_REST_VERSION = "0.1.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAE/B,eAAO,MAAM,kBAAkB,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * @visual-layer/figma-rest public surface.
+ */
+export * from './client.js';
+export * from './normalize.js';
+export const FIGMA_REST_VERSION = '0.1.0';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAE/B,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC"}

package/dist/normalize.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Normalize a Figma node tree into a ScreenGraph (source: "figma").
+ * Structure-first: derive interactables from FRAME / COMPONENT / INSTANCE / TEXT
+ * nodes, not from rendered pixels.
+ */
+import { type ScreenGraph, type Warning } from '@visual-layer/core';
+import type { FigmaClient } from './client.js';
+export interface CaptureFigmaOptions {
+    fileKey: string;
+    nodeId: string;
+    /** Fetch a rendered image and attach as a screenshot artifact reference. */
+    includeImage?: boolean;
+    /** Optional explicit graph id. */
+    id?: string;
+    /** Override the viewport (Figma frames have their own size). */
+    viewport?: ScreenGraph['viewport'];
+}
+export interface CaptureFigmaResult {
+    graph: ScreenGraph;
+    /** Rendered image URL per node id, when includeImage was set. */
+    imageUrls?: Record<string, string | null>;
+    warnings: Warning[];
+}
+export declare function captureFigma(client: FigmaClient, opts: CaptureFigmaOptions): Promise<CaptureFigmaResult>;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,OAAO,EAQb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kCAAkC;IAClC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,QAAQ,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,WAAW,CAAC;IACnB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1C,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAID,wBAAsB,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAkF9G"}

package/dist/normalize.js

@@ -0,0 +1,103 @@
+/**
+ * Normalize a Figma node tree into a ScreenGraph (source: "figma").
+ * Structure-first: derive interactables from FRAME / COMPONENT / INSTANCE / TEXT
+ * nodes, not from rendered pixels.
+ */
+import { SCHEMA_VERSION, deterministicId, warn, info, } from '@visual-layer/core';
+const INTERACTIVE_TYPES = new Set(['COMPONENT', 'INSTANCE', 'FRAME', 'TEXT', 'RECTANGLE']);
+export async function captureFigma(client, opts) {
+    const { document, version } = await client.getFileNodes(opts.fileKey, [opts.nodeId]);
+    const warnings = [];
+    const interactables = [];
+    const seenLabels = new Map();
+    const flat = [];
+    flatten(document, flat);
+    for (const node of flat) {
+        const type = node.type.toUpperCase();
+        if (!INTERACTIVE_TYPES.has(type))
+            continue;
+        if (node.visible === false) {
+            warnings.push(info('hidden_figma_node', `node "${node.name}" (${node.id}) invisible`, undefined));
+            continue;
+        }
+        const bb = node.absoluteBoundingBox;
+        if (!bb) {
+            warnings.push(warn('figma_node_missing_bbox', `node "${node.name}" has no bbox`, undefined));
+            continue;
+        }
+        const bbox = [bb.x, bb.y, bb.width, bb.height];
+        const role = inferRole(node);
+        const label = (node.characters ?? node.name ?? '').toString();
+        const sources = ['figma'];
+        const inter = {
+            id: deterministicId('i', `figma:${node.id}`),
+            role,
+            name: node.name,
+            text: node.characters,
+            bbox,
+            coordinateSpace: 'figma',
+            source: sources,
+            confidence: 0.85,
+            figmaNodeId: node.id,
+        };
+        interactables.push(inter);
+        if (label)
+            seenLabels.set(label, (seenLabels.get(label) ?? 0) + 1);
+    }
+    for (const [label, count] of seenLabels) {
+        if (count > 1)
+            warnings.push(warn('duplicate_label', `"${label}" appears ${count}x`, undefined));
+    }
+    let imageUrls;
+    let screenshot;
+    if (opts.includeImage) {
+        imageUrls = await client.getNodeImage(opts.fileKey, [opts.nodeId]).catch(() => ({ [opts.nodeId]: null }));
+        const url = imageUrls[opts.nodeId];
+        if (!url) {
+            warnings.push(warn('image_render_null', `image render for ${opts.nodeId} returned null`, undefined));
+        }
+        else {
+            // URL recorded; bytes are fetched separately at the artifact-store layer.
+            // ponytail: MVP stores URL ref, not bytes — fetching/validating PNG bytes is post-MVP.
+            screenshot = {
+                artifactId: deterministicId('img', url),
+                sha256: '0'.repeat(64), // placeholder; real hash computed when bytes are materialized
+                width: 0,
+                height: 0,
+                mimeType: 'image/png',
+            };
+        }
+    }
+    const graph = {
+        id: opts.id ?? deterministicId('sg', `figma:${opts.fileKey}:${opts.nodeId}:${version}`),
+        version: SCHEMA_VERSION,
+        source: 'figma',
+        createdAt: new Date().toISOString(),
+        ...(opts.viewport ? { viewport: opts.viewport } : {}),
+        ...(screenshot ? { screenshot } : {}),
+        interactables,
+        mappings: [],
+        figmaNodes: flat,
+        warnings,
+        provenance: [
+            { field: 'interactables', source: 'figma', confidence: 0.85, note: `fileKey=${opts.fileKey} node=${opts.nodeId} v=${version}` },
+        ],
+    };
+    return { graph, imageUrls, warnings };
+}
+function flatten(node, out) {
+    out.push(node);
+    for (const c of node.children ?? [])
+        flatten(c, out);
+}
+function inferRole(node) {
+    const t = node.type.toUpperCase();
+    if (t === 'COMPONENT' || t === 'INSTANCE')
+        return 'button';
+    if (t === 'TEXT')
+        return 'text';
+    if (t === 'FRAME')
+        return 'group';
+    return 'figure';
+}
+//# sourceMappingURL=normalize.js.map

package/dist/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@visual-layer/figma-rest",
+  "version": "1.0.0",
+  "description": "Figma REST capture with mockable client, rate-limit, retry",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/locotine/vision-layer.git",
+    "directory": "packages/figma-rest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^3.23.8",
+    "@visual-layer/core": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b"
+  }
+}