redoc 2.5.4 → 3.0.0-rc.1

package/typings/services/search/indexer/schema-walker.d.ts

@@ -0,0 +1,29 @@
+import type { OperationParameter } from '@redocly/theme/core/openapi';
+import type { SchemaEntry } from '../../../types/store.js';
+import type { SchemaNode } from '../../../types/schema.js';
+import type { DescriptionFormatter, WalkScope } from './context.js';
+export type SchemaFieldsArgs = {
+    schemaId: string;
+    place: string;
+    paramsMap: Record<string, OperationParameter>;
+    slug: string;
+    mediaType?: string;
+    hasMultipleMediaTypes?: boolean;
+    isResponse?: boolean;
+    linkType?: string;
+    visited?: Set<string>;
+};
+/** Walks raw JSON schemas from the schema store into flat `OperationParameter` rows. */
+export declare class SchemaWalker {
+    #private;
+    constructor(deps: {
+        schemaStore?: Record<string, SchemaEntry>;
+        document?: Record<string, unknown>;
+        formatDescription: DescriptionFormatter;
+    });
+    extractSchemaFields({ schemaId, ...args }: SchemaFieldsArgs, scope?: WalkScope): void;
+    /** Walks a schema that is not in the store (MCP input/output schemas, prompt arguments). */
+    extractSchemaNodeFields(schema: SchemaNode, { place, paramsMap, slug, mediaType, hasMultipleMediaTypes, isResponse, linkType, visited }: Omit<SchemaFieldsArgs, 'schemaId'>, scope?: WalkScope): void;
+    resolveParameterType(schemaId: string): string;
+    resolveEffectiveSchema(schema: SchemaNode): SchemaNode;
+}

package/typings/services/search/indexer/text.d.ts

@@ -0,0 +1,2 @@
+import type { ContentNode } from '../../../types/content.js';
+export declare function extractText(children: ContentNode[]): string;

package/typings/services/search/init.d.ts

@@ -0,0 +1,7 @@
+import type { ApiItem, ApiStore } from '../../types/store.js';
+import type { SearchItemData } from './types.js';
+export type SearchApi = {
+    search: (query: string) => Promise<SearchItemData[]>;
+};
+/** Builds the client-side search index from the item model, yielding to the event loop so large APIs don't block rendering. */
+export declare function initializeSearch(items: ApiItem[], store: ApiStore, basePath: string, document?: Record<string, unknown>): Promise<SearchApi>;

package/typings/services/search/text-match.d.ts

@@ -0,0 +1,5 @@
+export declare const MIN_QUERY_WORD_LENGTH = 2;
+export declare const MIN_INFIX_MATCH_LENGTH = 3;
+export declare function isWordChar(char: string | undefined): boolean;
+export declare function matchableQueryWords(query: string): string[];
+export declare function containsQueryWord(lowered: string, word: string): boolean;

package/typings/services/search/types.d.ts

@@ -0,0 +1,32 @@
+import type { OperationParameter, ParameterHighlight as ThemeParameterHighlight } from '@redocly/theme/core/openapi';
+import type { ItemBadge } from '@redocly/config';
+import type { RouteKind } from '../../utils/routeKind.js';
+export type ParameterHighlight = ThemeParameterHighlight & {
+    enum?: string;
+    example?: string;
+};
+export type SearchDocument = {
+    id: string;
+    url: string;
+    title: string | string[];
+    text: string | string[];
+    path?: string[];
+    httpMethod?: string;
+    httpPath?: string | string[];
+    isAdditionalOperation?: boolean;
+    isSchemaDefinition?: boolean;
+    deprecated?: boolean;
+    security?: string[];
+    parameters?: OperationParameter[];
+    badges?: ItemBadge[];
+    kind?: RouteKind;
+};
+export type SearchItemData = {
+    document: SearchDocument;
+    highlight: Record<string, string> & {
+        parameters?: ParameterHighlight[];
+        path?: string[];
+    };
+};
+export type { OperationParameter } from '@redocly/theme/core/openapi';
+export type { ItemBadge } from '@redocly/config';

package/typings/services/spec-slice/assistant-links.d.ts

