redoc 2.5.4 → 3.0.0-rc.1

package/typings/index.d.ts

@@ -1,8 +1,9 @@
-export * from './components';
-export { MiddlePanel, Row, RightPanel, Section, Dropdown, SimpleDropdown, } from './common-elements/';
-export type { DropdownOption } from './common-elements';
-export type { OpenAPIEncoding } from './types';
-export * from './services';
-export * from './utils';
-export * from './styled-components';
-export { default as styled } from './styled-components';
+export { RedocStandalone, prepareApiDocs } from './RedocStandalone.js';
+export type { RedocStandaloneProps } from './RedocStandalone.js';
+export { RedoclyApiDocsStandalone } from './RedoclyApiDocsStandalone.js';
+export type { RedoclyApiDocsStandaloneProps } from './RedoclyApiDocsStandalone.js';
+export { convertSwagger2OpenAPI } from './adapters/utils/convertSwagger2OpenAPI.js';
+export { logoFromSpec } from './utils/x-logo.js';
+export { ServerStyleSheet } from 'styled-components';
+export { RedoclyApiDocs as Redoc } from './RedoclyApiDocs.js';
+export type { RedoclyApiDocsProps as RedocProps } from './RedoclyApiDocs.js';

package/typings/jotai/app.d.ts

@@ -0,0 +1,75 @@
+import { LayoutVariant } from '@redocly/config';
+import type { AsyncLocalStorage } from 'node:async_hooks';
+declare global {
+    var redoclyCookieStorage: AsyncLocalStorage<string> | undefined;
+}
+export type TabType<T extends object = object> = {
+    title: string;
+    key: string;
+} & T;
+export type AppSessionStore = {
+    collapsedSidebar: boolean;
+    unsupportedFeatureScreen: boolean;
+};
+export type AppStore = {
+    activeMimeName: string;
+    layout: LayoutVariant;
+    colorMode: string;
+    language: string;
+    environment: string;
+    environments: Record<string, Record<string, string>>;
+    allowedEnvironments: string[] | null;
+};
+type LanguageAtom = {
+    languages?: (TabType & {
+        order?: number;
+        lang: string;
+    })[];
+    activeLanguage: string;
+};
+/** Raw `light` | `dark`; localStorage so it survives on `file://`, where cookies are dropped. */
+export declare const COLOR_MODE_STORAGE_KEY = "redoc.colorMode";
+export declare const appStore: import("jotai").WritableAtom<AppStore, [typeof import("jotai/utils").RESET | AppStore | ((prev: AppStore) => typeof import("jotai/utils").RESET | AppStore)], void>;
+export declare const environmentsAtom: import("jotai").Atom<import("../utils/environments.js").EnvironmentData>;
+export declare const environmentAtom: import("jotai").WritableAtom<[Record<string, string>, string], [{
+    environment?: string;
+    environments?: Record<string, Record<string, string>>;
+}], void>;
+export declare const savedEnvironmentNameAtom: import("jotai").Atom<string>;
+export declare const activeMimeNameAtom: import("jotai").WritableAtom<string, [string], void>;
+export declare const mediaTypeOverrideAtom: import("jotai").PrimitiveAtom<string | undefined> & {
+    init: string | undefined;
+};
+export declare const activeMediaTypeAtom: import("jotai").WritableAtom<string | undefined, [string | undefined], void>;
+export declare const layoutAtom: import("jotai").WritableAtom<LayoutVariant, LayoutVariant[], void>;
+export declare const allowedEnvironmentsAtom: import("jotai").WritableAtom<string[] | null, [string[] | null], void>;
+/**
+ * appSessionStore saved to session storage
+ */
+export declare const appSessionStore: import("jotai").WritableAtom<AppSessionStore, [typeof import("jotai/utils").RESET | AppSessionStore | ((prev: AppSessionStore) => typeof import("jotai/utils").RESET | AppSessionStore)], void>;
+/** Mobile sidebar drawer — open state is per-view, never persisted. */
+export declare const isSidebarOpenedAtom: import("jotai").PrimitiveAtom<boolean> & {
+    init: boolean;
+};
+export declare const colorModeAtom: import("jotai").WritableAtom<string, string[], void>;
+export declare const collapsedSidebarAtom: import("jotai").WritableAtom<boolean, boolean[], void>;
+export declare const languageAtom: import("jotai").WritableAtom<LanguageAtom, [string], void>;
+export declare const requestValuesAtom: import("jotai").PrimitiveAtom<Record<string, Record<string, unknown>>> & {
+    init: Record<string, Record<string, unknown>>;
+};
+/**
+ * The `data-section-id` of whatever section is currently nearest the top of
+ * the viewport (computed by `useScrollSpyUrlSync` via `useActiveSectionId`).
+ * Used only for the standalone API docs with sidebar.
+ */
+export declare const activeScrollSectionAtom: import("jotai").PrimitiveAtom<string | null> & {
+    init: string | null;
+};
+/**
+ * Lowercased pathnames visited this session. Written only by the root-mounted
+ * `useVisitedChannelsTracker` so per-item panels don't subscribe to the router.
+ */
+export declare const visitedChannelsAtom: import("jotai").PrimitiveAtom<string[]> & {
+    init: string[];
+};
+export {};

