@sun-asterisk/sungen 2.4.6 → 2.5.1

package/dist/tools/figma/figma-errors.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Typed error classes for Figma API failures.
+ * Each error carries an actionable remediation message for CLI output.
+ *
+ * Never include PAT values in error messages or remediation text.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FigmaNetworkError = exports.FigmaRateLimitError = exports.FigmaAccessError = exports.FigmaAuthError = void 0;
+// ---------------------------------------------------------------------------
+// Base
+// ---------------------------------------------------------------------------
+/** Common base for all Figma errors. */
+class FigmaBaseError extends Error {
+    constructor(message, remediation) {
+        super(message);
+        this.name = this.constructor.name;
+        this.remediation = remediation;
+    }
+}
+// ---------------------------------------------------------------------------
+// Concrete error types
+// ---------------------------------------------------------------------------
+/**
+ * HTTP 401 — PAT is missing, expired, or invalid.
+ */
+class FigmaAuthError extends FigmaBaseError {
+    constructor(message = 'Figma authentication failed (401).') {
+        super(message, 'Your Figma PAT is invalid or expired. Re-authenticate by running: sungen figma auth set');
+    }
+}
+exports.FigmaAuthError = FigmaAuthError;
+/**
+ * HTTP 403 / 404 — PAT valid but insufficient access, or resource not found.
+ */
+class FigmaAccessError extends FigmaBaseError {
+    constructor(statusCode, message) {
+        const defaultMsg = statusCode === 403
+            ? 'Figma access denied (403).'
+            : 'Figma resource not found (404).';
+        const remediation = statusCode === 403
+            ? 'Request view access to the Figma file, or ensure your PAT has the file:read scope.'
+            : 'Check the Figma URL — the file key or node ID may be incorrect.';
+        super(message ?? defaultMsg, remediation);
+        this.statusCode = statusCode;
+    }
+}
+exports.FigmaAccessError = FigmaAccessError;
+/**
+ * HTTP 429 — Rate limited by Figma API.
+ */
+class FigmaRateLimitError extends FigmaBaseError {
+    constructor(retryAfter, message, opts = {}) {
+        const human = formatRetryAfter(retryAfter);
+        const tierSuffix = opts.planTier ? ` (plan: ${opts.planTier}${opts.bucket ? `, bucket: ${opts.bucket}` : ''})` : '';
+        const msg = message ?? `Figma API rate limit hit (429)${tierSuffix}. Retry after ${human}.`;
+        // Multi-day Retry-After → almost certainly the Starter-tier daily quota.
+        const multiDay = retryAfter > 24 * 60 * 60;
+        const remediation = multiDay
+            ? [
+                `This is a Figma ${opts.planTier ?? 'Starter'}-tier daily/multi-day REST quota (not a transient burst).`,
+                'To continue today you must either:',
+                '  1) Re-run with a cached version: sungen add --screen <name> --figma <url>  (no --refresh)',
+                '     → reuses .sungen/figma-cache raw JSON; skips the /nodes API call entirely.',
+                opts.upgradeLink ? `  2) Upgrade the Figma account: ${opts.upgradeLink}` : '  2) Upgrade the Figma account to a paid tier.',
+                '  3) Wait for the quota window to reset.',
+            ].join('\n')
+            : 'Wait and retry, or reduce request frequency. In the meantime you can re-run without --refresh to reuse cached node JSON.';
+        super(msg, remediation);
+        this.retryAfter = retryAfter;
+        this.planTier = opts.planTier;
+        this.bucket = opts.bucket;
+        this.upgradeLink = opts.upgradeLink;
+    }
+}
+exports.FigmaRateLimitError = FigmaRateLimitError;
+/** Turn `369943` → `4d 6h 45m`. */
+function formatRetryAfter(secs) {
+    if (!Number.isFinite(secs) || secs <= 0)
+        return `${secs}s`;
+    const d = Math.floor(secs / 86400);
+    const h = Math.floor((secs % 86400) / 3600);
+    const m = Math.floor((secs % 3600) / 60);
+    const parts = [];
+    if (d)
+        parts.push(`${d}d`);
+    if (h)
+        parts.push(`${h}h`);
+    if (m && !d)
+        parts.push(`${m}m`);
+    if (!parts.length)
+        parts.push(`${secs}s`);
+    return `${parts.join(' ')} (${secs}s)`;
+}
+/**
+ * Network / transport failure (timeout, DNS, stream error, etc.).
+ */
+class FigmaNetworkError extends FigmaBaseError {
+    constructor(message, cause) {
+        super(message, 'Check your internet connection and verify api.figma.com is reachable. If the issue persists, retry.');
+        this.cause = cause;
+    }
+}
+exports.FigmaNetworkError = FigmaNetworkError;
+//# sourceMappingURL=figma-errors.js.map