@@ -0,0 +1,9 @@
+import type { SliceContentKind, SpecSliceScope } from './types.js';
+export declare const ASSISTANT_LINK_BASES: {
+    readonly chatgpt: 'https://chatgpt.com';
+    readonly claude: 'https://claude.ai/new';
+};
+export declare const MAX_ASSISTANT_URL_LENGTH = 8000;
+export declare function buildInlinePromptLink(baseUrl: string, content: string, contentKind?: SliceContentKind): string | undefined;
+export declare function describeSliceScope(scope: SpecSliceScope): string | undefined;
+export declare function buildFetchSpecPromptLink(baseUrl: string, specUrl: string, scope: SpecSliceScope): string;

package/typings/services/spec-slice/asyncapi-slice.d.ts

@@ -0,0 +1,5 @@
+import type { SpecSliceScope } from './types.js';
+export declare function scopeFromAsyncApiPointer(pointer: string): SpecSliceScope | undefined;
+export declare function extractAsyncApiSlice(document: Record<string, unknown>, scope: SpecSliceScope): {
+    document: Record<string, unknown>;
+} | undefined;

package/typings/services/spec-slice/clone-strip.d.ts

@@ -0,0 +1 @@
+export declare function cloneStrip(value: unknown, inlineTargets: ReadonlyMap<string, unknown>): unknown;

package/typings/services/spec-slice/component-closure.d.ts

@@ -0,0 +1,6 @@
+export type ComponentClosure = {
+    keep: Map<string, Set<string>>;
+    inlineTargets: Map<string, unknown>;
+};
+export declare function collectComponentClosure(document: Record<string, unknown>, seeds: unknown[], retainRef?: (ref: string) => boolean): ComponentClosure;
+export declare function buildComponentsFromClosure(document: Record<string, unknown>, keep: Map<string, Set<string>>): Record<string, unknown> | undefined;

package/typings/services/spec-slice/graphql-slice.d.ts

@@ -0,0 +1,2 @@
+import type { SpecSliceScope } from './types.js';
+export declare function extractGraphqlSlice(sdl: string, scope: SpecSliceScope): string | undefined;

package/typings/services/spec-slice/index.d.ts

@@ -0,0 +1,6 @@
+import type { ApiSpecType } from '../../types/common.js';
+import type { SpecSliceScope } from './types.js';
+export { resolveSpecSliceScope } from './resolve-scope.js';
+export { ASSISTANT_LINK_BASES, buildInlinePromptLink, buildFetchSpecPromptLink, } from './assistant-links.js';
+export type { SliceContentKind, SpecSliceScope } from './types.js';
+export declare function buildSpecSlice(specType: ApiSpecType, document: unknown, scope: SpecSliceScope): Promise<string | undefined>;

package/typings/services/spec-slice/openapi-slice.d.ts

@@ -0,0 +1,6 @@
+import type { SpecSliceScope } from './types.js';
+export declare function parsePointerTokens(pointer: string): string[];
+export declare function operationScopeFromPointer(pointer: string, isWebhook: boolean | undefined): SpecSliceScope | undefined;
+export declare function extractOpenApiSlice(document: Record<string, unknown>, scope: SpecSliceScope): {
+    document: Record<string, unknown>;
+} | undefined;

package/typings/services/spec-slice/resolve-scope.d.ts

@@ -0,0 +1,4 @@
+import type { ApiItemContent } from '../../types/store.js';
+import type { ApiSpecType } from '../../types/common.js';
+import type { SpecSliceScope } from './types.js';
+export declare function resolveSpecSliceScope(specType: ApiSpecType, content: ApiItemContent | null | undefined, label: string | undefined, groupMemberContents?: Array<ApiItemContent | null | undefined>): SpecSliceScope | undefined;

package/typings/services/spec-slice/types.d.ts

