vocs 2.0.17 → 2.1.2

package/dist/internal/openapi/openapi.d.ts

@@ -0,0 +1,187 @@
+/**
+ * OpenAPI integration config.
+ *
+ * Mounts an isolated, auto-generated API reference section in the docs from an
+ * OpenAPI spec. Use {@link from} to define an entry in `vocs.config.ts`.
+ */
+import type * as VocsConfig from '../config.js';
+import type { SidebarItem } from '../sidebar.js';
+/**
+ * Spec source.
+ *
+ * - A file path relative to the project root (e.g. `./openapi.yaml`).
+ * - A URL (e.g. `https://example.com/openapi.json`).
+ * - Raw JSON/YAML content.
+ * - An inline OpenAPI document object.
+ */
+export type Spec = string | Record<string, unknown>;
+/**
+ * A spec source, an already-started promise resolving to one, or a (lazy)
+ * provider that returns one. Promises/providers are awaited once when the
+ * reference is first rendered (and the result reused), so specs generated at
+ * runtime — e.g. from a server framework like `hono-openapi` — can be passed
+ * without resolving them up front. This lets `Handler.openApi` be constructed
+ * synchronously (and mounted via `app.route(...)`) even when the spec is
+ * produced asynchronously: build it eagerly and pass the promise directly.
+ *
+ * @example
+ * ```ts
+ * const spec = generateSpecs(app) // Promise<Spec>, started eagerly
+ * app.route('/', Handler.openApi({ spec }, { fallback: 'next' }))
+ * ```
+ */
+export type SpecInput = Spec | Promise<Spec> | (() => Spec | Promise<Spec>);
+/**
+ * Extra sidebar items to add around the auto-generated section.
+ *
+ * These are typically links to consumer-authored override/guide pages mounted
+ * under the same `path` (e.g. `pages/api/auth.mdx`).
+ */
+export type SidebarExtras = {
+    /** Items prepended above the generated `Introduction`/categories. */
+    top?: SidebarItem[] | undefined;
+    /** Items appended below the generated categories. */
+    bottom?: SidebarItem[] | undefined;
+    /**
+     * Items nested under the generated `Introduction` entry. When provided, the
+     * `Introduction` leaf becomes a collapsible group whose first child is an
+     * `Overview` link to the landing page, followed by these items (typically
+     * links to guide `pages` mounted under the section, e.g. authentication or
+     * versioning).
+     */
+    intro?: SidebarItem[] | undefined;
+    /**
+     * Collapse the generated category groups by default. The group matching the
+     * active page still auto-expands, so deep links stay navigable. The generated
+     * `Introduction` entry is unaffected.
+     *
+     * @default false
+     */
+    collapsed?: boolean | undefined;
+};
+/**
+ * A consumer-authored `.md`/`.mdx` page mounted into an OpenAPI section.
+ *
+ * In the Vite/site integration these are discovered automatically by the file
+ * router (e.g. `pages/api/auth.mdx`). In the standalone server handler
+ * ({@link file://./../../server/handlers.ts `Handler.openApi`}) — which has no
+ * filesystem router — they are supplied explicitly so override/guide content can
+ * still be rendered.
+ *
+ * - `path` is the route relative to the section mount (e.g. `/` overrides the
+ *   landing intro, `/auth` is a guide page, `/<group>` overrides a category
+ *   header).
+ * - `file` is the path to the `.md`/`.mdx` source, resolved against the handler
+ *   `rootDir` (default `process.cwd()`). Reading a file requires `node:fs`, so
+ *   on filesystem-less runtimes (e.g. Cloudflare Workers) supply `content`
+ *   instead.
+ * - `content` is the `.md`/`.mdx` source inline, an alternative to `file` that
+ *   needs no filesystem access. Exactly one of `file`/`content` is required.
+ * - `title` overrides the document title otherwise taken from frontmatter or the
+ *   first `# heading`, and renders as the page's heading on standalone guide
+ *   pages.
+ * - `description` renders as a subtitle below the title on standalone guide
+ *   pages (Markdown). Also taken from frontmatter `description` when omitted.
+ */
+export type Page = {
+    path: string;
+    file?: string | undefined;
+    content?: string | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+};
+export type Config = {
+    /**
+     * OpenAPI spec source: file path, URL, raw content, inline object, or a (lazy)
+     * provider function returning any of those.
+     */
+    spec: SpecInput;
+    /**
+     * Mount path for the generated API reference section.
+     *
+     * The section gets its own isolated sidebar scoped to this path.
+     *
+     * Required for the Vite/site integration. Optional for the standalone
+     * {@link file://./../../server/handlers.ts `Handler.openApi`} handler (the
+     * Hono mount provides the location; `path` only seeds generated link bases and
+     * defaults to `/`).
+     *
+     * @example "/api"
+     */
+    path?: string | undefined;
+    /**
+     * Extra sidebar items to add around the auto-generated section (e.g. links to
+     * consumer-authored guide pages mounted under `path`).
+     *
+     * @example
+     * ```ts
+     * sidebar: {
+     *   top: [{ text: 'Authentication', link: '/api/auth' }],
+     *   bottom: [{ text: 'Errors', link: '/api/errors' }],
+     * }
+     * ```
+     */
+    sidebar?: SidebarExtras | undefined;
+    /**
+     * Consumer-authored `.md`/`.mdx` override/guide pages.
+     *
+     * Only used by the standalone {@link file://./../../server/handlers.ts
+     * `Handler.openApi`} handler — the Vite/site integration discovers these via
+     * the file router instead.
+     */
+    pages?: Page[] | undefined;
+    /**
+     * Vocs config passthrough for the standalone {@link
+     * file://./../../server/handlers.ts `Handler.openApi`} handler.
+     *
+     * The handler renders the real Vocs layout, so these options customize the
+     * chrome (theme, top navigation, logo, socials, …) exactly like a
+     * `vocs.config.ts`.
+     *
+     * `title` and `description` default to the spec's `info.title`/`info.description`
+     * but can be overridden here. `sidebar` is derived from the generated section
+     * (plus the `sidebar` config above) and cannot be set here.
+     *
+     * @example
+     * ```ts
+     * vocs: {
+     *   title: 'Acme Docs',
+     *   logoUrl: '/logo.svg',
+     *   theme: { accentColor: '#7c3aed' },
+     *   topNav: [{ text: 'Home', link: 'https://acme.com' }],
+     * }
+     * ```
+     */
+    vocs?: Omit<VocsConfig.define.Options, 'sidebar' | 'openapi'> | undefined;
+};
+/**
+ * Config for the Vite/site integration, where `path` is required (it scopes the
+ * generated sidebar and routes).
+ */
+export type SiteConfig = Config & {
+    path: string;
+};
+/**
+ * Defines an OpenAPI integration entry.
+ *
+ * @example
+ * ```ts
+ * import { OpenApi } from 'vocs/config'
+ *
+ * export default defineConfig({
+ *   openapi: [
+ *     OpenApi.from({ spec: './openapi.yaml', path: '/api' }),
+ *   ],
+ * })
+ * ```
+ */
+export declare function from(config: from.Options): SiteConfig;
+export declare namespace from {
+    type Options = SiteConfig;
+}
+/**
+ * Normalizes a mount path: ensures a leading slash and strips any trailing
+ * slash (except for the root `/`).
+ */
+export declare function normalizePath(path: string): string;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/internal/openapi/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../src/internal/openapi/openapi.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,KAAK,UAAU,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;AAE3E;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,qEAAqE;IACrE,GAAG,CAAC,EAAE,WAAW,EAAE,GAAG,SAAS,CAAA;IAC/B,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,EAAE,GAAG,SAAS,CAAA;IAClC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,WAAW,EAAE,GAAG,SAAS,CAAA;IACjC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAChC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,IAAI,GAAG;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACjC,CAAA;AAED,MAAM,MAAM,MAAM,GAAG;IACnB;;;OAGG;IACH,IAAI,EAAE,SAAS,CAAA;IACf;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;IACnC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAA;IAC1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,CAAC,GAAG,SAAS,CAAA;CAC1E,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAChC,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,GAAG,UAAU,CAYrD;AAED,MAAM,CAAC,OAAO,WAAW,IAAI,CAAC;IAC5B,KAAK,OAAO,GAAG,UAAU,CAAA;CAC1B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlD"}