package/typings/jotai/examples.d.ts

@@ -0,0 +1,5 @@
+import type { ExampleEntry } from '../types/store.js';
+export declare const exampleStoreAtom: import("jotai").Atom<Record<string, ExampleEntry>>;
+export declare const itemSpecForSamplerAtom: import("jotai-family").AtomFamily<string, import("jotai").Atom<Record<string, unknown>>>;
+export declare function buildExampleAtomKey(schemaId: string, context?: 'request' | 'response', mediaType?: string, itemId?: string): string;
+export declare const generatedExampleAtom: import("jotai-family").AtomFamily<string, import("jotai").Atom<unknown>>;

package/typings/jotai/graphql.d.ts

@@ -0,0 +1,10 @@
+import type { GraphqlDirectiveData, GraphqlStoreFieldData, GraphqlTypeData, GraphqlTypeReference } from '../types/graphql-store.js';
+import type { GraphqlTypeLookup } from '../utils/graphql-samples.js';
+export declare const graphqlTypeLookupAtom: import("jotai").Atom<GraphqlTypeLookup>;
+export declare const graphqlTypeDataAtom: import("jotai-family").AtomFamily<string, import("jotai").Atom<GraphqlTypeData | undefined>>;
+export declare const graphqlDirectiveDataAtom: import("jotai-family").AtomFamily<string, import("jotai").Atom<GraphqlDirectiveData | undefined>>;
+export type GraphqlOperationType = 'query' | 'mutation' | 'subscription';
+export declare function graphqlOperationKey(operationType: GraphqlOperationType | undefined, operationName: string | undefined): string;
+export declare const graphqlOperationAtom: import("jotai-family").AtomFamily<string, import("jotai").Atom<GraphqlStoreFieldData | undefined>>;
+export declare const graphqlTypeSlugMapAtom: import("jotai").Atom<Record<string, string>>;
+export declare const graphqlReferenceMapAtom: import("jotai").Atom<Record<string, GraphqlTypeReference[]>>;

package/typings/jotai/itemStore.d.ts

@@ -0,0 +1,51 @@
+import type { Atom } from 'jotai';
+export type ItemStore = {
+    activeDiscriminator: Record<string, number>;
+    activeOneOf: Record<string, number>;
+    activeResponseCode: string;
+    activeExampleKey: string;
+    activeMessageKey: string;
+    selectedCallback: string;
+    expandableSections: Record<string, boolean | undefined>;
+    collapsibles: Record<string, boolean>;
+};
+export type ItemStoreKey = keyof ItemStore;
+export type ItemStoreFieldParams<K extends ItemStoreKey = ItemStoreKey> = {
+    itemId: string;
+    key: K;
+};
+type ItemStoreUpdate = Partial<ItemStore> | ((current: ItemStore) => Partial<ItemStore>);
+export declare const itemStoreAtom: import("jotai-family").AtomFamily<string, import("jotai").WritableAtom<ItemStore, [update: ItemStoreUpdate], void>>;
+export declare function itemStoreFieldAtom<K extends ItemStoreKey>(params: ItemStoreFieldParams<K>): Atom<ItemStore[K]>;
+export declare function buildVariantStateKey(parentPath: ReadonlyArray<string> | undefined, localPart: string): string;
+export type DeepLinkSectionData = {
+    /** Route-level item id (slug) */
+    id: string;
+    /** "request" | "response" for OpenAPI body/param sections */
+    t?: string;
+    /** "query" | "header" | "path" | "cookie" for OpenAPI parameter location */
+    in?: string;
+    /** Response status code */
+    c?: string;
+    /** Callback id */
+    cb?: string;
+    /** Content-type name (when multiple media types) */
+    ct?: string;
+    /** When true, nested field deep-links use `path=<field>` only */
+    pathOnly?: boolean;
+    /** AsyncAPI message key */
+    messageKey?: string;
+    /** AsyncAPI sub-section: "headers" | "payload" | "send" | "receive" | "parameters" | "messages" */
+    asyncSection?: string;
+    /** GraphQL type section: "field" | "argument" | "return-type" | "possible-types" | "implements" | "enum-value" */
+    graphqlType?: string;
+    /** GraphQL parent type name (e.g. "Query", "User") */
+    graphqlTypeName?: string;
+};
+export declare function activeDiscriminatorSelectAtom(itemId: string): Atom<ItemStore['activeDiscriminator']>;
+export declare function activeOneOfSelectAtom(itemId: string): Atom<ItemStore['activeOneOf']>;
+export declare function expandableSectionAtom(itemId: string, key: string): Atom<boolean | undefined>;
+export declare function buildCollapsibleEntryKey(sectionKey: string, instanceId: string): string;
+export declare function collapsibleEntrySection(entryKey: string): string;
+export declare function expandableSectionKeysAtom(itemId: string): Atom<string[]>;
+export {};