@@ -0,0 +1,37 @@
+export type GraphqlOperationType = 'query' | 'mutation' | 'subscription';
+export type GraphqlItemScope = {
+    kind: 'graphql-operation';
+    operationType: GraphqlOperationType;
+    name: string;
+} | {
+    kind: 'graphql-type';
+    name: string;
+} | {
+    kind: 'graphql-directive';
+    name: string;
+};
+export type SpecSliceScope = {
+    kind: 'document';
+} | {
+    kind: 'tag';
+    tagName: string;
+} | {
+    kind: 'operation';
+    pathName: string;
+    httpVerb: string;
+    source: 'paths' | 'webhooks';
+} | {
+    kind: 'schema';
+    name: string;
+} | {
+    kind: 'channel';
+    channelId: string;
+} | {
+    kind: 'async-operation';
+    operationId: string;
+} | GraphqlItemScope | {
+    kind: 'graphql-group';
+    label?: string;
+    members: GraphqlItemScope[];
+};
+export type SliceContentKind = 'yaml' | 'graphql';

package/typings/standalone.d.ts

@@ -0,0 +1,20 @@
+import './crypto-uuid-compat.js';
+import { type Root } from 'react-dom/client';
+import type { RedocStandaloneProps } from './RedocStandalone.js';
+import type { TypeOfUsage } from './telemetry/RedocTelemetry.js';
+import { RedocStandalone } from './RedocStandalone.js';
+export { RedocStandalone };
+export type { RedocStandaloneProps };
+export type InitOptions = NonNullable<RedocStandaloneProps['options']> & {
+    router?: 'hash' | 'history';
+    disableTelemetry?: boolean;
+    /** The Docker image sets `type-of-usage="docker"` on the `<redoc>` element. */
+    typeOfUsage?: TypeOfUsage;
+    basePath?: string;
+};
+export declare function init(specOrSpecUrl: string | Record<string, unknown>, options?: InitOptions, element?: Element | null): Root;
+/**
+ * Attaches to server-rendered markup instead of replacing it. The spec must be
+ * the same pre-bundled document the server pass rendered from.
+ */
+export declare function hydrate(specOrSpecUrl: string | Record<string, unknown>, options?: InitOptions, element?: Element | null): Promise<void>;

package/typings/standaloneThemeConfig.d.ts

@@ -0,0 +1,3 @@
+import type { ThemeDataTransferObject } from '@redocly/theme/core/openapi';
+/** Community edition: hides theme UI that needs a portal backend — the code-block report button and all generic page actions. Only the spec-driven x-mcp connect actions remain. */
+export declare const STANDALONE_THEME_CONFIG: ThemeDataTransferObject['config'] | undefined;

package/typings/telemetry/RedocTelemetry.d.ts

@@ -0,0 +1,22 @@
+import { Telemetry } from '@redocly/redoc-opentelemetry';
+import type { EventType, EventPayload } from '@redocly/redoc-opentelemetry';
+export type SpecType = 'openapi' | 'asyncapi' | 'graphql';
+export type TypeOfUsage = 'html' | 'cli' | 'react' | 'init' | 'docker';
+/** Sees every array payload before it is sent; returning `false` drops the event. */
+export type BeforeSend = (event: EventType, items: unknown[]) => boolean | void;
+export interface RedocTelemetryConfig {
+    specType?: SpecType;
+    collectorUrl?: string;
+    serviceName?: string;
+    disabled?: boolean;
+    serviceVersion?: string;
+    typeOfUsage?: TypeOfUsage;
+    beforeSend?: BeforeSend;
+}
+export declare class RedocTelemetry extends Telemetry {
+    private specType;
+    private beforeSend;
+    readonly typeOfUsage: TypeOfUsage | undefined;
+    constructor(config: RedocTelemetryConfig);
+    send<T extends EventType>(event: T, data?: EventPayload<T>): void;
+}

package/typings/telemetry/TypeOfUsageContext.d.ts

@@ -0,0 +1,3 @@
+import type { TypeOfUsage } from './RedocTelemetry.js';
+/** How the page embeds Redoc: `init()` provides `html` or `docker`, `hydrate()` provides `cli`. */
+export declare const TypeOfUsageContext: import("react").Context<TypeOfUsage | undefined>;

package/typings/telemetry/defaults.d.ts

