/**
 * Client for the Dynamic Framework component catalog and Storybook index.
 *
 * Two upstream sources, two base URLs:
 *
 *   - Catalog (component props): served from the dedicated CDN under
 *     `cdn.dynamicframework.dev/assets/<version>/ui-react/api.json`. The
 *     exact URL is resolved through `manifest.json` discovery — the manifest
 *     enumerates the published versions and their per-flavor artifact URLs.
 *     This replaced the legacy `react.dynamicframework.dev/latest/props.json`
 *     when Dynamic UI 2.5.x bumped to Storybook 10 and stopped publishing
 *     props.json (regression documented in AUDIT-MCP-2.5.1-2026-05-22.md).
 *
 *   - Index (story IDs for `widgets-list-patterns`): unaffected by the
 *     Storybook 10 upgrade; still served from
 *     `react.dynamicframework.dev/latest/index.json`.
 *
 * Wraps {@link FetchClient} to inherit retry-with-backoff (429/503/504),
 * timeout, Retry-After honoring, and debug logging with auth-header redact.
 * Adds two in-memory TTL caches: 1h for the catalog/index artifacts (which
 * are immutable per version on the CDN side), 5min for the manifest itself
 * (which matches the CDN's `max-age`).
 *
 * URL override for local dev (only the Storybook index — the catalog
 * version is pinned by the MCP, never by the operator):
 *   DYNAMIC_UI_STORYBOOK_URL=http://localhost:8080
 */
export interface ComponentPropEntry {
    type: string;
    required: boolean;
    defaultValue: string | null;
    description: string;
}
export interface ComponentDoc {
    description: string;
    sourcePath?: string;
    props: Record<string, ComponentPropEntry>;
}
export type PropsMap = Record<string, ComponentDoc>;
/**
 * Shape of the per-version entry in `manifest.json`. Each version exposes
 * an artifact URL per UI flavor — today only `ui-react`, but the manifest
 * is structured to admit more flavors (Vue, web components, etc.) without
 * breaking the contract.
 */
export interface ManifestVersionEntry {
    "ui-react": string;
    publishedAt: string;
    deprecated: boolean;
}
export interface ManifestPayload {
    updatedAt: string;
    latest: string;
    versions: Record<string, ManifestVersionEntry>;
}
/**
 * Top-level shape of `api.json` published under the Dynamic Framework CDN.
 *
 * `hooks` and `contexts` are intentionally typed `unknown` — no tool consumes
 * them today, and tightening them prematurely would force changes to drift
 * with the upstream contract. When a future tool reads them, type them in
 * the same commit that introduces the consumer.
 */
export interface ApiJsonPayload {
    $schema?: string;
    schemaVersion: string;
    packageVersion: string;
    repository: string | null;
    generatedAt: string;
    components: Record<string, ComponentDoc>;
    hooks: Record<string, unknown>;
    contexts: Record<string, unknown>;
}
export interface IndexEntry {
    id: string;
    title: string;
    name: string;
    type: "story" | "docs";
}
export type IndexMap = {
    entries?: Record<string, IndexEntry>;
} & Record<string, IndexEntry>;
export declare class StorybookClient {
    private catalogBaseUrl;
    private indexBaseUrl;
    private catalogFetchClient;
    private indexFetchClient;
    private propsCache;
    private indexCache;
    private manifestCache;
    constructor();
    /**
     * Returns the relative path of the Storybook stories index. Used by
     * `widgets-list-patterns` to filter entries with `title` starting in
     * `Patterns/`. The index is the native Storybook artifact and was not
     * affected by the Storybook 10 upgrade.
     */
    private getIndexPath;
    getIndexUrl(): string;
    /**
     * Fetches `manifest.json` from the catalog CDN with a 5-minute in-memory
     * TTL cache (mirroring the CDN's `max-age`). The manifest is the source
     * of truth for which versioned `api.json` URLs are published; the MCP
     * picks which version to consume via {@link resolveVersion}.
     */
    getManifest(): Promise<ManifestPayload>;
    /**
     * Returns the Dynamic UI version that this MCP release is pinned against
     * by the compatibility matrix (see `src/tools/widgets/_compatibility.ts`).
     *
     * The `manifest` parameter is intentionally unused today — it is kept on
     * the signature so future evolutions (e.g. cross-validating the pinned
     * version against manifest state without re-fetching) don't have to
     * thread the manifest through again. The cross-validation that does use
     * the manifest happens in {@link getCatalogUrl}.
     */
    private resolveVersion;
    /**
     * Resolves the absolute URL of the versioned `api.json` for the version
     * pinned by the compatibility matrix. Two failure modes are mapped to
     * actionable errors:
     *
     *   - Pinned version is missing from manifest.versions: upstream
     *     removed/never-published the version, or the pin in
     *     `_compatibility.ts` points at an unpublished version.
     *   - Pinned version is marked `deprecated: true` in the manifest:
     *     bump the pin to a supported version.
     */
    getCatalogUrl(): Promise<string>;
    private isCacheValid;
    getProps(): Promise<PropsMap>;
    getIndex(): Promise<IndexMap>;
    /**
     * Normalizes the two `index.json` shapes Storybook ships:
     *   - Storybook 9: flat object `{ "<id>": IndexEntry, ... }`
     *   - Storybook 10: wrapped `{ entries: { "<id>": IndexEntry, ... }, v: 5 }`
     *
     * Filters out entries that don't carry `id` and `title`, which protects
     * against the wrapper keys (e.g. `v`) leaking when the flat fallback hits.
     */
    getIndexEntries(index: IndexMap): IndexEntry[];
}
export declare const storybookClient: StorybookClient;
//# sourceMappingURL=storybookClient.d.ts.map