package/typings/jotai/routes.d.ts

@@ -0,0 +1,4 @@
+import type { RouteIndex } from '../utils/routing.js';
+export declare const routeIndexAtom: import("jotai").PrimitiveAtom<RouteIndex | null> & {
+    init: RouteIndex | null;
+};

package/typings/jotai/schema.d.ts

@@ -0,0 +1,3 @@
+import type { SchemaEntry } from '../types/store.js';
+export declare const schemaStoreAtom: import("jotai").Atom<Record<string, SchemaEntry>>;
+export declare const schemaEntryAtom: import("jotai-family").AtomFamily<string, import("jotai").Atom<SchemaEntry | undefined>>;

package/typings/jotai/store.d.ts

@@ -0,0 +1,22 @@
+import type { ApiItem, ApiStore } from '../types/store.js';
+import type { ApiSpecType } from '../types/common.js';
+import type { ApiDocsOptions } from '../types/options.js';
+export type GlobalStoreAtom = {
+    items: ApiItem[];
+    store: ApiStore;
+    options: ApiDocsOptions;
+    definition?: Record<string, unknown> | string;
+    definitionUrl?: string;
+};
+export declare const globalStoreAtom: import("jotai").PrimitiveAtom<GlobalStoreAtom> & {
+    init: GlobalStoreAtom;
+};
+export declare const globalItemsAtom: import("jotai").Atom<ApiItem[]>;
+/** Maps a component-schema name to the route slug of its schema-definition page (if it has one). */
+export declare const schemaDefinitionSlugMapAtom: import("jotai").Atom<Record<string, string>>;
+export declare const globalOptionsAtom: import("jotai").Atom<ApiDocsOptions>;
+export declare const specTypeAtom: import("jotai").Atom<ApiSpecType>;
+export declare const routingBasePathAtom: import("jotai").Atom<string>;
+export declare const storeAtom: import("jotai").Atom<ApiStore>;
+export declare const definitionAtom: import("jotai").Atom<string | Record<string, unknown> | undefined>;
+export declare const definitionUrlAtom: import("jotai").Atom<string | undefined>;

package/typings/jotai/telemetry.d.ts

@@ -0,0 +1,46 @@
+import type { EventType } from '@redocly/redoc-opentelemetry';
+export type NavigationCause = 'sidebar' | 'search' | 'referencedIn' | 'history';
+export type TelemetrySession = {
+    firstInteractionMs?: number;
+    sections: ReadonlySet<string>;
+    sidebarClicks: number;
+    schemaExpands: number;
+    maxSchemaDepth: number;
+    searches: number;
+    interactions: number;
+    hiddenCount: number;
+    hiddenMs: number;
+    hiddenSince?: number;
+    schemaExpandEvents: number;
+    cappedEvents: boolean;
+};
+/** Per-load cap on `schemaField.expanded` events sent over the network; counters stay complete. */
+export declare const SCHEMA_EXPAND_EVENT_CAP = 50;
+export declare const telemetrySessionAtom: import("jotai").PrimitiveAtom<TelemetrySession> & {
+    init: TelemetrySession;
+};
+/** Counts one UI event; returns `false` when the event is over the per-load cap and must not be sent. */
+export declare const recordTelemetryEventAtom: import("jotai").WritableAtom<null, [{
+    event: EventType;
+    data: unknown[];
+}], boolean> & {
+    init: null;
+};
+export declare const recordSectionViewedAtom: import("jotai").WritableAtom<null, [sectionId: string], void> & {
+    init: null;
+};
+export declare const recordVisibilityAtom: import("jotai").WritableAtom<null, [hidden: boolean], void> & {
+    init: null;
+};
+export declare const navigationCauseAtom: import("jotai").PrimitiveAtom<{
+    via: NavigationCause;
+    at: number;
+} | null> & {
+    init: {
+        via: NavigationCause;
+        at: number;
+    } | null;
+};
+export declare const markNavigationCauseAtom: import("jotai").WritableAtom<null, [via: NavigationCause], void> & {
+    init: null;
+};