@@ -0,0 +1,7 @@
+import type { TypeOfUsage } from './RedocTelemetry.js';
+export declare const TELEMETRY_DISABLED_BY_DEFAULT = false;
+export declare const DEFAULT_SERVICE_NAME = "redoc-ce";
+export declare const DEFAULT_TYPE_OF_USAGE: TypeOfUsage | undefined;
+/** Page identifier used by page-level events and as the PageResource of UI events; `undefined` means `location.href`. */
+export declare const PAGE_URI: string | undefined;
+export declare const PAGE_VIEWED_PER_ROUTE = true;

package/typings/telemetry/events.d.ts

@@ -0,0 +1,42 @@
+import type { EventPayload } from '@redocly/redoc-opentelemetry';
+type UiResource<O extends string, I extends string> = {
+    id: I;
+    object: O;
+    uri: `urn:redocly:redoc:ui:${O}:${I}`;
+};
+export declare function uiResource<O extends string, I extends string>(object: O, id: I): UiResource<O, I>;
+export declare const RESOURCES: {
+    readonly asyncapiDocsChannelLink: UiResource<"link", "asyncapiDocsChannelLink">;
+    readonly changeLayoutButton: UiResource<"button", "changeLayoutButton">;
+    readonly colorMode: UiResource<"button", "colorMode">;
+    readonly connectMcp: UiResource<"button", "connectMcp">;
+    readonly copyCodeSnippetButton: UiResource<"button", "copyCodeSnippetButton">;
+    readonly definitionLoad: UiResource<"definition", "definitionLoad">;
+    readonly downloadDefinition: UiResource<"definition", "downloadDefinition">;
+    readonly examplesSwitcherButton: UiResource<"button", "examplesSwitcherButton">;
+    readonly expandCollapseAllButton: UiResource<"button", "expandCollapseAllButton">;
+    readonly graphqlDocsReferencedInLink: UiResource<"link", "graphqlDocsReferencedInLink">;
+    readonly messageLink: UiResource<"link", "messageLink">;
+    readonly pageActions: UiResource<"button", "pageActions">;
+    readonly redoclyAttribution: UiResource<"link", "redoclyAttribution">;
+    readonly redocSecurityButton: UiResource<"button", "redocSecurityButton">;
+    readonly redocSecurityButtonClose: UiResource<"button", "redocSecurityButtonClose">;
+    readonly requiredScopesButton: UiResource<"button", "requiredScopesButton">;
+    readonly responseCodeTab: UiResource<"tab", "responseCodeTab">;
+    readonly schemaFieldToggle: UiResource<"button", "schemaFieldToggle">;
+    readonly searchDialog: UiResource<"search", "searchDialog">;
+    readonly searchInputResetButton: UiResource<"button", "searchInputResetButton">;
+    readonly searchQuery: UiResource<"search", "searchQuery">;
+    readonly securityOptionalScopesToggle: UiResource<"button", "securityOptionalScopesToggle">;
+    readonly selectLanguageButton: UiResource<"button", "selectLanguageButton">;
+    readonly serverModalButton: UiResource<"button", "serverModalButton">;
+    readonly sidebarCollapse: UiResource<"button", "sidebarCollapse">;
+    readonly sidebarItem: UiResource<"sidebar", "sidebarItem">;
+    readonly switchExampleButton: UiResource<"button", "switchExampleButton">;
+    readonly switchMessageButton: UiResource<"button", "switchMessageButton">;
+    readonly switchServersButton: UiResource<"button", "switchServersButton">;
+    readonly tryItButton: UiResource<"button", "tryItButton">;
+};
+/** Item for `downloadDefinition.clicked`: the constant resource when `PAGE_URI` is set, so no host, URL or label is sent; otherwise the resolved download URL. */
+export declare function downloadDefinitionItem(label: string | undefined, url: string): EventPayload<'com.redocly.downloadDefinition.clicked'>[0];
+export {};

package/typings/telemetry/fields.d.ts

@@ -0,0 +1,7 @@
+import type { EventPayload } from '@redocly/redoc-opentelemetry';
+export type StatusClass = NonNullable<EventPayload<'com.redocly.responseCodeTab.clicked'>[0]['statusClass']>;
+export type Protocol = NonNullable<EventPayload<'com.redocly.switchServers.clicked'>[0]['protocol']>;
+/** A built-in language key, or `other` for a site-authored name (`x-codeSamples` lang or label, `codeSamples.languages` label). */
+export declare function languageOf(value: string): string;
+export declare function statusClassOf(code: string): StatusClass;
+export declare function normalizeProtocol(value: string | undefined): Protocol;