package/dist/tools/figma/figma-errors.js.map

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

package/dist/tools/figma/figma-image-downloader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Download a Figma-signed image URL to disk.
+ *
+ * - Streams response body to a .tmp file then atomically renames to destPath.
+ * - Verifies the final file is non-zero bytes before committing.
+ * - Enforces a configurable timeout (default 30 s).
+ * - Surfaces all failures as FigmaNetworkError.
+ *
+ * Security: signed S3 URLs are consumed transiently — never logged.
+ */
+export interface DownloadOptions {
+    /** Request timeout in milliseconds. Default: 30 000. */
+    timeoutMs?: number;
+}
+/**
+ * Download the image at `url` and write it to `destPath`.
+ *
+ * Uses atomic write: streams to `<destPath>.tmp`, verifies size > 0,
+ * then renames to `destPath`. Cleans up .tmp on failure.
+ *
+ * @throws FigmaNetworkError on any network, timeout, or I/O failure.
+ * @throws FigmaNetworkError when the downloaded file has zero bytes.
+ */
+export declare function downloadToPath(url: string, destPath: string, options?: DownloadOptions): Promise<void>;
+//# sourceMappingURL=figma-image-downloader.d.ts.map

package/dist/tools/figma/figma-image-downloader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-image-downloader.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-image-downloader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAgEf"}