package/typings/options/constants.d.ts

@@ -0,0 +1,10 @@
+import { LayoutVariant } from '@redocly/config';
+export declare const DEFAULT_LAYOUT = LayoutVariant.THREE_PANEL;
+export declare const DEFAULT_MAX_DISPLAYED_ENUM_VALUES = 10;
+export declare const DEFAULT_ROUTING_BASE_PATH = "";
+export declare const GRAPHQL_DEFAULT_JSON_SAMPLES_DEPTH = 1;
+export declare const ASYNCAPI_DEFAULT_JSON_SAMPLES_DEPTH = 3;
+export declare const GRAPHQL_DEFAULT_SAMPLES_MAX_INLINE_ARGS = 2;
+export declare const GRAPHQL_DEFAULT_FIELD_EXPAND_LEVEL = 4;
+export declare const JSON_SAMPLES_EXPAND_LEVEL_DEFAULT = 2;
+export declare const GENERATED_SAMPLES_MAX_DEPTH_DEFAULT = 8;

package/typings/options/editionOverrides.d.ts

@@ -0,0 +1,3 @@
+import type { RawApiDocsOptions } from '../types/options.js';
+/** Option overrides applied on top of host options in `normalizeOptions`. The community edition forces enterprise options off here. */
+export declare const EDITION_OPTION_OVERRIDES: Partial<RawApiDocsOptions>;

package/typings/options/helpers.d.ts

@@ -0,0 +1,25 @@
+import { LayoutVariant, type RedocConfig } from '@redocly/config';
+import type { ApiSpecType } from '../types/common.js';
+import type { RawApiDocsOptions } from '../types/options.js';
+import type { CodeSamplesConfig } from '../types/code-samples-config.js';
+export declare function argValueToBoolean(val?: string | boolean, defaultValue?: boolean): boolean;
+export declare function argValueToNumber(value: number | string | undefined, defaultValue?: number): number;
+export declare function argValueToInt(value: number | string | undefined, defaultValue?: number): number;
+export declare function argValueToExpandLevel(value?: number | string | undefined, defaultValue?: number): number | undefined;
+export declare function normalizePath(path: string): string;
+export declare function normalizeShowExtensions(value: RedocConfig['showExtensions']): string[] | boolean;
+/**
+ * Normalize scrollYOffset for OpenAPI options. Safe for SSR: no DOM (querySelector).
+ * In browser, openapi-docs version also supports CSS selector strings.
+ */
+export declare function normalizeScrollYOffset(value: RedocConfig['scrollYOffset']): () => number;
+export declare function normalizeCodeSamples(value?: RedocConfig['codeSamples']): CodeSamplesConfig;
+export declare function normalizeIgnoreNamedSchemas(value: RawApiDocsOptions['ignoreNamedSchemas']): string[];
+export declare function normalizeDownloadUrls(downloadUrls: {
+    title?: string;
+    url: string;
+}[], type: ApiSpecType): {
+    title: string;
+    url: string;
+}[];
+export declare function normalizeLayout(layout: RawApiDocsOptions['layout']): LayoutVariant;

package/typings/options/normalizeOptions.d.ts

@@ -0,0 +1,2 @@
+import type { ApiDocsOptions, RawApiDocsOptions } from '../types/options.js';
+export declare function normalizeOptions(rawOptions: RawApiDocsOptions): ApiDocsOptions;

package/typings/options/standaloneLayoutVars.d.ts

@@ -0,0 +1,3 @@
+import type { CSSProperties } from 'react';
+import type { ApiDocsOptions } from '../types/options.js';
+export declare function getStandaloneLayoutStyle({ scrollYOffset }: ApiDocsOptions): CSSProperties;