package/dist/internal/openapi/openapi.js

@@ -0,0 +1,44 @@
+/**
+ * OpenAPI integration config.
+ *
+ * Mounts an isolated, auto-generated API reference section in the docs from an
+ * OpenAPI spec. Use {@link from} to define an entry in `vocs.config.ts`.
+ */
+/**
+ * Defines an OpenAPI integration entry.
+ *
+ * @example
+ * ```ts
+ * import { OpenApi } from 'vocs/config'
+ *
+ * export default defineConfig({
+ *   openapi: [
+ *     OpenApi.from({ spec: './openapi.yaml', path: '/api' }),
+ *   ],
+ * })
+ * ```
+ */
+export function from(config) {
+    const { spec, path, sidebar, pages } = config;
+    if (!spec)
+        throw new Error('[vocs] `openapi` entry is missing a `spec`.');
+    if (!path)
+        throw new Error('[vocs] `openapi` entry is missing a `path`.');
+    return {
+        spec,
+        path: normalizePath(path),
+        ...(sidebar ? { sidebar } : {}),
+        ...(pages ? { pages } : {}),
+    };
+}
+/**
+ * Normalizes a mount path: ensures a leading slash and strips any trailing
+ * slash (except for the root `/`).
+ */
+export function normalizePath(path) {
+    let normalized = path.startsWith('/') ? path : `/${path}`;
+    if (normalized.length > 1 && normalized.endsWith('/'))
+        normalized = normalized.slice(0, -1);
+    return normalized;
+}
+//# sourceMappingURL=openapi.js.map