package/typings/telemetry/index.d.ts

@@ -0,0 +1,15 @@
+export { useTelemetry } from '../hooks/useTelemetry.js';
+export { TelemetryContext } from '../contexts/telemetry.js';
+export type { RedocTelemetryConfig } from './RedocTelemetry.js';
+export { useRedocTelemetryInstance } from './useRedocTelemetryInstance.js';
+export { RESOURCES, downloadDefinitionItem, uiResource } from './events.js';
+export { languageOf, normalizeProtocol, statusClassOf } from './fields.js';
+export { OAUTH2_FLOW_NAMES, countSchemes } from './security.js';
+export type { Oauth2Flow } from './security.js';
+export { getPageUri } from './page.js';
+export { sanitizeErrorDetails } from './sanitizeError.js';
+export { reportDefinitionLoadFailed } from './reportDefinitionLoadFailed.js';
+export { useSchemaFieldTelemetry } from './useSchemaFieldTelemetry.js';
+export { useSidebarItemTelemetry } from './useSidebarItemTelemetry.js';
+export { nonDefaultOptions } from './initialPayload.js';
+export type { BuildTimings, InitialTelemetryContext } from './initialPayload.js';

package/typings/telemetry/initialPayload.d.ts

@@ -0,0 +1,56 @@
+import type { EventPayload } from '@redocly/redoc-opentelemetry';
+import type { LayoutVariant } from '@redocly/config';
+import type { ApiItem, ApiStore } from '../types/store.js';
+import type { ItemVariant } from '../types/common.js';
+import type { RouteKind } from '../utils/routeKind.js';
+import type { TypeOfUsage } from './RedocTelemetry.js';
+type InitialItem = EventPayload<'com.redocly.redoc.initialized'>[0];
+type Shape = NonNullable<InitialItem['shape']>;
+type RedocExtensions = NonNullable<InitialItem['redocExtensions']>;
+type ProtocolFlags = NonNullable<Shape['protocols']>;
+export type BuildTimings = {
+    resolveSpecMs: number;
+    buildItemsMs: number;
+};
+export type TelemetryOptionValue = string | number | boolean;
+export type InitialTelemetryContext = {
+    buildTimings?: BuildTimings;
+    options?: Record<string, TelemetryOptionValue>;
+};
+export declare function countItems(items: ApiItem[]): {
+    byVariant: Partial<Record<ItemVariant, number>>;
+    operations: number;
+    groups: number;
+    webhooks: number;
+    deprecated: number;
+};
+export declare function securityShape(securitySchemeStore: ApiStore['securitySchemeStore']): Pick<Shape, 'securitySchemes' | 'schemeTypes' | 'oauth2Flows'>;
+export type DocumentScan = {
+    specVersion?: string;
+    extensionsCount: number;
+    redocExtensions: RedocExtensions;
+    hasCodeSamples: boolean;
+    callbacks: number;
+    servers: number;
+    hasBindings: boolean;
+    hasReply: boolean;
+    protocols?: ProtocolFlags;
+};
+export declare function scanDocument(document: Record<string, unknown>): DocumentScan;
+export declare function openApiSecurityShape(document: Record<string, unknown>): Pick<Shape, 'hasGlobalSecurity' | 'securedOperations' | 'optionalSecurityOperations' | 'combinedSecurityOperations' | 'alternativeSecurityOperations'>;
+export declare function isLocalhost(hostname: string): boolean;
+export declare function nonDefaultOptions(raw: Record<string, unknown> | undefined): Record<string, TelemetryOptionValue> | undefined;
+export type InitialPayloadInput = {
+    uri: string;
+    layout: LayoutVariant;
+    typeOfUsage?: TypeOfUsage;
+    items: ApiItem[];
+    apiStore: ApiStore;
+    definition?: Record<string, unknown> | string;
+    hostname: string;
+    landedOn: RouteKind;
+    buildTimings?: BuildTimings;
+    options?: Record<string, TelemetryOptionValue>;
+};
+export declare function buildInitialPayload(input: InitialPayloadInput): InitialItem;
+export {};