package/typings/otel-semantic-conventions.d.ts

@@ -0,0 +1,10 @@
+export declare const ATTR_EXCEPTION_MESSAGE = "exception.message";
+export declare const ATTR_EXCEPTION_STACKTRACE = "exception.stacktrace";
+export declare const ATTR_EXCEPTION_TYPE = "exception.type";
+export declare const ATTR_SERVICE_NAME = "service.name";
+export declare const ATTR_SERVICE_VERSION = "service.version";
+export declare const ATTR_TELEMETRY_SDK_LANGUAGE = "telemetry.sdk.language";
+export declare const ATTR_TELEMETRY_SDK_NAME = "telemetry.sdk.name";
+export declare const ATTR_TELEMETRY_SDK_VERSION = "telemetry.sdk.version";
+export declare const TELEMETRY_SDK_LANGUAGE_VALUE_NODEJS = "nodejs";
+export declare const TELEMETRY_SDK_LANGUAGE_VALUE_WEBJS = "webjs";

package/typings/pages/EntryPage.d.ts

@@ -0,0 +1,25 @@
+import type { ReactElement } from 'react';
+import type { RouteIndex } from '../utils/routing.js';
+type EntryPageProps = {
+    routeIndex: RouteIndex;
+    basePath: string;
+};
+/**
+ * Renders the whole API as one persistent tree with two layers of laziness:
+ *
+ *   1. **Top-level LazySections** — one per top-level entry (root page,
+ *      every top-level tag, any standalone non-tag route). Each
+ *      observer-mounts when scrolled near the viewport and stays mounted.
+ *
+ *   2. **Ops inside a tag** — when the tag is in scope (active route OR an
+ *      ancestor of the active route), every op renders as a nested
+ *      LazySection. The active op is eager; the rest are placeholders that
+ *      observer-mount on scroll. When the tag goes out of scope, its ops
+ *      unmount; the active op of the new tag becomes eager.
+ *
+ * Section pointer routes (`route.content === null`) live inside the root
+ * page's overview body — when one is active, the root page is eager.
+ */
+declare function EntryPageComponent({ routeIndex, basePath }: EntryPageProps): ReactElement;
+export declare const EntryPage: import("react").MemoExoticComponent<typeof EntryPageComponent>;
+export {};

package/typings/pages/GroupPage.d.ts

@@ -0,0 +1 @@
+export declare const GroupPage: import("react").FC<any>;

package/typings/pages/ItemPage.d.ts

@@ -0,0 +1 @@
+export declare const ItemPage: import("react").FC<any>;

package/typings/pages/NotFoundPage.d.ts

@@ -0,0 +1,6 @@
+import type { ReactElement } from 'react';
+type NotFoundPageProps = {
+    routingBasePath: string;
+};
+export declare function NotFoundPage({ routingBasePath }: NotFoundPageProps): ReactElement;
+export {};

package/typings/pages/OverviewPage.d.ts

@@ -0,0 +1 @@
+export declare const OverviewPage: import("react").FC<any>;

package/typings/pages/TopLevelEntryView.d.ts

@@ -0,0 +1,17 @@
+import type { ReactElement } from 'react';
+import type { TopLevelEntry } from '../utils/routing.js';
+type TopLevelEntryViewProps = {
+    entry: TopLevelEntry;
+    activePath: string | undefined;
+    entryEager: boolean;
+    eagerOpSlug: string | null;
+    shouldRenderOps: boolean;
+    opsStartIndex?: number;
+    renderEntrySection?: boolean;
+};
+/** Renders one top-level entry as a LazySection plus, when in scope, its op
+ *  LazySections. The op LazySections are siblings (not children) of the
+ *  entry's LazySection so the entry's memo bail doesn't keep a stale `eager`
+ *  prop on the active op during sibling-op navigation. */
+export declare const TopLevelEntryView: import("react").MemoExoticComponent<({ entry, activePath, entryEager, eagerOpSlug, shouldRenderOps, opsStartIndex, renderEntrySection, }: TopLevelEntryViewProps) => ReactElement>;
+export {};

package/typings/services/agent-tools/index.d.ts