package/dist/internal/openapi/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../../../src/internal/openapi/openapi.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAsKH;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,IAAI,CAAC,MAAoB;IACvC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,CAAA;IAE7C,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IACzE,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;IAEzE,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC;QACzB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5B,CAAA;AACH,CAAC;AAMD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAA;IACzD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC3F,OAAO,UAAU,CAAA;AACnB,CAAC"}

package/dist/internal/openapi/openrpc.d.ts

@@ -0,0 +1,90 @@
+import type { IrOperation } from './parser.js';
+/**
+ * Minimal structural typing for the OpenRPC documents we expand. Only the
+ * fields consumed during expansion are modeled; everything else is ignored.
+ *
+ * @see https://spec.open-rpc.org
+ */
+export type Document = {
+    openrpc?: string;
+    info?: {
+        title?: string;
+        version?: string;
+        description?: string;
+    };
+    methods?: Method[];
+    components?: {
+        schemas?: Record<string, unknown>;
+    };
+};
+export type Method = {
+    name: string;
+    summary?: string;
+    description?: string;
+    deprecated?: boolean;
+    params?: ContentDescriptor[];
+    result?: ContentDescriptor;
+    examples?: Example[];
+};
+type ContentDescriptor = {
+    name?: string;
+    summary?: string;
+    description?: string;
+    required?: boolean;
+    deprecated?: boolean;
+    schema?: Record<string, unknown>;
+};
+type Example = {
+    name?: string;
+    params?: {
+        name?: string;
+        value?: unknown;
+    }[];
+    result?: {
+        name?: string;
+        value?: unknown;
+    };
+};
+/**
+ * Expands an OpenRPC document into one {@link IrOperation} per JSON-RPC method,
+ * modeled after a single host HTTP operation (the JSON-RPC endpoint).
+ *
+ * JSON-RPC methods all POST the same envelope to one endpoint, which OpenAPI
+ * cannot express as distinct path items. Expanding at the IR level instead lets
+ * each method become its own sidebar entry and page section while keeping the
+ * shared transport: every generated operation reuses the host operation's
+ * `method` (POST) and `path`, so request code samples target the real endpoint.
+ *
+ * Each method maps to:
+ * - `summary` → the method name (the sidebar/section title)
+ * - `description` → the method summary + description
+ * - `parameters` (`in: 'rpc'`) → the JSON-RPC params, rendered like path/query
+ *   params
+ * - `requestBody` → the JSON-RPC request envelope, `hidden` from the body
+ *   section but used to generate an accurate request code sample
+ * - a `200` response → the JSON-RPC response envelope wrapping the method result
+ */
+export declare function expand(host: IrOperation, document: Document | string, options?: expand.Options): Promise<expand.Result>;
+export declare namespace expand {
+    type Options = {
+        /**
+         * Base URL relative `x-openrpc` URLs (e.g. `/openrpc.json`) resolve against:
+         * the spec URL when the spec was loaded from a URL, or the request origin in
+         * the standalone server handler.
+         */
+        baseUrl?: string | undefined;
+    };
+    /** A named JSON-RPC request example to inject onto the host operation. */
+    type RpcExample = {
+        summary?: string | undefined;
+        value: unknown;
+    };
+    type Result = {
+        /** One IR operation per JSON-RPC method. */
+        operations: IrOperation[];
+        /** Request examples keyed by method name, for the host operation. */
+        examples: Record<string, RpcExample>;
+    };
+}
+export {};
+//# sourceMappingURL=openrpc.d.ts.map