package/dist/tools/figma/figma-image-downloader.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Download a Figma-signed image URL to disk.
+ *
+ * - Streams response body to a .tmp file then atomically renames to destPath.
+ * - Verifies the final file is non-zero bytes before committing.
+ * - Enforces a configurable timeout (default 30 s).
+ * - Surfaces all failures as FigmaNetworkError.
+ *
+ * Security: signed S3 URLs are consumed transiently — never logged.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadToPath = downloadToPath;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const promises_1 = require("node:stream/promises");
+const node_stream_1 = require("node:stream");
+const figma_errors_1 = require("./figma-errors");
+/**
+ * Download the image at `url` and write it to `destPath`.
+ *
+ * Uses atomic write: streams to `<destPath>.tmp`, verifies size > 0,
+ * then renames to `destPath`. Cleans up .tmp on failure.
+ *
+ * @throws FigmaNetworkError on any network, timeout, or I/O failure.
+ * @throws FigmaNetworkError when the downloaded file has zero bytes.
+ */
+async function downloadToPath(url, destPath, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 30000;
+    const tmpPath = `${destPath}.tmp`;
+    // Ensure destination directory exists
+    const dir = path.dirname(destPath);
+    fs.mkdirSync(dir, { recursive: true });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetch(url, { signal: controller.signal });
+    }
+    catch (cause) {
+        clearTimeout(timer);
+        cleanupTmp(tmpPath);
+        const isTimeout = cause instanceof Error && cause.name === 'AbortError';
+        throw new figma_errors_1.FigmaNetworkError(isTimeout
+            ? `Image download timed out after ${timeoutMs}ms.`
+            : 'Image download failed due to a network error.', cause);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        cleanupTmp(tmpPath);
+        throw new figma_errors_1.FigmaNetworkError(`Image download received HTTP ${response.status}.`);
+    }
+    if (!response.body) {
+        cleanupTmp(tmpPath);
+        throw new figma_errors_1.FigmaNetworkError('Image download response has no body.');
+    }
+    // Stream to .tmp file
+    const writeStream = fs.createWriteStream(tmpPath);
+    try {
+        await (0, promises_1.pipeline)(node_stream_1.Readable.fromWeb(response.body), writeStream);
+    }
+    catch (cause) {
+        cleanupTmp(tmpPath);
+        throw new figma_errors_1.FigmaNetworkError('Failed to write image to disk.', cause);
+    }
+    // Verify non-zero file size
+    const stat = fs.statSync(tmpPath);
+    if (stat.size === 0) {
+        cleanupTmp(tmpPath);
+        throw new figma_errors_1.FigmaNetworkError('Downloaded image file is empty (0 bytes).');
+    }
+    // Atomic rename
+    try {
+        fs.renameSync(tmpPath, destPath);
+    }
+    catch (cause) {
+        cleanupTmp(tmpPath);
+        throw new figma_errors_1.FigmaNetworkError('Failed to finalize image file on disk.', cause);
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function cleanupTmp(tmpPath) {
+    try {
+        if (fs.existsSync(tmpPath))
+            fs.unlinkSync(tmpPath);
+    }
+    catch {
+        // Best-effort cleanup — ignore errors
+    }
+}
+//# sourceMappingURL=figma-image-downloader.js.map

package/dist/tools/figma/figma-image-downloader.js.map

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

package/dist/tools/figma/figma-node-filter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Prune raw Figma node trees to a minimal shape for LLM / test-generation use.
+ *
+ * Drops: vectors, fills, effects, strokes, constraints, style references.
+ * Keeps: id, name, type, text content, component/variant metadata, bounding box, children.
+ *
+ * Role inference: component name suffix → button | textbox | link | image | null.
+ */
+import type { FilteredFigmaNode, FigmaTextLabel, FigmaVariantDefinition } from './figma-client-types';
+/**
+ * Validate and filter a raw Figma node tree.
+ *
+ * @throws ZodError when the input fails basic structural validation.
+ */
+export declare function filterFigmaNode(rawNode: unknown): FilteredFigmaNode;
+/**
+ * Recursively collect all text labels from a filtered node tree.
+ * Returns a flat list of { text, nodePath } pairs.
+ */
+export declare function extractTextLabels(node: FilteredFigmaNode, _path?: string): FigmaTextLabel[];
+/**
+ * Extract variant definitions from a COMPONENT_SET node.
+ * Each direct child COMPONENT represents one variant combination.
+ */
+export declare function extractVariants(componentSetNode: FilteredFigmaNode): FigmaVariantDefinition[];
+//# sourceMappingURL=figma-node-filter.d.ts.map

package/dist/tools/figma/figma-node-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-node-filter.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-node-filter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,iBAAiB,EAEjB,cAAc,EACd,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAgI9B;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,CASnE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,iBAAiB,EACvB,KAAK,SAAK,GACT,cAAc,EAAE,CAalB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,gBAAgB,EAAE,iBAAiB,GAClC,sBAAsB,EAAE,CAU1B"}

package/dist/tools/figma/figma-node-filter.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Prune raw Figma node trees to a minimal shape for LLM / test-generation use.
+ *
+ * Drops: vectors, fills, effects, strokes, constraints, style references.
+ * Keeps: id, name, type, text content, component/variant metadata, bounding box, children.
+ *
+ * Role inference: component name suffix → button | textbox | link | image | null.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterFigmaNode = filterFigmaNode;
+exports.extractTextLabels = extractTextLabels;
+exports.extractVariants = extractVariants;
+const zod_1 = require("zod");
+// ---------------------------------------------------------------------------
+// Zod schema — loose, unknown fields allowed via passthrough
+// ---------------------------------------------------------------------------
+// Zod v4: z.record() requires explicit key schema (z.string())
+const RawNodeSchema = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    name: zod_1.z.string(),
+    type: zod_1.z.string(),
+    characters: zod_1.z.string().optional(),
+    componentPropertyDefinitions: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    componentProperties: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.object({ value: zod_1.z.string(), type: zod_1.z.string() }))
+        .optional(),
+    absoluteBoundingBox: zod_1.z
+        .object({ x: zod_1.z.number(), y: zod_1.z.number(), width: zod_1.z.number(), height: zod_1.z.number() })
+        .optional(),
+    children: zod_1.z.array(zod_1.z.lazy(() => RawNodeSchema)).optional(),
+})
+    .passthrough();
+// ---------------------------------------------------------------------------
+// Role inference
+// ---------------------------------------------------------------------------
+const ROLE_SUFFIX_MAP = [
+    [/button$/i, 'button'],
+    [/input|textbox|text.?field|text.?input/i, 'textbox'],
+    [/link$/i, 'link'],
+    [/icon|image|img|illustration/i, 'image'],
+];
+function inferRole(name) {
+    for (const [pattern, role] of ROLE_SUFFIX_MAP) {
+        if (pattern.test(name))
+            return role;
+    }
+    return null;
+}
+// Node types to skip entirely (leaf-only visual noise)
+const SKIP_TYPES = new Set([
+    'VECTOR',
+    'STAR',
+    'POLYGON',
+    'BOOLEAN_OPERATION',
+    'ELLIPSE',
+    'LINE',
+]);
+// ---------------------------------------------------------------------------
+// Core filter
+// ---------------------------------------------------------------------------
+/**
+ * Recursively prune a raw Figma node to the minimal FilteredFigmaNode shape.
+ * Returns null when the node type should be dropped entirely.
+ *
+ * @param raw     Validated (but loosely typed) raw Figma node object.
+ * @param maxDepth  Maximum recursion depth (default 30 — safety guard).
+ */
+function filterNode(raw, depth = 0, maxDepth = 30) {
+    const id = raw['id'];
+    const name = raw['name'];
+    const type = raw['type'];
+    if (SKIP_TYPES.has(type))
+        return null;
+    if (depth > maxDepth)
+        return null;
+    // Bounding box
+    let boundingBox;
+    const bb = raw['absoluteBoundingBox'];
+    if (bb) {
+        boundingBox = { x: bb.x, y: bb.y, w: bb.width, h: bb.height };
+    }
+    // Text content
+    const text = type === 'TEXT' ? raw['characters'] : undefined;
+    // Component / variant metadata
+    let componentName;
+    let variantProps;
+    if (type === 'COMPONENT' || type === 'COMPONENT_SET' || type === 'INSTANCE') {
+        componentName = name;
+        const props = raw['componentProperties'];
+        if (props) {
+            variantProps = Object.fromEntries(Object.entries(props).map(([k, v]) => [k, v.value]));
+        }
+    }
+    // Role (only meaningful for component-like nodes)
+    const role = componentName != null ? inferRole(name) : null;
+    // Recurse into children
+    const rawChildren = raw['children'] ?? [];
+    const children = rawChildren
+        .map((child) => filterNode(child, depth + 1, maxDepth))
+        .filter((n) => n !== null);
+    const node = { id, name, type, children };
+    if (text !== undefined)
+        node.text = text;
+    if (componentName !== undefined)
+        node.componentName = componentName;
+    if (variantProps !== undefined)
+        node.variantProps = variantProps;
+    if (role)
+        node.role = role;
+    if (boundingBox !== undefined)
+        node.boundingBox = boundingBox;
+    return node;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Validate and filter a raw Figma node tree.
+ *
+ * @throws ZodError when the input fails basic structural validation.
+ */
+function filterFigmaNode(rawNode) {
+    const validated = RawNodeSchema.parse(rawNode);
+    const result = filterNode(validated);
+    // Root node should never be null (root type is never in SKIP_TYPES)
+    if (!result) {
+        const id = rawNode['id'] ?? 'unknown';
+        throw new Error(`Root node (id=${id}) was filtered out — unexpected type.`);
+    }
+    return result;
+}
+/**
+ * Recursively collect all text labels from a filtered node tree.
+ * Returns a flat list of { text, nodePath } pairs.
+ */
+function extractTextLabels(node, _path = '') {
+    const currentPath = _path ? `${_path} > ${node.name}` : node.name;
+    const labels = [];
+    if (node.text) {
+        labels.push({ text: node.text, nodePath: currentPath });
+    }
+    for (const child of node.children) {
+        labels.push(...extractTextLabels(child, currentPath));
+    }
+    return labels;
+}
+/**
+ * Extract variant definitions from a COMPONENT_SET node.
+ * Each direct child COMPONENT represents one variant combination.
+ */
+function extractVariants(componentSetNode) {
+    if (componentSetNode.type !== 'COMPONENT_SET')
+        return [];
+    return componentSetNode.children
+        .filter((child) => child.type === 'COMPONENT')
+        .map((child) => ({
+        nodeId: child.id,
+        name: child.name,
+        variantProps: child.variantProps ?? {},
+    }));
+}
+//# sourceMappingURL=figma-node-filter.js.map

package/dist/tools/figma/figma-node-filter.js.map

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

package/dist/tools/figma/figma-rest-client.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimal Figma REST client.
+ *
+ * - Base URL: https://api.figma.com
+ * - Auth header: X-Figma-Token (PAT — never logged)
+ * - Retry: 429 → honor Retry-After (cap 3 attempts); 5xx → retry once
+ * - All HTTP errors mapped to typed FigmaError subclasses
+ */
+import type { FigmaMeResponse, FigmaFileNodesResponse, FigmaImageUrlsResponse, FigmaImageOptions } from './figma-client-types';
+/**
+ * GET /v1/me — validate PAT and return user info.
+ */
+export declare function getMe(pat: string): Promise<FigmaMeResponse>;
+/**
+ * GET /v1/files/:key/nodes?ids=<id,id,...>
+ * Returns the raw node document and current file version.
+ */
+export declare function getFileNodes(pat: string, fileKey: string, nodeIds: string[]): Promise<FigmaFileNodesResponse>;
+/**
+ * GET /v1/images/:key?ids=<id,id>&scale=<n>&format=<fmt>
+ * Returns signed S3 URLs — consume immediately, do not persist.
+ */
+export declare function getImageUrls(pat: string, fileKey: string, nodeIds: string[], options?: FigmaImageOptions): Promise<FigmaImageUrlsResponse>;
+//# sourceMappingURL=figma-rest-client.d.ts.map

package/dist/tools/figma/figma-rest-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-rest-client.d.ts","sourceRoot":"","sources":["../../../src/tools/figma/figma-rest-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAkH9B;;GAEG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAIjE;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,sBAAsB,CAAC,CAQjC;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,sBAAsB,CAAC,CAYjC"}

package/dist/tools/figma/figma-rest-client.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Minimal Figma REST client.
+ *
+ * - Base URL: https://api.figma.com
+ * - Auth header: X-Figma-Token (PAT — never logged)
+ * - Retry: 429 → honor Retry-After (cap 3 attempts); 5xx → retry once
+ * - All HTTP errors mapped to typed FigmaError subclasses
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMe = getMe;
+exports.getFileNodes = getFileNodes;
+exports.getImageUrls = getImageUrls;
+const figma_errors_1 = require("./figma-errors");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const BASE_URL = 'https://api.figma.com';
+/**
+ * Per-request timeout (ms). Figma can stall on very large nodes; without this,
+ * node fetch hangs the CLI indefinitely. Override via SUNGEN_FIGMA_TIMEOUT_MS.
+ */
+const DEFAULT_REQUEST_TIMEOUT_MS = 90000;
+function getRequestTimeoutMs() {
+    const raw = process.env.SUNGEN_FIGMA_TIMEOUT_MS;
+    const n = raw ? parseInt(raw, 10) : NaN;
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_REQUEST_TIMEOUT_MS;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Build headers with PAT — never expose PAT in logs/errors. */
+function makeHeaders(pat) {
+    return { 'X-Figma-Token': pat };
+}
+/** Parse Retry-After header into seconds (default 60 when missing/invalid). */
+function parseRetryAfter(headers) {
+    const value = headers.get('Retry-After');
+    if (!value)
+        return 60;
+    const parsed = parseInt(value, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 60;
+}
+/** Sleep for `ms` milliseconds. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Map a non-2xx HTTP status to a typed error.
+ * `url` is included only in a generic way — never includes PAT.
+ */
+function mapHttpError(status, url) {
+    const safeUrl = url.replace(/\?.*$/, ''); // strip query params (may contain ids)
+    if (status === 401)
+        throw new figma_errors_1.FigmaAuthError();
+    if (status === 403)
+        throw new figma_errors_1.FigmaAccessError(403);
+    if (status === 404)
+        throw new figma_errors_1.FigmaAccessError(404);
+    throw new figma_errors_1.FigmaNetworkError(`Figma API error ${status} at ${safeUrl}`);
+}
+/**
+ * Core fetch wrapper with retry logic.
+ *
+ * Retry rules:
+ *   - 429: up to MAX_RATE_LIMIT_RETRIES attempts, sleeping Retry-After seconds between each.
+ *   - 5xx: retry once after 2 s.
+ *   - Other errors: throw immediately.
+ */
+async function figmaFetch(pat, url) {
+    let serverErrorRetried = false;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        let response;
+        const timeoutMs = getRequestTimeoutMs();
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            response = await fetch(url, { headers: makeHeaders(pat), signal: controller.signal });
+        }
+        catch (cause) {
+            const aborted = cause?.name === 'AbortError';
+            if (aborted) {
+                throw new figma_errors_1.FigmaNetworkError(`Figma API request timed out after ${Math.round(timeoutMs / 1000)}s. ` +
+                    'The node may be very large. Retry with --refresh, pick a smaller frame, ' +
+                    'or raise SUNGEN_FIGMA_TIMEOUT_MS.', cause);
+            }
+            throw new figma_errors_1.FigmaNetworkError('Network request to Figma API failed.', cause);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (response.ok)
+            return response;
+        // 429: fail fast. Figma rate-limit windows are per-minute, so in-CLI
+        // retries typically waste time. Surface the Retry-After hint and let
+        // the caller re-run after waiting.
+        if (response.status === 429) {
+            const retryAfter = parseRetryAfter(response.headers);
+            const planTier = response.headers.get('x-figma-plan-tier') ?? undefined;
+            const bucket = response.headers.get('x-figma-rate-limit-type') ?? undefined;
+            const upgradeLink = response.headers.get('x-figma-upgrade-link') ?? undefined;
+            throw new figma_errors_1.FigmaRateLimitError(retryAfter, undefined, { planTier, bucket, upgradeLink });
+        }
+        if (response.status >= 500 && !serverErrorRetried) {
+            serverErrorRetried = true;
+            await sleep(2000);
+            continue;
+        }
+        // For all other non-2xx, delegate to mapHttpError (throws)
+        mapHttpError(response.status, url);
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * GET /v1/me — validate PAT and return user info.
+ */
+async function getMe(pat) {
+    const url = `${BASE_URL}/v1/me`;
+    const response = await figmaFetch(pat, url);
+    return response.json();
+}
+/**
+ * GET /v1/files/:key/nodes?ids=<id,id,...>
+ * Returns the raw node document and current file version.
+ */
+async function getFileNodes(pat, fileKey, nodeIds) {
+    if (nodeIds.length === 0) {
+        throw new Error('getFileNodes: nodeIds must be a non-empty array.');
+    }
+    const ids = nodeIds.join(',');
+    const url = `${BASE_URL}/v1/files/${encodeURIComponent(fileKey)}/nodes?ids=${encodeURIComponent(ids)}`;
+    const response = await figmaFetch(pat, url);
+    return response.json();
+}
+/**
+ * GET /v1/images/:key?ids=<id,id>&scale=<n>&format=<fmt>
+ * Returns signed S3 URLs — consume immediately, do not persist.
+ */
+async function getImageUrls(pat, fileKey, nodeIds, options = {}) {
+    if (nodeIds.length === 0) {
+        throw new Error('getImageUrls: nodeIds must be a non-empty array.');
+    }
+    const scale = options.scale ?? 2;
+    const format = options.format ?? 'png';
+    const ids = nodeIds.join(',');
+    const url = `${BASE_URL}/v1/images/${encodeURIComponent(fileKey)}` +
+        `?ids=${encodeURIComponent(ids)}&scale=${scale}&format=${format}`;
+    const response = await figmaFetch(pat, url);
+    return response.json();
+}
+//# sourceMappingURL=figma-rest-client.js.map