import type { FigmaAssetFormat, FigmaRef } from "./types";
/** Typed capability/transport failures per design spec §4.4. */
export type FigmaClientErrorCode = "NO_TOKEN" | "BAD_TOKEN" | "FORBIDDEN" | "REQUIRES_ENTERPRISE" | "RATE_LIMITED" | "RENDER_FAILED" | "NODE_NOT_FOUND" | "HTTP_ERROR";
export declare class FigmaClientError extends Error {
    readonly code: FigmaClientErrorCode;
    readonly status?: number;
    /** Low-cardinality REST call label (e.g. "images", "files_nodes") for
     *  telemetry attribution — never the raw fileKey/nodeId path. */
    readonly endpoint?: string;
    constructor(code: FigmaClientErrorCode, message: string, status?: number, endpoint?: string);
}
/** Injectable fetch so tests never touch the network. */
export type FigmaFetch = (url: string, init?: {
    headers?: Record<string, string>;
}) => Promise<Response>;
export interface RenderNodeOptions {
    format: FigmaAssetFormat;
    scale?: number;
}
export interface RenderedNode {
    /** short-lived figma CDN url — freeze it immediately */
    url: string;
    ext: FigmaAssetFormat;
}
export interface FigmaVariablePayload {
    name: string;
    key?: string;
    resolvedType?: string;
    valuesByMode?: Record<string, unknown>;
    variableCollectionId?: string;
}
export interface FigmaVariablesResult {
    variables: Record<string, FigmaVariablePayload>;
    variableCollections: Record<string, unknown>;
}
export interface FigmaStyleMeta {
    key: string;
    name: string;
    style_type: string;
    node_id?: string;
    description?: string;
}
/** Raw figma node document from GET /v1/files/:key/nodes. Field-level shape
 *  is consumed by nodeToHtml; kept loose here on purpose — consumers narrow
 *  children/fills/etc themselves. */
export interface FigmaNodeDocument {
    id: string;
    name: string;
    type: string;
    [field: string]: unknown;
}
export interface FigmaFileVersion {
    version: string;
    lastModified: string;
}
/** One batch render result — url is null when figma couldn't render that
 *  node (a bad node id in the batch shouldn't fail the whole call). */
export interface BatchRenderedNode {
    nodeId: string;
    url: string | null;
    ext: FigmaAssetFormat;
}
export interface FigmaClient {
    renderNode(ref: FigmaRef, opts: RenderNodeOptions): Promise<RenderedNode>;
    /** Batch render many nodes of ONE file in a single /v1/images call — the
     *  documented rate-limit workaround (comma-separated ids). Per-node
     *  failures come back as url:null rather than throwing the batch. */
    renderNodes(fileKey: string, nodeIds: string[], opts: RenderNodeOptions): Promise<BatchRenderedNode[]>;
    imageFills(fileKey: string): Promise<Map<string, string>>;
    variables(fileKey: string): Promise<FigmaVariablesResult>;
    styles(fileKey: string): Promise<FigmaStyleMeta[]>;
    nodeTree(ref: FigmaRef): Promise<FigmaNodeDocument>;
    fileVersion(fileKey: string): Promise<FigmaFileVersion>;
}
export interface FigmaClientOptions {
    token: string;
    fetch?: FigmaFetch;
    baseUrl?: string;
    /** Injectable delay for 429 backoff — tests pass a no-op so retries don't
     *  actually wait. Defaults to a real timer. */
    sleep?: (ms: number) => Promise<void>;
    /** Max 429 retries before giving up. Default 3. */
    maxRetries?: number;
}
export declare function createFigmaClient(options: FigmaClientOptions): FigmaClient;
//# sourceMappingURL=client.d.ts.map