package/dist/internal/openapi/openrpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openrpc.d.ts","sourceRoot":"","sources":["../../../src/internal/openapi/openrpc.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,aAAa,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACjE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,UAAU,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;CACnD,CAAA;AAED,MAAM,MAAM,MAAM,GAAG;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC5B,MAAM,CAAC,EAAE,iBAAiB,CAAA;IAC1B,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CACrB,CAAA;AAED,KAAK,iBAAiB,GAAG;IACvB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACjC,CAAA;AAED,KAAK,OAAO,GAAG;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;IAC7C,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAC5C,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,MAAM,CAC1B,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAC3B,OAAO,GAAE,MAAM,CAAC,OAAY,GAC3B,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAwFxB;AAED,MAAM,CAAC,OAAO,WAAW,MAAM,CAAC;IAC9B,KAAK,OAAO,GAAG;QACb;;;;WAIG;QACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAC7B,CAAA;IACD,0EAA0E;IAC1E,KAAK,UAAU,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAA;IAClE,KAAK,MAAM,GAAG;QACZ,4CAA4C;QAC5C,UAAU,EAAE,WAAW,EAAE,CAAA;QACzB,qEAAqE;QACrE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;KACrC,CAAA;CACF"}

package/dist/internal/openapi/openrpc.js