@@ -0,0 +1,11 @@
+import type { AgentTool, ApiDocsAgentToolsParams } from './types.js';
+export { collectOperations } from './operations.js';
+export { MAX_AGENT_RESULT_CHARS, agentErrorResult, agentJsonResult, agentTextResult, } from './results.js';
+export { registerAgentTools } from './webmcp.js';
+export { createSpecSliceOperationDetail } from './spec-slice-detail.js';
+export type { AgentTool, AgentToolAnnotations, AgentToolOutcome, AgentToolResult, AgentToolsTelemetry, ApiDocsAgentToolsParams, ApiOperationSummary, } from './types.js';
+/**
+ * Tools describing the API rendered on the current page. A host supplies how its URLs are shaped
+ * and where operation detail comes from; everything else is read from the item tree and store.
+ */
+export declare function buildApiDocsAgentTools({ items, store, resolveDocUrl, getOperationDetail }: ApiDocsAgentToolsParams): AgentTool[];

package/typings/services/agent-tools/operations.d.ts

@@ -0,0 +1,20 @@
+import type { ApiItem } from '../../types/store.js';
+import type { ApiOperationSummary } from './types.js';
+/**
+ * Request path of an OpenAPI operation, from its pointer: `/paths/~1museum-hours/get` is
+ * `GET /museum-hours`. AsyncAPI channel pointers hold an identifier rather than an address,
+ * so they are left without a path.
+ */
+export declare function pathFromPointer(pointer: string | undefined): string | undefined;
+/**
+ * Flattens the navigation tree into the operations it documents: HTTP operations, webhooks,
+ * AsyncAPI channel operations, `x-mcp` entities, and GraphQL queries, mutations and subscriptions.
+ */
+export declare function collectOperations(items: ApiItem[], resolveDocUrl?: (link: string) => string): ApiOperationSummary[];
+/** Matches on a documentation URL when given one, otherwise on method and path or title. */
+export declare function findOperation(operations: ApiOperationSummary[], criteria: {
+    url?: string;
+    method?: string;
+    path?: string;
+}): ApiOperationSummary | undefined;
+export declare function filterOperations(operations: ApiOperationSummary[], query: string): ApiOperationSummary[];

package/typings/services/agent-tools/results.d.ts

@@ -0,0 +1,6 @@
+import type { AgentToolResult } from './types.js';
+/** Longest text one tool result may carry. */
+export declare const MAX_AGENT_RESULT_CHARS = 24000;
+export declare function agentTextResult(text: string): AgentToolResult;
+export declare function agentJsonResult(value: unknown): AgentToolResult;
+export declare function agentErrorResult(message: string): AgentToolResult;

package/typings/services/agent-tools/security.d.ts

@@ -0,0 +1,13 @@
+import type { ApiStore } from '../../types/store.js';
+type ApiSecuritySummary = {
+    servers: Array<{
+        url: string;
+        description?: string;
+    }>;
+    securitySchemes: Array<Record<string, unknown> & {
+        id: string;
+    }>;
+};
+/** Servers and security schemes of the documented API, with every stored credential removed. */
+export declare function summarizeSecurity(store: ApiStore): ApiSecuritySummary;
+export {};

package/typings/services/agent-tools/spec-slice-detail.d.ts

@@ -0,0 +1,12 @@
+import type { ApiSpecType } from '../../types/common.js';
+import type { ApiItem } from '../../types/store.js';
+import type { ApiOperationSummary } from './types.js';
+type SpecSliceDetailParams = {
+    items: ApiItem[];
+    specType: ApiSpecType;
+    /** The bundled definition, or GraphQL SDL. */
+    definition: Record<string, unknown> | string;
+};
+/** Operation detail for hosts that hold the definition: the slice the page actions copy. */
+export declare function createSpecSliceOperationDetail({ items, specType, definition }: SpecSliceDetailParams): (operation: ApiOperationSummary) => Promise<string | undefined>;
+export {};

package/typings/services/agent-tools/types.d.ts