package/typings/telemetry/page.d.ts

@@ -0,0 +1,5 @@
+import type { EventType } from '@redocly/redoc-opentelemetry';
+export declare function getPageUri(): string;
+export declare const PAGE_LEVEL_EVENTS: ReadonlySet<EventType>;
+/** Appends the constant page item so the SDK does not inject `location.href` and the referrer. */
+export declare function withPageItem(event: EventType, items: unknown[]): unknown[];

package/typings/telemetry/reportDefinitionLoadFailed.d.ts

@@ -0,0 +1,9 @@
+import type { RedocTelemetryConfig } from './RedocTelemetry.js';
+type ReportOptions = {
+    source: 'url' | 'inline';
+    durationMs: number;
+    telemetryConfig?: Partial<RedocTelemetryConfig>;
+};
+/** Sends `definition.loadFailed` with its own instance: the loader renders above any provider. */
+export declare function reportDefinitionLoadFailed(error: unknown, { source, durationMs, telemetryConfig }: ReportOptions): void;
+export {};

package/typings/telemetry/sanitizeError.d.ts

@@ -0,0 +1,4 @@
+import type { EventPayload } from '@redocly/redoc-opentelemetry';
+type ErrorDetails = NonNullable<EventPayload<'com.redocly.error.occurred'>[0]['details']>;
+export declare function sanitizeErrorDetails(error: Error, componentStack?: string | null): ErrorDetails;
+export {};

package/typings/telemetry/security.d.ts

@@ -0,0 +1,15 @@
+import type { EventPayload } from '@redocly/redoc-opentelemetry';
+type SecurityDetails = EventPayload<'com.redocly.viewSecurityDetails.clicked'>[0];
+export type SchemeTypeKey = keyof NonNullable<SecurityDetails['schemeTypes']>;
+export type Oauth2Flow = keyof NonNullable<SecurityDetails['oauth2Flows']>;
+export declare const OAUTH2_FLOW_NAMES: ReadonlySet<string>;
+export declare function schemeTypeKey(type: string | undefined, scheme: string | undefined): SchemeTypeKey;
+export declare function countSchemes(schemes: Iterable<{
+    type?: string;
+    scheme?: string;
+    flows?: object | null;
+}>): {
+    schemeTypes: Partial<Record<SchemeTypeKey, number>>;
+    oauth2Flows: Partial<Record<Oauth2Flow, number>>;
+};
+export {};

package/typings/telemetry/useRedocTelemetryInstance.d.ts

@@ -0,0 +1,3 @@
+import type { RedocTelemetryConfig } from './RedocTelemetry.js';
+import { RedocTelemetry } from './RedocTelemetry.js';
+export declare function useRedocTelemetryInstance(config?: Partial<RedocTelemetryConfig>): RedocTelemetry;

package/typings/telemetry/useSchemaFieldTelemetry.d.ts

@@ -0,0 +1,4 @@
+import type { EventPayload } from '@redocly/redoc-opentelemetry';
+import { RESOURCES } from './events.js';
+export type SchemaFieldToggle = Omit<EventPayload<'com.redocly.schemaField.expanded'>[0], keyof typeof RESOURCES.schemaFieldToggle | 'specType'>;
+export declare function useSchemaFieldTelemetry(): (toggle: SchemaFieldToggle) => void;

package/typings/telemetry/useSidebarItemTelemetry.d.ts

@@ -0,0 +1,11 @@
+import type { MouseEvent } from 'react';
+import type { EventPayload } from '@redocly/redoc-opentelemetry';
+type SidebarItemType = EventPayload<'com.redocly.sidebarItem.clicked'>[0]['type'];
+type SidebarItemClick = {
+    type: SidebarItemType;
+    depth: number;
+    navigates: boolean;
+};
+export declare function sidebarItemFromTarget(target: Element): SidebarItemClick | null;
+export declare function useSidebarItemTelemetry(): (event: MouseEvent<HTMLElement>) => void;
+export {};