@@ -0,0 +1,213 @@
+import { dereference } from '@scalar/openapi-parser';
+import GithubSlugger from 'github-slugger';
+/**
+ * Expands an OpenRPC document into one {@link IrOperation} per JSON-RPC method,
+ * modeled after a single host HTTP operation (the JSON-RPC endpoint).
+ *
+ * JSON-RPC methods all POST the same envelope to one endpoint, which OpenAPI
+ * cannot express as distinct path items. Expanding at the IR level instead lets
+ * each method become its own sidebar entry and page section while keeping the
+ * shared transport: every generated operation reuses the host operation's
+ * `method` (POST) and `path`, so request code samples target the real endpoint.
+ *
+ * Each method maps to:
+ * - `summary` → the method name (the sidebar/section title)
+ * - `description` → the method summary + description
+ * - `parameters` (`in: 'rpc'`) → the JSON-RPC params, rendered like path/query
+ *   params
+ * - `requestBody` → the JSON-RPC request envelope, `hidden` from the body
+ *   section but used to generate an accurate request code sample
+ * - a `200` response → the JSON-RPC response envelope wrapping the method result
+ */
+export async function expand(host, document, options = {}) {
+    const resolved = await resolve(document, options);
+    const methods = resolved.methods ?? [];
+    const slugger = new GithubSlugger();
+    // Named request examples (keyed by method name) injected onto the host
+    // operation so the interactive client (Scalar) can prefill the JSON-RPC
+    // envelope for each method. JSON-RPC methods all share one path+verb, so the
+    // client distinguishes them by selecting the matching named example.
+    const examples = {};
+    const operations = methods.map((method) => {
+        const example = method.examples?.[0];
+        const parameters = (method.params ?? []).map((param, index) => ({
+            name: param.name ?? `param${index}`,
+            in: 'rpc',
+            required: param.required,
+            deprecated: param.deprecated,
+            description: param.description ?? param.summary,
+            schema: param.schema,
+            example: paramExample(param, index, example),
+        }));
+        // The wire-format example values (positional `params` array) used for the
+        // request code sample and to fill in any params the examples omit.
+        const paramValues = parameters.map((parameter) => parameter.example !== undefined ? parameter.example : sampleFromSchema(parameter.schema));
+        const requestExample = {
+            jsonrpc: '2.0',
+            id: 1,
+            method: method.name,
+            params: paramValues,
+        };
+        examples[method.name] = { summary: method.summary, value: requestExample };
+        const resultSchema = method.result?.schema;
+        const resultValue = example?.result?.value !== undefined ? example.result.value : sampleFromSchema(resultSchema);
+        const responseExample = { jsonrpc: '2.0', id: 1, result: resultValue };
+        const description = [method.summary, method.description].filter(Boolean).join('\n\n');
+        return {
+            id: slugger.slug(method.name),
+            method: host.method,
+            path: host.path,
+            // Name of the host operation's request example to select in the
+            // interactive client (matches the key added to `examples` above).
+            rpcExample: method.name,
+            summary: method.name,
+            description: description || undefined,
+            deprecated: method.deprecated,
+            parameters,
+            requestBody: {
+                required: true,
+                // Hidden from the rendered "Request Body" section: the params already
+                // appear in the "Parameters" section and the literal envelope shows in
+                // the request code sample. The body is still used to build that sample.
+                hidden: true,
+                content: [
+                    {
+                        mediaType: 'application/json',
+                        schema: requestEnvelopeSchema(method),
+                        example: requestExample,
+                    },
+                ],
+            },
+            responses: [
+                {
+                    status: '200',
+                    description: method.result?.description ?? 'JSON-RPC response.',
+                    content: [
+                        {
+                            mediaType: 'application/json',
+                            schema: responseEnvelopeSchema(resultSchema),
+                            example: responseExample,
+                        },
+                    ],
+                    headers: [],
+                },
+            ],
+        };
+    });
+    return { operations, examples };
+}
+/**
+ * Resolves an OpenRPC source (URL, raw JSON, or object) to a dereferenced doc.
+ *
+ * A string is treated as raw JSON when it begins with `{`; otherwise it's a
+ * URL. Absolute (`http(s)://`) URLs are fetched directly. Relative URLs (e.g.
+ * `/openrpc.json`, the host-relative link an OpenAPI document commonly uses) are
+ * resolved against `baseUrl` — the spec URL when the spec was loaded from a URL,
+ * or the request origin in the standalone server handler — then fetched.
+ */
+async function resolve(document, options = {}) {
+    let raw = document;
+    if (typeof document === 'string') {
+        const trimmed = document.trimStart();
+        if (trimmed.startsWith('{')) {
+            raw = JSON.parse(trimmed);
+        }
+        else {
+            const url = trimmed.startsWith('http://') || trimmed.startsWith('https://')
+                ? trimmed
+                : options.baseUrl
+                    ? new URL(trimmed, options.baseUrl).toString()
+                    : undefined;
+            if (!url)
+                throw new Error(`Cannot resolve relative OpenRPC document "${trimmed}" without a base URL.`);
+            const response = await fetch(url);
+            if (!response.ok)
+                throw new Error(`Failed to fetch OpenRPC document from ${url}: ${response.statusText}`);
+            raw = await response.json();
+        }
+    }
+    // Dereference internal `$ref`s (`#/components/schemas/...`) so the renderer
+    // sees concrete schemas, matching how the OpenAPI parser dereferences specs.
+    const { schema } = await dereference(raw);
+    return (schema ?? raw);
+}
+/** JSON-RPC request envelope schema for a method (used only for code samples). */
+function requestEnvelopeSchema(method) {
+    return {
+        type: 'object',
+        properties: {
+            jsonrpc: { type: 'string', const: '2.0' },
+            id: { type: 'integer' },
+            method: { type: 'string', const: method.name },
+            params: {
+                type: 'array',
+                prefixItems: (method.params ?? []).map((param) => param.schema ?? {}),
+            },
+        },
+        required: ['jsonrpc', 'method'],
+    };
+}
+/** JSON-RPC response envelope schema wrapping a method's result schema. */
+function responseEnvelopeSchema(resultSchema) {
+    return {
+        type: 'object',
+        properties: {
+            jsonrpc: { type: 'string', const: '2.0' },
+            id: { type: 'integer' },
+            ...(resultSchema ? { result: resultSchema } : {}),
+        },
+    };
+}
+/** Looks up the example value for a param, by name then position. */
+function paramExample(param, index, example) {
+    const entries = example?.params ?? [];
+    const byName = param.name ? entries.find((entry) => entry.name === param.name) : undefined;
+    const entry = byName ?? entries[index];
+    return entry?.value;
+}
+/**
+ * Derives a representative value from a JSON Schema for methods/params that lack
+ * authored examples. Intentionally small — prefers authored `example`/`default`/
+ * `enum` values and otherwise falls back to a type-based placeholder.
+ */
+function sampleFromSchema(schema) {
+    if (!schema || typeof schema !== 'object')
+        return undefined;
+    if ('example' in schema)
+        return schema['example'];
+    if (Array.isArray(schema['examples']) && schema['examples'].length > 0)
+        return schema['examples'][0];
+    if ('default' in schema)
+        return schema['default'];
+    if ('const' in schema)
+        return schema['const'];
+    if (Array.isArray(schema['enum']) && schema['enum'].length > 0)
+        return schema['enum'][0];
+    const type = Array.isArray(schema['type']) ? schema['type'][0] : schema['type'];
+    switch (type) {
+        case 'string':
+            return 'string';
+        case 'integer':
+        case 'number':
+            return 0;
+        case 'boolean':
+            return true;
+        case 'array': {
+            const items = schema['items'];
+            const item = sampleFromSchema(items);
+            return item === undefined ? [] : [item];
+        }
+        case 'object': {
+            const properties = schema['properties'];
+            if (!properties)
+                return {};
+            const result = {};
+            for (const [key, value] of Object.entries(properties))
+                result[key] = sampleFromSchema(value);
+            return result;
+        }
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=openrpc.js.map

package/dist/internal/openapi/openrpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openrpc.js","sourceRoot":"","sources":["../../../src/internal/openapi/openrpc.ts"],"names":[],"mappings":"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"}