@@ -0,0 +1,54 @@
+import type { ApiItem, ApiStore } from '../../types/store.js';
+/** One operation of the documented API, flattened out of the navigation tree. */
+export type ApiOperationSummary = {
+    /** Upper-case HTTP method, or the entity kind for items such as `x-mcp` tools. */
+    method: string;
+    title: string;
+    /** Documentation URL, already in the host's URL space. */
+    url: string;
+    path?: string;
+    /** Tag or group the operation is listed under. */
+    section?: string;
+    deprecated?: boolean;
+};
+export type AgentToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+};
+/** Hints an agent uses to decide whether a tool is safe to call unattended. */
+export type AgentToolAnnotations = {
+    readOnlyHint?: boolean;
+    untrustedContentHint?: boolean;
+    /** The tool changes something outside the page, so an agent should confirm before calling it. */
+    consequentialHint?: boolean;
+};
+/** A tool an agent can read and call, in the shape both WebMCP and MCP accept. */
+export type AgentTool = {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    annotations?: AgentToolAnnotations;
+    execute: (input: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }) => Promise<AgentToolResult>;
+};
+export type ApiDocsAgentToolsParams = {
+    items: ApiItem[];
+    store: ApiStore;
+    /** Rewrites an item link into the host's URL space; identity when omitted. */
+    resolveDocUrl?: (link: string) => string;
+    /** Full reference text for one operation; without it `get_api_operation` returns the summary. */
+    getOperationDetail?: (operation: ApiOperationSummary, options?: {
+        signal?: AbortSignal;
+    }) => Promise<string | undefined>;
+};
+export type AgentToolOutcome = 'answered' | 'rejected' | 'failed';
+/** How a host records use of the tools. */
+export type AgentToolsTelemetry = {
+    registered: (toolCount: number) => void;
+    called: (toolName: string, outcome: AgentToolOutcome) => void;
+};

package/typings/services/agent-tools/webmcp.d.ts

@@ -0,0 +1,14 @@
+import type { AgentTool, AgentToolsTelemetry } from './types.js';
+type ModelContextLike = {
+    registerTool: (tool: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }) => Promise<void> | void;
+};
+/** The browser's WebMCP entry point: `document.modelContext`, then `navigator.modelContext`. */
+export declare function getModelContext(): ModelContextLike | undefined;
+/**
+ * Registers every tool with the browser; aborting the shared signal unregisters them all.
+ * Returns the names that registered; none when the browser has no WebMCP.
+ */
+export declare function registerAgentTools(tools: AgentTool[], signal: AbortSignal, telemetry?: AgentToolsTelemetry): Promise<string[]>;
+export {};

package/typings/services/code-samples/apply-env-variables.d.ts

@@ -0,0 +1,8 @@
+import type { CodeSampleRequestValues } from './source.js';
+/**
+ * Substitutes `{{name}}` environment-variable placeholders in a sample using
+ * the base env variables plus the active server's scoped overrides.
+ * `requestValues.serverEnvVariables` is keyed by the raw (templated) spec
+ * server URL.
+ */
+export declare function applyEnvVariables(sample: string, requestValues: CodeSampleRequestValues | undefined, activeServerSpecUrl: string | undefined): string;

package/typings/services/code-samples/convertSampleToString.d.ts

@@ -0,0 +1,3 @@
+type RawSchema = Record<string, unknown> | undefined;
+export declare function convertSampleToString(sample: unknown, mime: string, schema?: RawSchema, repeat?: boolean): unknown;
+export {};

package/typings/services/code-samples/discriminator.d.ts

