@orpc/openapi 0.0.0-next.3cc45a9 → 0.0.0-next.3d9f498

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.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

@@ -90,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, createJsonifiedRouterClient, 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

@@ -90,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, createJsonifiedRouterClient, 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,5 +1,5 @@
-import { c as customOpenAPIOperation } from './shared/openapi.DqPCYbM9.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.DqPCYbM9.mjs';
+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';

package/dist/plugins/index.d.mts

@@ -1,6 +1,6 @@
 import { Context, HTTPPath, Router } from '@orpc/server';
 import { StandardHandlerInterceptorOptions, StandardHandlerPlugin, StandardHandlerOptions } from '@orpc/server/standard';
-import { Value } from '@orpc/shared';
+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';
@@ -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,23 +30,23 @@ 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<Record<string, unknown>, [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.
      */

package/dist/plugins/index.d.ts

@@ -1,6 +1,6 @@
 import { Context, HTTPPath, Router } from '@orpc/server';
 import { StandardHandlerInterceptorOptions, StandardHandlerPlugin, StandardHandlerOptions } from '@orpc/server/standard';
-import { Value } from '@orpc/shared';
+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';
@@ -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,23 +30,23 @@ 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<Record<string, unknown>, [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.
      */

package/dist/plugins/index.mjs

@@ -1,5 +1,5 @@
 import { stringifyJSON, once, value } from '@orpc/shared';
-import { O as OpenAPIGenerator } from '../shared/openapi.DqPCYbM9.mjs';
+import { O as OpenAPIGenerator } from '../shared/openapi.PDTdnRIU.mjs';
 import '@orpc/client';
 import '@orpc/client/standard';
 import '@orpc/contract';

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.DqPCYbM9.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}");
@@ -463,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) {
@@ -545,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": "0.0.0-next.3cc45a9",
+  "version": "0.0.0-next.3d9f498",
   "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": "0.0.0-next.3cc45a9",
-    "@orpc/openapi-client": "0.0.0-next.3cc45a9",
-    "@orpc/contract": "0.0.0-next.3cc45a9",
-    "@orpc/server": "0.0.0-next.3cc45a9",
-    "@orpc/shared": "0.0.0-next.3cc45a9",
-    "@orpc/standard-server": "0.0.0-next.3cc45a9"
+    "@orpc/client": "0.0.0-next.3d9f498",
+    "@orpc/contract": "0.0.0-next.3d9f498",
+    "@orpc/openapi-client": "0.0.0-next.3d9f498",
+    "@orpc/shared": "0.0.0-next.3d9f498",
+    "@orpc/standard-server": "0.0.0-next.3d9f498",
+    "@orpc/server": "0.0.0-next.3d9f498"
   },
   "devDependencies": {
-    "zod": "^3.24.2"
+    "zod": "^3.25.11"
   },
   "scripts": {
     "build": "unbuild",