/**
 * Figma REST Client — Pulls design system data using the Figma REST API.
 *
 * This module is the headless alternative to FigmaBridge (ws-server.ts). Use it
 * when Figma Desktop is not running — CI pipelines, headless machines, or any
 * environment where the plugin cannot connect over WebSocket. The only
 * prerequisites are a personal access token (FIGMA_TOKEN) and a file key
 * (FIGMA_FILE_KEY); no plugin, no local server, no open browser tab.
 *
 * The returned DesignSystem shape is identical to what FigmaBridge.extractDesignSystem()
 * returns, so all downstream consumers — registry, auto-spec, code-gen — are
 * agnostic to which transport was used.
 *
 * Error taxonomy:
 *   FigmaConfigError — permanent failures that require user action (bad token,
 *     wrong file key). Never retry automatically; surface immediately.
 *   FigmaPlanError (extends FigmaConfigError) — the token is valid but the
 *     endpoint is gated behind a paid Figma plan. Absorbed gracefully so a
 *     partial design system is still returned.
 *   Error — transient network failures. Absorbed per-endpoint so the pull
 *     continues with the data that did arrive.
 */
import type { DesignSystem } from "../engine/registry.js";
/**
 * Thrown when the request cannot succeed without user intervention — invalid or
 * expired token, wrong file key, or insufficient file permissions. Callers must
 * surface this error rather than retrying; the root cause is always a
 * misconfiguration, not a transient failure.
 */
export declare class FigmaConfigError extends Error {
    readonly status?: number;
    constructor(msg: string, status?: number);
}
/**
 * Thrown when a 403 is received on a plan-gated endpoint such as
 * `/files/{key}/variables/local`. The Figma variables API requires a
 * Professional plan or higher; Free and Starter plans return 403 even for
 * files the token can otherwise access.
 *
 * Unlike a generic FigmaConfigError, FigmaPlanError is absorbed by
 * extractDesignSystemREST — the pull continues without tokens and logs a
 * warning instead of failing.
 */
export declare class FigmaPlanError extends FigmaConfigError {
    constructor(endpoint: string);
}
export interface FigmaUserInfo {
    id: string;
    email: string;
    handle: string;
    img_url?: string;
}
/**
 * Verify a Figma personal access token by calling `GET /v1/me`.
 *
 * Use this immediately after the user pastes a token — catching the error here
 * gives a clear "token is wrong" message rather than a cryptic failure buried
 * inside a design system pull.
 *
 * @param token  Figma personal access token to validate
 * @returns      Basic user info (id, email, handle) confirming the token is valid
 * @throws {FigmaConfigError} status 401 — token is invalid or expired
 */
export declare function validateFigmaToken(token: string): Promise<FigmaUserInfo>;
export interface FigmaFileInfo {
    name: string;
    /**
     * Number of published components in the file. Used as a proxy for file
     * health — a count of zero is valid (new files) but useful for surfacing
     * "did you mean a different file key?" warnings in the CLI.
     */
    componentCount: number;
}
/**
 * Confirm a file key is accessible by fetching its published component list.
 *
 * A successful response means the token can read the file. The component count
 * is returned as a lightweight health indicator — the caller can warn the user
 * when zero components are found without treating it as a hard error.
 *
 * FigmaPlanError is absorbed here: an inaccessible variables endpoint still
 * proves the file exists and the token is valid.
 *
 * @param fileKey  Figma file key (the alphanumeric segment of the file URL)
 * @param token    Figma personal access token
 * @returns        File name (falls back to fileKey) and published component count
 * @throws {FigmaConfigError} status 404 — file key is wrong or file is deleted
 * @throws {FigmaConfigError} status 403 — token lacks access to this file
 */
export declare function validateFigmaFile(fileKey: string, token: string): Promise<FigmaFileInfo>;
/**
 * Pull a complete design system from Figma using only the REST API.
 *
 * Fires three requests in parallel — variables (tokens), components, and styles —
 * and merges the results into the same {@link DesignSystem} shape that
 * `FigmaBridge.extractDesignSystem()` returns. All downstream code (registry,
 * auto-spec, code-gen, token-differ) works without knowing which transport was
 * used.
 *
 * **Partial-failure semantics:**
 * Each endpoint is wrapped in its own catch handler. A {@link FigmaPlanError} on
 * the variables endpoint (Free plan restriction) is absorbed silently — the pull
 * continues without tokens. A {@link FigmaConfigError} on any endpoint (bad token,
 * missing file key) is re-thrown immediately because the user must fix the
 * configuration before any data can be retrieved. Generic network errors are
 * absorbed per-endpoint so a flaky connection on one call doesn't discard the
 * data that the other two calls already returned.
 *
 * @param token    Figma personal access token with read access to the file
 * @param fileKey  Figma file key from the file's URL
 * @returns        DesignSystem containing tokens, components, and styles
 * @throws {FigmaConfigError} when the token is invalid or the file is inaccessible
 */
export declare function extractDesignSystemREST(fileKey: string, token: string): Promise<DesignSystem>;