@orpc/openapi 1.1.1 → 1.3.0

package/README.md

@@ -49,6 +49,7 @@ You can find the full documentation [here](https://orpc.unnoq.com).
 - [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
 - [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
 - [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with NestJS.
 - [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
 - [@orpc/react-query](https://www.npmjs.com/package/@orpc/react-query): Integration with [React Query](https://tanstack.com/query/latest/docs/framework/react/overview).
 - [@orpc/vue-query](https://www.npmjs.com/package/@orpc/vue-query): Integration with [Vue Query](https://tanstack.com/query/latest/docs/framework/vue/overview).

package/dist/adapters/fetch/index.d.mts

@@ -8,7 +8,7 @@ import '@orpc/server/standard';
  * OpenAPI Handler for Fetch Server
  *
  * @see {@link https://orpc.unnoq.com/docs/openapi/openapi-handler OpenAPI Handler Docs}
- * @see {@link https://orpc.unnoq.com/docs/integrations/fetch-server Fetch Server Integration Docs}
+ * @see {@link https://orpc.unnoq.com/docs/adapters/http HTTP Adapter Docs}
  */
 declare class OpenAPIHandler<T extends Context> extends FetchHandler<T> {
     constructor(router: Router<any, T>, options?: NoInfer<StandardOpenAPIHandlerOptions<T> & FetchHandlerOptions<T>>);

package/dist/adapters/fetch/index.d.ts

@@ -8,7 +8,7 @@ import '@orpc/server/standard';
  * OpenAPI Handler for Fetch Server
  *
  * @see {@link https://orpc.unnoq.com/docs/openapi/openapi-handler OpenAPI Handler Docs}
- * @see {@link https://orpc.unnoq.com/docs/integrations/fetch-server Fetch Server Integration Docs}
+ * @see {@link https://orpc.unnoq.com/docs/adapters/http HTTP Adapter Docs}
  */
 declare class OpenAPIHandler<T extends Context> extends FetchHandler<T> {
     constructor(router: Router<any, T>, options?: NoInfer<StandardOpenAPIHandlerOptions<T> & FetchHandlerOptions<T>>);

package/dist/adapters/fetch/index.mjs

@@ -1,7 +1,8 @@
 import { FetchHandler } from '@orpc/server/fetch';
+import '@orpc/client';
 import '@orpc/contract';
 import '@orpc/shared';
-import { a as StandardOpenAPIHandler } from '../../shared/openapi.p5tsmBXx.mjs';
+import { a as StandardOpenAPIHandler } from '../../shared/openapi.C_UtQ8Us.mjs';
 import '@orpc/client/standard';
 import '@orpc/server';
 import 'rou3';

package/dist/adapters/node/index.d.mts

@@ -8,7 +8,7 @@ import '@orpc/server/standard';
  * OpenAPI Handler for Node Server
  *
  * @see {@link https://orpc.unnoq.com/docs/openapi/openapi-handler OpenAPI Handler Docs}
- * @see {@link https://orpc.unnoq.com/docs/integrations/node Node Integration Docs}
+ * @see {@link https://orpc.unnoq.com/docs/adapters/http HTTP Adapter Docs}
  */
 declare class OpenAPIHandler<T extends Context> extends NodeHttpHandler<T> {
     constructor(router: Router<any, T>, options?: NoInfer<StandardOpenAPIHandlerOptions<T> & NodeHttpHandlerOptions<T>>);

package/dist/adapters/node/index.d.ts

@@ -8,7 +8,7 @@ import '@orpc/server/standard';
  * OpenAPI Handler for Node Server
  *
  * @see {@link https://orpc.unnoq.com/docs/openapi/openapi-handler OpenAPI Handler Docs}
- * @see {@link https://orpc.unnoq.com/docs/integrations/node Node Integration Docs}
+ * @see {@link https://orpc.unnoq.com/docs/adapters/http HTTP Adapter Docs}
  */
 declare class OpenAPIHandler<T extends Context> extends NodeHttpHandler<T> {
     constructor(router: Router<any, T>, options?: NoInfer<StandardOpenAPIHandlerOptions<T> & NodeHttpHandlerOptions<T>>);

package/dist/adapters/node/index.mjs

@@ -1,7 +1,8 @@
 import { NodeHttpHandler } from '@orpc/server/node';
+import '@orpc/client';
 import '@orpc/contract';
 import '@orpc/shared';
-import { a as StandardOpenAPIHandler } from '../../shared/openapi.p5tsmBXx.mjs';
+import { a as StandardOpenAPIHandler } from '../../shared/openapi.C_UtQ8Us.mjs';
 import '@orpc/client/standard';
 import '@orpc/server';
 import 'rou3';

package/dist/adapters/standard/index.d.mts

@@ -6,6 +6,7 @@ import { StandardLazyRequest, StandardResponse } from '@orpc/standard-server';
 export { a as StandardOpenAPIHandler, S as StandardOpenAPIHandlerOptions } from '../../shared/openapi.D3j94c9n.mjs';
 
 declare class StandardOpenAPICodec implements StandardCodec {
+    #private;
     private readonly serializer;
     constructor(serializer: StandardOpenAPISerializer);
     decode(request: StandardLazyRequest, params: StandardParams | undefined, procedure: AnyProcedure): Promise<unknown>;

package/dist/adapters/standard/index.d.ts

@@ -6,6 +6,7 @@ import { StandardLazyRequest, StandardResponse } from '@orpc/standard-server';
 export { a as StandardOpenAPIHandler, S as StandardOpenAPIHandlerOptions } from '../../shared/openapi.D3j94c9n.js';
 
 declare class StandardOpenAPICodec implements StandardCodec {
+    #private;
     private readonly serializer;
     constructor(serializer: StandardOpenAPISerializer);
     decode(request: StandardLazyRequest, params: StandardParams | undefined, procedure: AnyProcedure): Promise<unknown>;

package/dist/adapters/standard/index.mjs

@@ -1,6 +1,7 @@
-export { S as StandardOpenAPICodec, a as StandardOpenAPIHandler, b as StandardOpenAPIMatcher, d as decodeParams, t as toRou3Pattern } from '../../shared/openapi.p5tsmBXx.mjs';
+export { S as StandardOpenAPICodec, a as StandardOpenAPIHandler, b as StandardOpenAPIMatcher, d as decodeParams, t as toRou3Pattern } from '../../shared/openapi.C_UtQ8Us.mjs';
 import '@orpc/openapi-client/standard';
 import '@orpc/server/standard';
+import '@orpc/client';
 import '@orpc/contract';
 import '@orpc/shared';
 import '@orpc/client/standard';

package/dist/index.d.mts

@@ -1,13 +1,14 @@
 import { AnyContractProcedure } from '@orpc/contract';
 import { OpenAPIV3_1 } from 'openapi-types';
 export { OpenAPIV3_1 as OpenAPI } from 'openapi-types';
-export { d as CompositeSchemaConverter, C as ConditionalSchemaConverter, b as OpenAPIGenerator, a as OpenAPIGeneratorGenerateOptions, O as OpenAPIGeneratorOptions, S as SchemaConvertOptions, c as SchemaConverter } from './shared/openapi.DP97kr00.mjs';
+export { d as CompositeSchemaConverter, C as ConditionalSchemaConverter, b as OpenAPIGenerator, a as OpenAPIGeneratorGenerateOptions, O as OpenAPIGeneratorOptions, S as SchemaConvertOptions, c as SchemaConverter } from './shared/openapi.CwdCLgSU.mjs';
 import { HTTPPath, HTTPMethod } from '@orpc/client';
 import { JSONSchema } from 'json-schema-typed/draft-2020-12';
-export { JSONSchema, Format as JSONSchemaFormat } from 'json-schema-typed/draft-2020-12';
+export { JSONSchema, ContentEncoding as JSONSchemaContentEncoding, Format as JSONSchemaFormat } from 'json-schema-typed/draft-2020-12';
+import { JsonifiedClient } from '@orpc/openapi-client';
+import { AnyRouter, ClientContext, Lazyable, CreateProcedureClientOptions, InferRouterInitialContext, Schema, ErrorMap, Meta, RouterClient } from '@orpc/server';
+import { MaybeOptionalOptions } from '@orpc/shared';
 import '@orpc/openapi-client/standard';
-import '@orpc/server';
-import '@orpc/shared';
 
 type OverrideOperationValue = Partial<OpenAPIV3_1.OperationObject> | ((current: OpenAPIV3_1.OperationObject, procedure: AnyContractProcedure) => OpenAPIV3_1.OperationObject);
 /**
@@ -66,6 +67,8 @@ declare function checkParamsSchema(schema: ObjectSchema, params: string[]): bool
  */
 declare function toOpenAPISchema(schema: JSONSchema): OpenAPIV3_1.SchemaObject & object;
 
+declare function createJsonifiedRouterClient<T extends AnyRouter, TClientContext extends ClientContext>(router: Lazyable<T | undefined>, ...rest: MaybeOptionalOptions<CreateProcedureClientOptions<InferRouterInitialContext<T>, Schema<unknown, unknown>, ErrorMap, Meta, TClientContext>>): JsonifiedClient<RouterClient<T, TClientContext>>;
+
 /**
  *@internal
  */
@@ -87,10 +90,16 @@ declare function separateObjectSchema(schema: ObjectSchema, separatedProperties:
  */
 declare function filterSchemaBranches(schema: JSONSchema, check: (schema: JSONSchema) => boolean, matches?: JSONSchema[]): [matches: JSONSchema[], rest: JSONSchema | undefined];
 declare function applySchemaOptionality(required: boolean, schema: JSONSchema): JSONSchema;
+/**
+ * Takes a JSON schema and, if it's primarily a union type (anyOf, oneOf),
+ * recursively expands it into an array of its constituent, non-union base schemas.
+ * If the schema is not a simple union or is a base type, it's returned as a single-element array.
+ */
+declare function expandUnionSchema(schema: JSONSchema): JSONSchema[];
 
 declare const oo: {
     spec: typeof customOpenAPIOperation;
 };
 
-export { LOGIC_KEYWORDS, applyCustomOpenAPIOperation, applySchemaOptionality, checkParamsSchema, customOpenAPIOperation, filterSchemaBranches, getCustomOpenAPIOperation, isAnySchema, isFileSchema, isObjectSchema, oo, separateObjectSchema, toOpenAPIContent, toOpenAPIEventIteratorContent, toOpenAPIMethod, toOpenAPIParameters, toOpenAPIPath, toOpenAPISchema };
+export { LOGIC_KEYWORDS, applyCustomOpenAPIOperation, applySchemaOptionality, checkParamsSchema, createJsonifiedRouterClient, customOpenAPIOperation, expandUnionSchema, filterSchemaBranches, getCustomOpenAPIOperation, isAnySchema, isFileSchema, isObjectSchema, oo, separateObjectSchema, toOpenAPIContent, toOpenAPIEventIteratorContent, toOpenAPIMethod, toOpenAPIParameters, toOpenAPIPath, toOpenAPISchema };
 export type { FileSchema, ObjectSchema, OverrideOperationValue };

package/dist/index.d.ts

@@ -1,13 +1,14 @@
 import { AnyContractProcedure } from '@orpc/contract';
 import { OpenAPIV3_1 } from 'openapi-types';
 export { OpenAPIV3_1 as OpenAPI } from 'openapi-types';
-export { d as CompositeSchemaConverter, C as ConditionalSchemaConverter, b as OpenAPIGenerator, a as OpenAPIGeneratorGenerateOptions, O as OpenAPIGeneratorOptions, S as SchemaConvertOptions, c as SchemaConverter } from './shared/openapi.DP97kr00.js';
+export { d as CompositeSchemaConverter, C as ConditionalSchemaConverter, b as OpenAPIGenerator, a as OpenAPIGeneratorGenerateOptions, O as OpenAPIGeneratorOptions, S as SchemaConvertOptions, c as SchemaConverter } from './shared/openapi.CwdCLgSU.js';
 import { HTTPPath, HTTPMethod } from '@orpc/client';
 import { JSONSchema } from 'json-schema-typed/draft-2020-12';
-export { JSONSchema, Format as JSONSchemaFormat } from 'json-schema-typed/draft-2020-12';
+export { JSONSchema, ContentEncoding as JSONSchemaContentEncoding, Format as JSONSchemaFormat } from 'json-schema-typed/draft-2020-12';
+import { JsonifiedClient } from '@orpc/openapi-client';
+import { AnyRouter, ClientContext, Lazyable, CreateProcedureClientOptions, InferRouterInitialContext, Schema, ErrorMap, Meta, RouterClient } from '@orpc/server';
+import { MaybeOptionalOptions } from '@orpc/shared';
 import '@orpc/openapi-client/standard';
-import '@orpc/server';
-import '@orpc/shared';
 
 type OverrideOperationValue = Partial<OpenAPIV3_1.OperationObject> | ((current: OpenAPIV3_1.OperationObject, procedure: AnyContractProcedure) => OpenAPIV3_1.OperationObject);
 /**
@@ -66,6 +67,8 @@ declare function checkParamsSchema(schema: ObjectSchema, params: string[]): bool
  */
 declare function toOpenAPISchema(schema: JSONSchema): OpenAPIV3_1.SchemaObject & object;
 
+declare function createJsonifiedRouterClient<T extends AnyRouter, TClientContext extends ClientContext>(router: Lazyable<T | undefined>, ...rest: MaybeOptionalOptions<CreateProcedureClientOptions<InferRouterInitialContext<T>, Schema<unknown, unknown>, ErrorMap, Meta, TClientContext>>): JsonifiedClient<RouterClient<T, TClientContext>>;
+
 /**
  *@internal
  */
@@ -87,10 +90,16 @@ declare function separateObjectSchema(schema: ObjectSchema, separatedProperties:
  */
 declare function filterSchemaBranches(schema: JSONSchema, check: (schema: JSONSchema) => boolean, matches?: JSONSchema[]): [matches: JSONSchema[], rest: JSONSchema | undefined];
 declare function applySchemaOptionality(required: boolean, schema: JSONSchema): JSONSchema;
+/**
+ * Takes a JSON schema and, if it's primarily a union type (anyOf, oneOf),
+ * recursively expands it into an array of its constituent, non-union base schemas.
+ * If the schema is not a simple union or is a base type, it's returned as a single-element array.
+ */
+declare function expandUnionSchema(schema: JSONSchema): JSONSchema[];
 
 declare const oo: {
     spec: typeof customOpenAPIOperation;
 };
 
-export { LOGIC_KEYWORDS, applyCustomOpenAPIOperation, applySchemaOptionality, checkParamsSchema, customOpenAPIOperation, filterSchemaBranches, getCustomOpenAPIOperation, isAnySchema, isFileSchema, isObjectSchema, oo, separateObjectSchema, toOpenAPIContent, toOpenAPIEventIteratorContent, toOpenAPIMethod, toOpenAPIParameters, toOpenAPIPath, toOpenAPISchema };
+export { LOGIC_KEYWORDS, applyCustomOpenAPIOperation, applySchemaOptionality, checkParamsSchema, createJsonifiedRouterClient, customOpenAPIOperation, expandUnionSchema, filterSchemaBranches, getCustomOpenAPIOperation, isAnySchema, isFileSchema, isObjectSchema, oo, separateObjectSchema, toOpenAPIContent, toOpenAPIEventIteratorContent, toOpenAPIMethod, toOpenAPIParameters, toOpenAPIPath, toOpenAPISchema };
 export type { FileSchema, ObjectSchema, OverrideOperationValue };

package/dist/index.mjs

@@ -1,15 +1,41 @@
-import { c as customOpenAPIOperation } from './shared/openapi.fMEQd3Yd.mjs';
-export { C as CompositeSchemaConverter, L as LOGIC_KEYWORDS, O as OpenAPIGenerator, a as applyCustomOpenAPIOperation, n as applySchemaOptionality, h as checkParamsSchema, m as filterSchemaBranches, g as getCustomOpenAPIOperation, l as isAnySchema, j as isFileSchema, k as isObjectSchema, s as separateObjectSchema, d as toOpenAPIContent, e as toOpenAPIEventIteratorContent, b as toOpenAPIMethod, f as toOpenAPIParameters, t as toOpenAPIPath, i as toOpenAPISchema } from './shared/openapi.fMEQd3Yd.mjs';
-export { Format as JSONSchemaFormat } from 'json-schema-typed/draft-2020-12';
-import '@orpc/client';
+import { c as customOpenAPIOperation } from './shared/openapi.PDTdnRIU.mjs';
+export { C as CompositeSchemaConverter, L as LOGIC_KEYWORDS, O as OpenAPIGenerator, a as applyCustomOpenAPIOperation, n as applySchemaOptionality, h as checkParamsSchema, o as expandUnionSchema, m as filterSchemaBranches, g as getCustomOpenAPIOperation, l as isAnySchema, j as isFileSchema, k as isObjectSchema, s as separateObjectSchema, d as toOpenAPIContent, e as toOpenAPIEventIteratorContent, b as toOpenAPIMethod, f as toOpenAPIParameters, t as toOpenAPIPath, i as toOpenAPISchema } from './shared/openapi.PDTdnRIU.mjs';
+import { createORPCErrorFromJson } from '@orpc/client';
+import { StandardOpenAPISerializer, StandardOpenAPIJsonSerializer, StandardBracketNotationSerializer } from '@orpc/openapi-client/standard';
+import { ORPCError, createRouterClient } from '@orpc/server';
+import { resolveMaybeOptionalOptions } from '@orpc/shared';
+export { ContentEncoding as JSONSchemaContentEncoding, Format as JSONSchemaFormat } from 'json-schema-typed/draft-2020-12';
 import '@orpc/client/standard';
 import '@orpc/contract';
-import '@orpc/openapi-client/standard';
-import '@orpc/server';
-import '@orpc/shared';
+
+function createJsonifiedRouterClient(router, ...rest) {
+  const options = resolveMaybeOptionalOptions(rest);
+  const serializer = new StandardOpenAPISerializer(new StandardOpenAPIJsonSerializer(), new StandardBracketNotationSerializer());
+  options.interceptors ??= [];
+  options.interceptors.unshift(async (options2) => {
+    try {
+      return serializer.deserialize(
+        serializer.serialize(
+          await options2.next()
+        )
+      );
+    } catch (e) {
+      if (e instanceof ORPCError) {
+        throw createORPCErrorFromJson(serializer.deserialize(
+          serializer.serialize(
+            e.toJSON(),
+            { outputFormat: "plain" }
+          )
+        ));
+      }
+      throw e;
+    }
+  });
+  return createRouterClient(router, options);
+}
 
 const oo = {
   spec: customOpenAPIOperation
 };
 
-export { customOpenAPIOperation, oo };
+export { createJsonifiedRouterClient, customOpenAPIOperation, oo };

package/dist/plugins/index.d.mts

@@ -1,10 +1,10 @@
 import { Context, HTTPPath, Router } from '@orpc/server';
 import { StandardHandlerInterceptorOptions, StandardHandlerPlugin, StandardHandlerOptions } from '@orpc/server/standard';
-import { Value } from '@orpc/shared';
-import { O as OpenAPIGeneratorOptions, a as OpenAPIGeneratorGenerateOptions } from '../shared/openapi.DP97kr00.mjs';
+import { Value, Promisable } from '@orpc/shared';
+import { OpenAPIV3_1 } from 'openapi-types';
+import { O as OpenAPIGeneratorOptions, a as OpenAPIGeneratorGenerateOptions } from '../shared/openapi.CwdCLgSU.mjs';
 import '@orpc/contract';
 import '@orpc/openapi-client/standard';
-import 'openapi-types';
 import 'json-schema-typed/draft-2020-12';
 
 interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAPIGeneratorOptions {
@@ -12,7 +12,7 @@ interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAPIGenera
      * Options to pass to the OpenAPI generate.
      *
      */
-    specGenerateOptions?: Value<OpenAPIGeneratorGenerateOptions, [StandardHandlerInterceptorOptions<T>]>;
+    specGenerateOptions?: Value<Promisable<OpenAPIGeneratorGenerateOptions>, [StandardHandlerInterceptorOptions<T>]>;
     /**
      * The URL path at which to serve the OpenAPI JSON.
      *
@@ -30,27 +30,27 @@ interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAPIGenera
      *
      * @default 'API Reference'
      */
-    docsTitle?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
+    docsTitle?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
     /**
      * Arbitrary configuration object for the UI.
      */
-    docsConfig?: Value<object, [StandardHandlerInterceptorOptions<T>]>;
+    docsConfig?: Value<Promisable<Record<string, unknown>>, [StandardHandlerInterceptorOptions<T>]>;
     /**
      * HTML to inject into the <head> of the docs page.
      *
      * @default ''
      */
-    docsHead?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
+    docsHead?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
     /**
      * URL of the external script bundle for the reference UI.
      *
      * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'
      */
-    docsScriptUrl?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
+    docsScriptUrl?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
     /**
      * Override function to generate the full HTML for the docs page.
      */
-    renderDocsHtml?: (specUrl: string, title: string, head: string, scriptUrl: string, config: object | undefined) => string;
+    renderDocsHtml?: (specUrl: string, title: string, head: string, scriptUrl: string, config: Record<string, unknown> | undefined, spec: OpenAPIV3_1.Document) => string;
 }
 declare class OpenAPIReferencePlugin<T extends Context> implements StandardHandlerPlugin<T> {
     private readonly generator;

package/dist/plugins/index.d.ts

@@ -1,10 +1,10 @@
 import { Context, HTTPPath, Router } from '@orpc/server';
 import { StandardHandlerInterceptorOptions, StandardHandlerPlugin, StandardHandlerOptions } from '@orpc/server/standard';
-import { Value } from '@orpc/shared';
-import { O as OpenAPIGeneratorOptions, a as OpenAPIGeneratorGenerateOptions } from '../shared/openapi.DP97kr00.js';
+import { Value, Promisable } from '@orpc/shared';
+import { OpenAPIV3_1 } from 'openapi-types';
+import { O as OpenAPIGeneratorOptions, a as OpenAPIGeneratorGenerateOptions } from '../shared/openapi.CwdCLgSU.js';
 import '@orpc/contract';
 import '@orpc/openapi-client/standard';
-import 'openapi-types';
 import 'json-schema-typed/draft-2020-12';
 
 interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAPIGeneratorOptions {
@@ -12,7 +12,7 @@ interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAPIGenera
      * Options to pass to the OpenAPI generate.
      *
      */
-    specGenerateOptions?: Value<OpenAPIGeneratorGenerateOptions, [StandardHandlerInterceptorOptions<T>]>;
+    specGenerateOptions?: Value<Promisable<OpenAPIGeneratorGenerateOptions>, [StandardHandlerInterceptorOptions<T>]>;
     /**
      * The URL path at which to serve the OpenAPI JSON.
      *
@@ -30,27 +30,27 @@ interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAPIGenera
      *
      * @default 'API Reference'
      */
-    docsTitle?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
+    docsTitle?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
     /**
      * Arbitrary configuration object for the UI.
      */
-    docsConfig?: Value<object, [StandardHandlerInterceptorOptions<T>]>;
+    docsConfig?: Value<Promisable<Record<string, unknown>>, [StandardHandlerInterceptorOptions<T>]>;
     /**
      * HTML to inject into the <head> of the docs page.
      *
      * @default ''
      */
-    docsHead?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
+    docsHead?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
     /**
      * URL of the external script bundle for the reference UI.
      *
      * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'
      */
-    docsScriptUrl?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
+    docsScriptUrl?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
     /**
      * Override function to generate the full HTML for the docs page.
      */
-    renderDocsHtml?: (specUrl: string, title: string, head: string, scriptUrl: string, config: object | undefined) => string;
+    renderDocsHtml?: (specUrl: string, title: string, head: string, scriptUrl: string, config: Record<string, unknown> | undefined, spec: OpenAPIV3_1.Document) => string;
 }
 declare class OpenAPIReferencePlugin<T extends Context> implements StandardHandlerPlugin<T> {
     private readonly generator;

package/dist/plugins/index.mjs

@@ -1,5 +1,5 @@
-import { stringifyJSON, value } from '@orpc/shared';
-import { O as OpenAPIGenerator } from '../shared/openapi.fMEQd3Yd.mjs';
+import { stringifyJSON, once, value } from '@orpc/shared';
+import { O as OpenAPIGenerator } from '../shared/openapi.PDTdnRIU.mjs';
 import '@orpc/client';
 import '@orpc/client/standard';
 import '@orpc/contract';
@@ -27,25 +27,32 @@ class OpenAPIReferencePlugin {
     this.specPath = options.specPath ?? "/spec.json";
     this.generator = new OpenAPIGenerator(options);
     const esc = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-    this.renderDocsHtml = options.renderDocsHtml ?? ((specUrl, title, head, scriptUrl, config) => `
-      <!doctype html>
-      <html>
-        <head>
-          <meta charset="utf-8" />
-          <meta name="viewport" content="width=device-width, initial-scale=1" />
-          <title>${esc(title)}</title>
-          ${head}
-        </head>
-        <body>
-          <script 
-              id="api-reference" 
-              data-url="${esc(specUrl)}"
-              ${config !== void 0 ? `data-configuration="${esc(stringifyJSON(config))}"` : ""}
-          ><\/script>
-          <script src="${esc(scriptUrl)}"><\/script>
-        </body>
-      </html>
-    `);
+    this.renderDocsHtml = options.renderDocsHtml ?? ((specUrl, title, head, scriptUrl, config, spec) => {
+      const finalConfig = {
+        content: stringifyJSON(spec),
+        ...config
+      };
+      return `
+        <!doctype html>
+        <html>
+          <head>
+            <meta charset="utf-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1" />
+            <title>${esc(title)}</title>
+            ${head}
+          </head>
+          <body>
+            <div id="app" data-config="${esc(stringifyJSON(finalConfig))}"></div>
+
+            <script src="${esc(scriptUrl)}"><\/script>
+
+            <script>
+              Scalar.createApiReference('#app', JSON.parse(document.getElementById('app').dataset.config))
+            <\/script>
+          </body>
+        </html>
+      `;
+    });
   }
   init(options, router) {
     options.interceptors ??= [];
@@ -58,11 +65,14 @@ class OpenAPIReferencePlugin {
       const requestPathname = options2.request.url.pathname.replace(/\/$/, "") || "/";
       const docsUrl = new URL(`${prefix}${this.docsPath}`.replace(/\/$/, ""), options2.request.url.origin);
       const specUrl = new URL(`${prefix}${this.specPath}`.replace(/\/$/, ""), options2.request.url.origin);
-      if (requestPathname === specUrl.pathname) {
-        const spec = await this.generator.generate(router, {
+      const generateSpec = once(async () => {
+        return await this.generator.generate(router, {
           servers: [{ url: new URL(prefix, options2.request.url.origin).toString() }],
           ...await value(this.specGenerateOptions, options2)
         });
+      });
+      if (requestPathname === specUrl.pathname) {
+        const spec = await generateSpec();
         return {
           matched: true,
           response: {
@@ -78,7 +88,8 @@ class OpenAPIReferencePlugin {
           await value(this.docsTitle, options2),
           await value(this.docsHead, options2),
           await value(this.docsScriptUrl, options2),
-          await value(this.docsConfig, options2)
+          await value(this.docsConfig, options2),
+          await generateSpec()
         );
         return {
           matched: true,

package/dist/shared/{openapi.p5tsmBXx.mjs → openapi.C_UtQ8Us.mjs}

@@ -1,7 +1,8 @@
 import { standardizeHTTPPath, StandardOpenAPIJsonSerializer, StandardBracketNotationSerializer, StandardOpenAPISerializer } from '@orpc/openapi-client/standard';
 import { StandardHandler } from '@orpc/server/standard';
+import { isORPCErrorStatus } from '@orpc/client';
 import { fallbackContractConfig } from '@orpc/contract';
-import { isObject } from '@orpc/shared';
+import { isObject, stringifyJSON } from '@orpc/shared';
 import { toHttpPath } from '@orpc/client/standard';
 import { traverseContractProcedures, isProcedure, getLazyMeta, unlazy, getRouter, createContractedProcedure } from '@orpc/server';
 import { createRouter, addRoute, findRoute } from 'rou3';
@@ -52,13 +53,21 @@ class StandardOpenAPICodec {
         body: this.serializer.serialize(output)
       };
     }
-    if (!isObject(output)) {
-      throw new Error(
-        'Invalid output structure for "detailed" output. Expected format: { body: any, headers?: Record<string, string | string[] | undefined> }'
-      );
+    if (!this.#isDetailedOutput(output)) {
+      throw new Error(`
+        Invalid "detailed" output structure:
+        \u2022 Expected an object with optional properties:
+          - status (number 200-399)
+          - headers (Record<string, string | string[]>)
+          - body (any)
+        \u2022 No extra keys allowed.
+
+        Actual value:
+          ${stringifyJSON(output)}
+      `);
     }
     return {
-      status: successStatus,
+      status: output.status ?? successStatus,
       headers: output.headers ?? {},
       body: this.serializer.serialize(output.body)
     };
@@ -70,6 +79,18 @@ class StandardOpenAPICodec {
       body: this.serializer.serialize(error.toJSON(), { outputFormat: "plain" })
     };
   }
+  #isDetailedOutput(output) {
+    if (!isObject(output)) {
+      return false;
+    }
+    if (output.headers && !isObject(output.headers)) {
+      return false;
+    }
+    if (output.status !== void 0 && (typeof output.status !== "number" || !Number.isInteger(output.status) || isORPCErrorStatus(output.status))) {
+      return false;
+    }
+    return true;
+  }
 }
 
 function toRou3Pattern(path) {

package/dist/shared/{openapi.DP97kr00.d.mts → openapi.CwdCLgSU.d.mts}

@@ -1,6 +1,6 @@
-import { AnySchema, AnyContractRouter } from '@orpc/contract';
+import { AnySchema, AnyContractProcedure, AnyContractRouter } from '@orpc/contract';
 import { StandardOpenAPIJsonSerializerOptions } from '@orpc/openapi-client/standard';
-import { AnyRouter } from '@orpc/server';
+import { AnyProcedure, AnyRouter } from '@orpc/server';
 import { OpenAPIV3_1 } from 'openapi-types';
 import { Promisable } from '@orpc/shared';
 import { JSONSchema } from 'json-schema-typed/draft-2020-12';
@@ -24,6 +24,12 @@ interface OpenAPIGeneratorOptions extends StandardOpenAPIJsonSerializerOptions {
     schemaConverters?: ConditionalSchemaConverter[];
 }
 interface OpenAPIGeneratorGenerateOptions extends Partial<Omit<OpenAPIV3_1.Document, 'openapi'>> {
+    /**
+     * Exclude procedures from the OpenAPI specification.
+     *
+     * @default () => false
+     */
+    exclude?: (procedure: AnyProcedure | AnyContractProcedure, path: readonly string[]) => boolean;
 }
 /**
  * The generator that converts oRPC routers/contracts to OpenAPI specifications.

package/dist/shared/{openapi.DP97kr00.d.ts → openapi.CwdCLgSU.d.ts}

@@ -1,6 +1,6 @@
-import { AnySchema, AnyContractRouter } from '@orpc/contract';
+import { AnySchema, AnyContractProcedure, AnyContractRouter } from '@orpc/contract';
 import { StandardOpenAPIJsonSerializerOptions } from '@orpc/openapi-client/standard';
-import { AnyRouter } from '@orpc/server';
+import { AnyProcedure, AnyRouter } from '@orpc/server';
 import { OpenAPIV3_1 } from 'openapi-types';
 import { Promisable } from '@orpc/shared';
 import { JSONSchema } from 'json-schema-typed/draft-2020-12';
@@ -24,6 +24,12 @@ interface OpenAPIGeneratorOptions extends StandardOpenAPIJsonSerializerOptions {
     schemaConverters?: ConditionalSchemaConverter[];
 }
 interface OpenAPIGeneratorGenerateOptions extends Partial<Omit<OpenAPIV3_1.Document, 'openapi'>> {
+    /**
+     * Exclude procedures from the OpenAPI specification.
+     *
+     * @default () => false
+     */
+    exclude?: (procedure: AnyProcedure | AnyContractProcedure, path: readonly string[]) => boolean;
 }
 /**
  * The generator that converts oRPC routers/contracts to OpenAPI specifications.

package/dist/shared/{openapi.fMEQd3Yd.mjs → openapi.PDTdnRIU.mjs}

@@ -1,9 +1,9 @@
-import { fallbackORPCErrorStatus, fallbackORPCErrorMessage } from '@orpc/client';
+import { isORPCErrorStatus, fallbackORPCErrorStatus, fallbackORPCErrorMessage } from '@orpc/client';
 import { toHttpPath } from '@orpc/client/standard';
 import { fallbackContractConfig, getEventIteratorSchemaDetails } from '@orpc/contract';
 import { standardizeHTTPPath, StandardOpenAPIJsonSerializer, getDynamicParams } from '@orpc/openapi-client/standard';
 import { isProcedure, resolveContractProcedures } from '@orpc/server';
-import { isObject, findDeepMatches, toArray, clone } from '@orpc/shared';
+import { isObject, findDeepMatches, toArray, clone, stringifyJSON } from '@orpc/shared';
 import 'json-schema-typed/draft-2020-12';
 
 const OPERATION_EXTENDER_SYMBOL = Symbol("ORPC_OPERATION_EXTENDER");
@@ -184,6 +184,18 @@ function applySchemaOptionality(required, schema) {
     ]
   };
 }
+function expandUnionSchema(schema) {
+  if (typeof schema === "object") {
+    for (const keyword of ["anyOf", "oneOf"]) {
+      if (schema[keyword] && Object.keys(schema).every(
+        (k) => k === keyword || !LOGIC_KEYWORDS.includes(k)
+      )) {
+        return schema[keyword].flatMap((s) => expandUnionSchema(s));
+      }
+    }
+  }
+  return [schema];
+}
 
 function toOpenAPIPath(path) {
   return standardizeHTTPPath(path).replace(/\/\{\+([^}]+)\}/g, "/{$1}");
@@ -312,14 +324,18 @@ class OpenAPIGenerator {
    * @see {@link https://orpc.unnoq.com/docs/openapi/openapi-specification OpenAPI Specification Docs}
    */
   async generate(router, options = {}) {
+    const exclude = options.exclude ?? (() => false);
     const doc = {
       ...clone(options),
       info: options.info ?? { title: "API Reference", version: "0.0.0" },
-      openapi: "3.1.1"
+      openapi: "3.1.1",
+      exclude: void 0
     };
     const contracts = [];
     await resolveContractProcedures({ path: [], router }, ({ contract, path }) => {
-      contracts.push({ contract, path });
+      if (!exclude(contract, path)) {
+        contracts.push({ contract, path });
+      }
     });
     const errors = [];
     for (const { contract, path } of contracts) {
@@ -459,36 +475,71 @@ ${errors.join("\n\n")}`
       return;
     }
     const [required, json] = await this.converter.convert(outputSchema, { strategy: "output" });
-    ref.responses ??= {};
-    ref.responses[status] = {
-      description
-    };
     if (outputStructure === "compact") {
+      ref.responses ??= {};
+      ref.responses[status] = {
+        description
+      };
       ref.responses[status].content = toOpenAPIContent(applySchemaOptionality(required, json));
       return;
     }
-    const error = new OpenAPIGeneratorError(
-      'When output structure is "detailed", output schema must satisfy: { headers?: Record<string, unknown>, body?: unknown }'
-    );
-    if (!isObjectSchema(json)) {
-      throw error;
-    }
-    if (json.properties?.headers !== void 0) {
-      if (!isObjectSchema(json.properties.headers)) {
+    const handledStatuses = /* @__PURE__ */ new Set();
+    for (const item of expandUnionSchema(json)) {
+      const error = new OpenAPIGeneratorError(`
+        When output structure is "detailed", output schema must satisfy:
+        { 
+          status?: number, // must be a literal number and in the range of 200-399
+          headers?: Record<string, unknown>, 
+          body?: unknown 
+        }
+        
+        But got: ${stringifyJSON(item)}
+      `);
+      if (!isObjectSchema(item)) {
         throw error;
       }
-      for (const key in json.properties.headers.properties) {
-        ref.responses[status].headers ??= {};
-        ref.responses[status].headers[key] = {
-          schema: toOpenAPISchema(json.properties.headers.properties[key]),
-          required: json.properties.headers.required?.includes(key)
-        };
+      let schemaStatus;
+      let schemaDescription;
+      if (item.properties?.status !== void 0) {
+        if (typeof item.properties.status !== "object" || item.properties.status.const === void 0 || typeof item.properties.status.const !== "number" || !Number.isInteger(item.properties.status.const) || isORPCErrorStatus(item.properties.status.const)) {
+          throw error;
+        }
+        schemaStatus = item.properties.status.const;
+        schemaDescription = item.properties.status.description;
+      }
+      const itemStatus = schemaStatus ?? status;
+      const itemDescription = schemaDescription ?? description;
+      if (handledStatuses.has(itemStatus)) {
+        throw new OpenAPIGeneratorError(`
+          When output structure is "detailed", each success status must be unique.
+          But got status: ${itemStatus} used more than once.
+        `);
+      }
+      handledStatuses.add(itemStatus);
+      ref.responses ??= {};
+      ref.responses[itemStatus] = {
+        description: itemDescription
+      };
+      if (item.properties?.headers !== void 0) {
+        if (!isObjectSchema(item.properties.headers)) {
+          throw error;
+        }
+        for (const key in item.properties.headers.properties) {
+          const headerSchema = item.properties.headers.properties[key];
+          if (headerSchema !== void 0) {
+            ref.responses[itemStatus].headers ??= {};
+            ref.responses[itemStatus].headers[key] = {
+              schema: toOpenAPISchema(headerSchema),
+              required: item.properties.headers.required?.includes(key)
+            };
+          }
+        }
+      }
+      if (item.properties?.body !== void 0) {
+        ref.responses[itemStatus].content = toOpenAPIContent(
+          applySchemaOptionality(item.required?.includes("body") ?? false, item.properties.body)
+        );
       }
-    }
-    if (json.properties?.body !== void 0) {
-      ref.responses[status].content = toOpenAPIContent(
-        applySchemaOptionality(json.required?.includes("body") ?? false, json.properties.body)
-      );
     }
   }
   async #errorResponse(ref, def) {
@@ -541,4 +592,4 @@ ${errors.join("\n\n")}`
   }
 }
 
-export { CompositeSchemaConverter as C, LOGIC_KEYWORDS as L, OpenAPIGenerator as O, applyCustomOpenAPIOperation as a, toOpenAPIMethod as b, customOpenAPIOperation as c, toOpenAPIContent as d, toOpenAPIEventIteratorContent as e, toOpenAPIParameters as f, getCustomOpenAPIOperation as g, checkParamsSchema as h, toOpenAPISchema as i, isFileSchema as j, isObjectSchema as k, isAnySchema as l, filterSchemaBranches as m, applySchemaOptionality as n, separateObjectSchema as s, toOpenAPIPath as t };
+export { CompositeSchemaConverter as C, LOGIC_KEYWORDS as L, OpenAPIGenerator as O, applyCustomOpenAPIOperation as a, toOpenAPIMethod as b, customOpenAPIOperation as c, toOpenAPIContent as d, toOpenAPIEventIteratorContent as e, toOpenAPIParameters as f, getCustomOpenAPIOperation as g, checkParamsSchema as h, toOpenAPISchema as i, isFileSchema as j, isObjectSchema as k, isAnySchema as l, filterSchemaBranches as m, applySchemaOptionality as n, expandUnionSchema as o, separateObjectSchema as s, toOpenAPIPath as t };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orpc/openapi",
   "type": "module",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "license": "MIT",
   "homepage": "https://orpc.unnoq.com",
   "repository": {
@@ -47,15 +47,15 @@
     "json-schema-typed": "^8.0.1",
     "openapi-types": "^12.1.3",
     "rou3": "^0.6.0",
-    "@orpc/client": "1.1.1",
-    "@orpc/openapi-client": "1.1.1",
-    "@orpc/server": "1.1.1",
-    "@orpc/contract": "1.1.1",
-    "@orpc/standard-server": "1.1.1",
-    "@orpc/shared": "1.1.1"
+    "@orpc/client": "1.3.0",
+    "@orpc/contract": "1.3.0",
+    "@orpc/server": "1.3.0",
+    "@orpc/shared": "1.3.0",
+    "@orpc/standard-server": "1.3.0",
+    "@orpc/openapi-client": "1.3.0"
   },
   "devDependencies": {
-    "zod": "^3.24.2"
+    "zod": "^3.25.11"
   },
   "scripts": {
     "build": "unbuild",