@@ -0,0 +1,66 @@
+import type { SchemaEntry } from '../../types/store.js';
+export type EffectiveDiscriminator = {
+    propertyName: string;
+    mapping: Record<string, string>;
+    defaultMapping?: string;
+    variantsNode?: Record<string, unknown>;
+};
+export declare function findEffectiveDiscriminator(schemaData: Record<string, unknown> | undefined, schemaStore: Record<string, SchemaEntry>, visited?: Set<string>): EffectiveDiscriminator | undefined;
+export declare function applyDiscriminatorValue(sample: Record<string, unknown>, variantSchemaId: string, schemaStore: Record<string, SchemaEntry>, mappingKey?: string): void;
+export type SchemaVariantOption = {
+    label: string;
+    schemaId: string;
+    mappingKey?: string;
+    isDefaultMapping?: boolean;
+    isDeprecated?: boolean;
+};
+export type HoistedVariant = {
+    schema: Record<string, unknown>;
+    variantSchemaId: string;
+    mappingKey?: string;
+};
+export type SchemaVariantAxis = {
+    kind: 'discriminator' | 'oneOf' | 'anyOf';
+    stateKey: string;
+    options: SchemaVariantOption[];
+    localPart: string;
+    parentPath: string[];
+};
+export declare function collectNestedVariantAxes(schemaData: Record<string, unknown> | undefined, schemaStore: Record<string, SchemaEntry>, out?: Map<string, SchemaVariantAxis>, visitedRefs?: Set<string>, path?: string[]): Map<string, SchemaVariantAxis>;
+export declare function findSchemaVariantAxis(schemaId: string, schemaStore: Record<string, SchemaEntry>, { includeNested }?: {
+    includeNested?: boolean;
+}): SchemaVariantAxis | undefined;
+export declare function resolveActiveVariantIndex(axis: SchemaVariantAxis, activeDiscriminator?: Record<string, number>, activeOneOf?: Record<string, number>): number;
+export type SchemaVariantPick = {
+    axis: SchemaVariantAxis;
+    idx: number;
+};
+export type SchemaVariantLeaf = SchemaVariantOption & {
+    key: string;
+    /** The option to select on each axis, outermost first. */
+    picks: SchemaVariantPick[];
+};
+type VariantState = {
+    activeDiscriminator?: Record<string, number>;
+    activeOneOf?: Record<string, number>;
+};
+export declare function collectVariantLeaves(axis: SchemaVariantAxis, schemaStore: Record<string, SchemaEntry>, visited?: ReadonlySet<string>): SchemaVariantLeaf[];
+export declare function findSchemaVariantLeaves(schemaId: string, schemaStore: Record<string, SchemaEntry>, options?: {
+    includeNested?: boolean;
+}): SchemaVariantLeaf[] | undefined;
+/** The state fields selecting `picks` changes: each axis writes to the record its kind owns. */
+export declare function withVariantPicks(state: VariantState, picks: readonly SchemaVariantPick[]): VariantState;
+export declare function resolveActiveVariantLeafIndex(leaves: SchemaVariantLeaf[], activeDiscriminator?: Record<string, number>, activeOneOf?: Record<string, number>): number;
+export declare function resolveActiveVariantSchemaId(schemaId: string, schemaStore: Record<string, SchemaEntry>, activeDiscriminator?: Record<string, number>, activeOneOf?: Record<string, number>): string;
+export declare function hoistActiveVariantSchemaForSampling(schemaId: string, schemaStore: Record<string, SchemaEntry>, activeDiscriminator?: Record<string, number>, activeOneOf?: Record<string, number>): HoistedVariant | undefined;
+/**
+ * Deep-collapse inline nested variant axes to the active option so generated
+ * samples follow the switcher: oneOf/anyOf collapse to the active branch
+ * (default 0) — so null branches sample as `null`: the sampler turns any
+ * surviving `oneOf: [{type: 'null'}]` wrapper into `{}` — and inline
+ * discriminator hosts collapse to the active variant with its mapping key
+ * stamped. Returns a structural clone.
+ */
+export declare function applyActiveVariantsToSchema(data: Record<string, unknown>, schemaStore: Record<string, SchemaEntry>, activeDiscriminator?: Record<string, number>, activeOneOf?: Record<string, number>, parentPath?: string[]): Record<string, unknown>;
+export declare function applyActiveVariantsToStore(schemaStore: Record<string, SchemaEntry>, activeDiscriminator?: Record<string, number>, activeOneOf?: Record<string, number>): Record<string, Record<string, unknown>>;
+export {};

package/typings/services/code-samples/example-key.d.ts

@@ -0,0 +1,25 @@
+type ResolveExample = (id: string) => {
+    key?: string;
+} | undefined;
+type ResponseCodeExamples = {
+    exampleIds?: string[];
+    mediaTypeContent?: Record<string, {
+        exampleIds?: string[];
+    }>;
+};
+/**
+ * Resolves an `exampleKey` from a pluggable tag to a store example id.
+ * Spec-level keys (e.g. `beta` under `examples:`) never equal the generated
+ * store ids (`example_N`), so the lookup goes through the entry's `key`;
+ * direct id equality is kept for callers that already hold a store id.
+ * Keys are matched across the whole list before falling back to id equality,
+ * so an author key that happens to look like a store id can't be shadowed.
+ */
+export declare function findExampleIdByKey(exampleIds: string[] | undefined, key: string | undefined, resolveExample: ResolveExample): string | undefined;
+/** Response code entries whose examples (in any media type) contain `key`. */
+export declare function responseCodesContainingKey<T extends ResponseCodeExamples>(responseCodes: T[] | undefined, key: string | undefined, resolveExample: ResolveExample): T[];
+/** Media type of a request-body map (mediaType → { exampleIds }) whose examples contain `key`. */
+export declare function mediaTypeContainingKey(requestBody: Record<string, {
+    exampleIds?: string[];
+}> | undefined, key: string | undefined, resolveExample: ResolveExample): string | undefined;
+export {};

package/typings/services/code-samples/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './source.js';
+export { convertSampleToString } from './convertSampleToString.js';