orpc-fn 0.1.0

package/dist/mcp.d.ts

@@ -0,0 +1,39 @@
+import { type AnyProcedure, type AnyRouter, type TraverseContractProcedureCallbackOptions } from '@orpc/server';
+import { rawInputSchema, type ToolSchema } from './json-schema.js';
+import { toToolName } from './meta.js';
+export { toToolName };
+export { rawInputSchema as toolInputSchema };
+export type { ToolSchema };
+/** Picks procedures; also fits oRPC's `OpenAPIHandler({ filter })`. */
+export type ProcedureFilter = (options: TraverseContractProcedureCallbackOptions) => boolean;
+export type McpTool = {
+    /** Tool name: the sanitized `fn` name (`user.me` becomes `user-me`). */
+    name: string;
+    procedure: AnyProcedure;
+    config: {
+        description?: string;
+        /**
+         * Validates and coerces (date strings to `Date`) but returns the raw
+         * input: pass it to `call(procedure, args)`, which parses it.
+         */
+        inputSchema?: ToolSchema;
+        annotations: {
+            readOnlyHint: boolean;
+        };
+    };
+};
+/** Procedures whose route has `tag`: `listTools(router, { filter: hasTag('external') })`. */
+export declare const hasTag: (tag: string) => ProcedureFilter;
+/**
+ * MCP tool definitions for the procedures in `router` matching `filter`
+ * (default: all). Register them with any MCP server:
+ * `server.registerTool(tool.name, tool.config, run)`.
+ *
+ * `readOnly` sets `readOnlyHint`; it defaults to GET routes, since an MCP
+ * client treats anything else as a mutation and may ask for approval.
+ */
+export declare function listTools(router: AnyRouter, options?: {
+    filter?: ProcedureFilter;
+    readOnly?: ProcedureFilter;
+}): McpTool[];
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,wCAAwC,EAE7C,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClE,OAAO,EAAc,UAAU,EAAE,MAAM,WAAW,CAAA;AAElD,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,OAAO,EAAE,cAAc,IAAI,eAAe,EAAE,CAAA;AAC5C,YAAY,EAAE,UAAU,EAAE,CAAA;AAE1B,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,CAC7B,OAAO,EAAE,wCAAwC,KAC7C,OAAO,CAAA;AAEZ,MAAM,MAAM,OAAO,GAAG;IACrB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,YAAY,CAAA;IACvB,MAAM,EAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB;;;WAGG;QACH,WAAW,CAAC,EAAE,UAAU,CAAA;QACxB,WAAW,EAAE;YAAE,YAAY,EAAE,OAAO,CAAA;SAAE,CAAA;KACtC,CAAA;CACD,CAAA;AAED,6FAA6F;AAC7F,eAAO,MAAM,MAAM,QACZ,MAAM,KAAG,eAEsC,CAAA;AAKtD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACxB,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,EAAE,eAAe,CAAA;CAAO,GACpE,OAAO,EAAE,CAmBX"}

package/dist/mcp.js

@@ -0,0 +1,38 @@
+import { traverseContractProcedures } from '@orpc/server';
+import { rawInputSchema } from './json-schema.js';
+import { readFnMeta, toToolName } from './meta.js';
+export { toToolName };
+export { rawInputSchema as toolInputSchema };
+/** Procedures whose route has `tag`: `listTools(router, { filter: hasTag('external') })`. */
+export const hasTag = (tag) => ({ contract }) => contract['~orpc'].route.tags?.includes(tag) ?? false;
+const isGet = ({ contract }) => contract['~orpc'].route.method === 'GET';
+/**
+ * MCP tool definitions for the procedures in `router` matching `filter`
+ * (default: all). Register them with any MCP server:
+ * `server.registerTool(tool.name, tool.config, run)`.
+ *
+ * `readOnly` sets `readOnlyHint`; it defaults to GET routes, since an MCP
+ * client treats anything else as a mutation and may ask for approval.
+ */
+export function listTools(router, options = {}) {
+    const { filter, readOnly = isGet } = options;
+    const tools = [];
+    traverseContractProcedures({ router, path: [] }, (traversed) => {
+        if (filter && !filter(traversed))
+            return;
+        const procedure = traversed.contract;
+        const { inputSchema, route } = procedure['~orpc'];
+        const description = route.description ?? route.summary;
+        tools.push({
+            name: toToolName(readFnMeta(procedure).name ?? traversed.path.join('.')),
+            procedure,
+            config: {
+                ...(description === undefined ? {} : { description }),
+                ...(inputSchema ? { inputSchema: rawInputSchema(inputSchema) } : {}),
+                annotations: { readOnlyHint: readOnly(traversed) }
+            }
+        });
+    });
+    return tools;
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,0BAA0B,EAC1B,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,cAAc,EAAmB,MAAM,kBAAkB,CAAA;AAClE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAElD,OAAO,EAAE,UAAU,EAAE,CAAA;AACrB,OAAO,EAAE,cAAc,IAAI,eAAe,EAAE,CAAA;AAuB5C,6FAA6F;AAC7F,MAAM,CAAC,MAAM,MAAM,GAClB,CAAC,GAAW,EAAmB,EAAE,CACjC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAChB,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAA;AAEtD,MAAM,KAAK,GAAoB,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAC/C,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,KAAK,CAAA;AAEzC;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CACxB,MAAiB,EACjB,OAAO,GAA6D,EAAE;IAEtE,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAG,KAAK,EAAE,GAAG,OAAO,CAAA;IAC5C,MAAM,KAAK,GAAc,EAAE,CAAA;IAC3B,0BAA0B,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,SAAS,EAAE,EAAE;QAC9D,IAAI,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;YAAE,OAAM;QACxC,MAAM,SAAS,GAAG,SAAS,CAAC,QAAwB,CAAA;QACpD,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,CAAA;QACjD,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,OAAO,CAAA;QACtD,KAAK,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,IAAI,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxE,SAAS;YACT,MAAM,EAAE;gBACP,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC;gBACrD,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpE,WAAW,EAAE,EAAE,YAAY,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE;aAClD;SACD,CAAC,CAAA;IACH,CAAC,CAAC,CAAA;IACF,OAAO,KAAK,CAAA;AACb,CAAC","sourcesContent":["import {\n\ttype AnyProcedure,\n\ttype AnyRouter,\n\ttype TraverseContractProcedureCallbackOptions,\n\ttraverseContractProcedures\n} from '@orpc/server'\nimport { rawInputSchema, type ToolSchema } from './json-schema.js'\nimport { readFnMeta, toToolName } from './meta.js'\n\nexport { toToolName }\nexport { rawInputSchema as toolInputSchema }\nexport type { ToolSchema }\n\n/** Picks procedures; also fits oRPC's `OpenAPIHandler({ filter })`. */\nexport type ProcedureFilter = (\n\toptions: TraverseContractProcedureCallbackOptions\n) => boolean\n\nexport type McpTool = {\n\t/** Tool name: the sanitized `fn` name (`user.me` becomes `user-me`). */\n\tname: string\n\tprocedure: AnyProcedure\n\tconfig: {\n\t\tdescription?: string\n\t\t/**\n\t\t * Validates and coerces (date strings to `Date`) but returns the raw\n\t\t * input: pass it to `call(procedure, args)`, which parses it.\n\t\t */\n\t\tinputSchema?: ToolSchema\n\t\tannotations: { readOnlyHint: boolean }\n\t}\n}\n\n/** Procedures whose route has `tag`: `listTools(router, { filter: hasTag('external') })`. */\nexport const hasTag =\n\t(tag: string): ProcedureFilter =>\n\t({ contract }) =>\n\t\tcontract['~orpc'].route.tags?.includes(tag) ?? false\n\nconst isGet: ProcedureFilter = ({ contract }) =>\n\tcontract['~orpc'].route.method === 'GET'\n\n/**\n * MCP tool definitions for the procedures in `router` matching `filter`\n * (default: all). Register them with any MCP server:\n * `server.registerTool(tool.name, tool.config, run)`.\n *\n * `readOnly` sets `readOnlyHint`; it defaults to GET routes, since an MCP\n * client treats anything else as a mutation and may ask for approval.\n */\nexport function listTools(\n\trouter: AnyRouter,\n\toptions: { filter?: ProcedureFilter; readOnly?: ProcedureFilter } = {}\n): McpTool[] {\n\tconst { filter, readOnly = isGet } = options\n\tconst tools: McpTool[] = []\n\ttraverseContractProcedures({ router, path: [] }, (traversed) => {\n\t\tif (filter && !filter(traversed)) return\n\t\tconst procedure = traversed.contract as AnyProcedure\n\t\tconst { inputSchema, route } = procedure['~orpc']\n\t\tconst description = route.description ?? route.summary\n\t\ttools.push({\n\t\t\tname: toToolName(readFnMeta(procedure).name ?? traversed.path.join('.')),\n\t\t\tprocedure,\n\t\t\tconfig: {\n\t\t\t\t...(description === undefined ? {} : { description }),\n\t\t\t\t...(inputSchema ? { inputSchema: rawInputSchema(inputSchema) } : {}),\n\t\t\t\tannotations: { readOnlyHint: readOnly(traversed) }\n\t\t\t}\n\t\t})\n\t})\n\treturn tools\n}\n"]}

package/dist/meta.d.ts

@@ -0,0 +1,35 @@
+import type { AnySchema } from '@orpc/contract';
+import type { AnyProcedure } from '@orpc/server';
+/**
+ * Key under which `fn()` stores its metadata in oRPC's procedure meta
+ * (`.meta()`). Living in oRPC's own meta means it survives everything that
+ * rebuilds a procedure (`os.router()`, `.use()` on a router, lazy routers),
+ * unlike a symbol property on the procedure object.
+ */
+export declare const FN_META_KEY = "orpc-fn";
+export type StoredFnMeta = {
+    name: string;
+    procedure: string;
+    meta: Record<string, unknown>;
+};
+export type FnMeta<TMeta extends object = Record<string, unknown>> = {
+    /** `fn({ name })`, also the OpenAPI operationId; undefined if not made by `fn()`. */
+    name: string | undefined;
+    /** The `procedures` key the route was built from. */
+    procedure: string | undefined;
+    /** The app's typed meta (`createFn({ meta })`) declared on this route. */
+    meta: Partial<TMeta>;
+    /** Route summary, falling back to description, falling back to ''. */
+    description: string;
+    summary: string | undefined;
+    method: string | undefined;
+    path: string | undefined;
+    tags: readonly string[];
+    inputSchema: AnySchema | undefined;
+    outputSchema: AnySchema | undefined;
+};
+/** Read what `fn()` (and oRPC) recorded on a procedure. */
+export declare function readFnMeta<TMeta extends object = Record<string, unknown>>(procedure: AnyProcedure): FnMeta<TMeta>;
+/** Tool-safe name (`a-z0-9-_`): `Users.Get` becomes `users-get`. */
+export declare function toToolName(name: string): string;
+//# sourceMappingURL=meta.d.ts.map

package/dist/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../src/meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,WAAW,YAAY,CAAA;AAEpC,MAAM,MAAM,YAAY,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,MAAM,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IACpE,qFAAqF;IACrF,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,qDAAqD;IACrD,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,0EAA0E;IAC1E,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;IACpB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACxB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,WAAW,EAAE,SAAS,GAAG,SAAS,CAAA;IAClC,YAAY,EAAE,SAAS,GAAG,SAAS,CAAA;CACnC,CAAA;AAeD,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,KAAK,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxE,SAAS,EAAE,YAAY,GACrB,MAAM,CAAC,KAAK,CAAC,CAgBf;AAED,oEAAoE;AACpE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/meta.js

@@ -0,0 +1,30 @@
+/**
+ * Key under which `fn()` stores its metadata in oRPC's procedure meta
+ * (`.meta()`). Living in oRPC's own meta means it survives everything that
+ * rebuilds a procedure (`os.router()`, `.use()` on a router, lazy routers),
+ * unlike a symbol property on the procedure object.
+ */
+export const FN_META_KEY = 'orpc-fn';
+/** Read what `fn()` (and oRPC) recorded on a procedure. */
+export function readFnMeta(procedure) {
+    const def = procedure['~orpc'] ?? {};
+    const stored = def.meta?.[FN_META_KEY];
+    const route = def.route ?? {};
+    return {
+        name: stored?.name,
+        procedure: stored?.procedure,
+        meta: (stored?.meta ?? {}),
+        description: route.summary ?? route.description ?? '',
+        summary: route.summary,
+        method: route.method,
+        path: route.path,
+        tags: route.tags ?? [],
+        inputSchema: def.inputSchema,
+        outputSchema: def.outputSchema
+    };
+}
+/** Tool-safe name (`a-z0-9-_`): `Users.Get` becomes `users-get`. */
+export function toToolName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9-_]/g, '-');
+}
+//# sourceMappingURL=meta.js.map

package/dist/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../src/meta.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAA;AAsCpC,2DAA2D;AAC3D,MAAM,UAAU,UAAU,CACzB,SAAuB;IAEvB,MAAM,GAAG,GAAI,SAA+C,CAAC,OAAO,CAAC,IAAI,EAAE,CAAA;IAC3E,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,CAA6B,CAAA;IAClE,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,EAAE,CAAA;IAC7B,OAAO;QACN,IAAI,EAAE,MAAM,EAAE,IAAI;QAClB,SAAS,EAAE,MAAM,EAAE,SAAS;QAC5B,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,IAAI,EAAE,CAAmB;QAC5C,WAAW,EAAE,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,WAAW,IAAI,EAAE;QACrD,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;QACtB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,YAAY,EAAE,GAAG,CAAC,YAAY;KAC9B,CAAA;AACF,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,UAAU,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,CAAA;AACvD,CAAC","sourcesContent":["import type { AnySchema } from '@orpc/contract'\nimport type { AnyProcedure } from '@orpc/server'\n\n/**\n * Key under which `fn()` stores its metadata in oRPC's procedure meta\n * (`.meta()`). Living in oRPC's own meta means it survives everything that\n * rebuilds a procedure (`os.router()`, `.use()` on a router, lazy routers),\n * unlike a symbol property on the procedure object.\n */\nexport const FN_META_KEY = 'orpc-fn'\n\nexport type StoredFnMeta = {\n\tname: string\n\tprocedure: string\n\tmeta: Record<string, unknown>\n}\n\nexport type FnMeta<TMeta extends object = Record<string, unknown>> = {\n\t/** `fn({ name })`, also the OpenAPI operationId; undefined if not made by `fn()`. */\n\tname: string | undefined\n\t/** The `procedures` key the route was built from. */\n\tprocedure: string | undefined\n\t/** The app's typed meta (`createFn({ meta })`) declared on this route. */\n\tmeta: Partial<TMeta>\n\t/** Route summary, falling back to description, falling back to ''. */\n\tdescription: string\n\tsummary: string | undefined\n\tmethod: string | undefined\n\tpath: string | undefined\n\ttags: readonly string[]\n\tinputSchema: AnySchema | undefined\n\toutputSchema: AnySchema | undefined\n}\n\ntype ProcedureDefinition = {\n\tmeta?: Record<string, unknown>\n\troute?: {\n\t\tsummary?: string\n\t\tdescription?: string\n\t\tmethod?: string\n\t\tpath?: string\n\t\ttags?: readonly string[]\n\t}\n\tinputSchema?: AnySchema\n\toutputSchema?: AnySchema\n}\n\n/** Read what `fn()` (and oRPC) recorded on a procedure. */\nexport function readFnMeta<TMeta extends object = Record<string, unknown>>(\n\tprocedure: AnyProcedure\n): FnMeta<TMeta> {\n\tconst def = (procedure as { '~orpc'?: ProcedureDefinition })['~orpc'] ?? {}\n\tconst stored = def.meta?.[FN_META_KEY] as StoredFnMeta | undefined\n\tconst route = def.route ?? {}\n\treturn {\n\t\tname: stored?.name,\n\t\tprocedure: stored?.procedure,\n\t\tmeta: (stored?.meta ?? {}) as Partial<TMeta>,\n\t\tdescription: route.summary ?? route.description ?? '',\n\t\tsummary: route.summary,\n\t\tmethod: route.method,\n\t\tpath: route.path,\n\t\ttags: route.tags ?? [],\n\t\tinputSchema: def.inputSchema,\n\t\toutputSchema: def.outputSchema\n\t}\n}\n\n/** Tool-safe name (`a-z0-9-_`): `Users.Get` becomes `users-get`. */\nexport function toToolName(name: string): string {\n\treturn name.toLowerCase().replace(/[^a-z0-9-_]/g, '-')\n}\n"]}

package/dist/otel.d.ts

@@ -0,0 +1,66 @@
+/** Attribute values accepted by OpenTelemetry spans. */
+export type AttributeValue = string | number | boolean;
+/** The part of an OpenTelemetry `Span` this package uses. */
+export interface SpanLike {
+    setAttribute(key: string, value: AttributeValue): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    recordException(exception: Error): unknown;
+    end(): unknown;
+}
+type SpanOptionsLike = {
+    kind?: number;
+    attributes?: Record<string, AttributeValue>;
+};
+interface TracerLike<TSpan> {
+    startActiveSpan<F extends (span: TSpan) => unknown>(name: string, options: SpanOptionsLike, fn: F): ReturnType<F>;
+    startSpan(name: string, options?: SpanOptionsLike): TSpan;
+}
+/**
+ * The part of `@opentelemetry/api` this package uses. Pass the module itself:
+ * `import * as otel from '@opentelemetry/api'` then `createFn({ otel })`.
+ * Without it no spans are created and handlers receive `span: undefined`.
+ */
+export interface OtelApiLike<TSpan extends SpanLike = SpanLike> {
+    trace: {
+        getTracer(name: string): TracerLike<TSpan>;
+    };
+    SpanStatusCode: {
+        OK: number;
+        ERROR: number;
+    };
+    SpanKind: {
+        INTERNAL: number;
+        SERVER: number;
+        PRODUCER: number;
+    };
+    /** Restores a span's context for each step of a stream it returned. */
+    context: {
+        active(): unknown;
+        with<T>(context: never, fn: () => T): T;
+    };
+}
+/** The span type of an OpenTelemetry API, or `SpanLike` when absent. */
+export type SpanOf<TOtel> = TOtel extends OtelApiLike<infer TSpan> ? TSpan : SpanLike;
+/** Called once when a span's work is done, before the span ends. */
+export type OnSettled = (span: SpanLike | undefined, ...error: [] | [unknown]) => void;
+export type Tracing = {
+    /**
+     * Run `fn` inside an active span: OK when it resolves, ERROR when it throws,
+     * ended either way. When `fn` resolves to a stream, the span stays open -
+     * and active for each step of the stream - until the stream ends.
+     * `onSettled` runs once at that point, before the span ends. Without
+     * OpenTelemetry `span` is undefined and `onSettled` still runs.
+     */
+    inSpan<T>(name: string, kind: 'INTERNAL' | 'SERVER' | 'PRODUCER', fn: (span: SpanLike | undefined) => Promise<T>, onSettled?: OnSettled): Promise<T>;
+    /** Start a span that the caller ends with `end` (long-lived streams). */
+    startSpan(name: string, kind: 'SERVER', attributes: Record<string, AttributeValue>): SpanLike | undefined;
+    /** Set OK, or ERROR with `error`, and end the span. */
+    end(span: SpanLike | undefined, error?: unknown): void;
+};
+export declare function createTracing(otel: OtelApiLike | undefined): Tracing;
+export declare function errorMessageOf(error: unknown): string;
+export {};
+//# sourceMappingURL=otel.d.ts.map

package/dist/otel.d.ts.map

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

package/dist/otel.js

@@ -0,0 +1,63 @@
+import { isAsyncIteratorObject, onStreamEnd } from './stream.js';
+export function createTracing(otel) {
+    const tracer = otel?.trace.getTracer('orpc-fn');
+    const end = (span, ...error) => {
+        if (!span || !otel)
+            return;
+        if (error.length === 0) {
+            span.setStatus({ code: otel.SpanStatusCode.OK });
+        }
+        else {
+            span.setStatus({
+                code: otel.SpanStatusCode.ERROR,
+                message: errorMessageOf(error[0])
+            });
+            if (error[0] instanceof Error)
+                span.recordException(error[0]);
+        }
+        span.end();
+    };
+    return {
+        inSpan(name, kind, fn, onSettled) {
+            const settle = (span, ...error) => {
+                try {
+                    onSettled?.(span, ...error);
+                }
+                finally {
+                    end(span, ...error);
+                }
+            };
+            const run = async (span, scope) => {
+                let result;
+                try {
+                    result = await fn(span);
+                }
+                catch (error) {
+                    settle(span, error);
+                    throw error;
+                }
+                if (isAsyncIteratorObject(result)) {
+                    return onStreamEnd(result, (...error) => settle(span, ...error), scope);
+                }
+                settle(span);
+                return result;
+            };
+            if (!tracer || !otel)
+                return run(undefined);
+            return tracer.startActiveSpan(name, { kind: otel.SpanKind[kind] }, (span) => {
+                const active = otel.context.active();
+                return run(span, (step) => otel.context.with(active, step));
+            });
+        },
+        startSpan(name, kind, attributes) {
+            if (!tracer || !otel)
+                return undefined;
+            return tracer.startSpan(name, { kind: otel.SpanKind[kind], attributes });
+        },
+        end
+    };
+}
+export function errorMessageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=otel.js.map

package/dist/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.js","sourceRoot":"","sources":["../src/otel.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\tisAsyncIteratorObject,\n\tonStreamEnd,\n\ttype StreamScope\n} from './stream.js'\n\n/** Attribute values accepted by OpenTelemetry spans. */\nexport type AttributeValue = string | number | boolean\n\n/** The part of an OpenTelemetry `Span` this package uses. */\nexport interface SpanLike {\n\tsetAttribute(key: string, value: AttributeValue): unknown\n\tsetStatus(status: { code: number; message?: string }): unknown\n\trecordException(exception: Error): unknown\n\tend(): unknown\n}\n\ntype SpanOptionsLike = {\n\tkind?: number\n\tattributes?: Record<string, AttributeValue>\n}\n\ninterface TracerLike<TSpan> {\n\tstartActiveSpan<F extends (span: TSpan) => unknown>(\n\t\tname: string,\n\t\toptions: SpanOptionsLike,\n\t\tfn: F\n\t): ReturnType<F>\n\tstartSpan(name: string, options?: SpanOptionsLike): TSpan\n}\n\n/**\n * The part of `@opentelemetry/api` this package uses. Pass the module itself:\n * `import * as otel from '@opentelemetry/api'` then `createFn({ otel })`.\n * Without it no spans are created and handlers receive `span: undefined`.\n */\nexport interface OtelApiLike<TSpan extends SpanLike = SpanLike> {\n\ttrace: { getTracer(name: string): TracerLike<TSpan> }\n\tSpanStatusCode: { OK: number; ERROR: number }\n\tSpanKind: {\n\t\tINTERNAL: number\n\t\tSERVER: number\n\t\tPRODUCER: number\n\t}\n\t/** Restores a span's context for each step of a stream it returned. */\n\tcontext: {\n\t\tactive(): unknown\n\t\twith<T>(context: never, fn: () => T): T\n\t}\n}\n\n/** The span type of an OpenTelemetry API, or `SpanLike` when absent. */\nexport type SpanOf<TOtel> =\n\tTOtel extends OtelApiLike<infer TSpan> ? TSpan : SpanLike\n\n/** Called once when a span's work is done, before the span ends. */\nexport type OnSettled = (\n\tspan: SpanLike | undefined,\n\t...error: [] | [unknown]\n) => void\n\nexport type Tracing = {\n\t/**\n\t * Run `fn` inside an active span: OK when it resolves, ERROR when it throws,\n\t * ended either way. When `fn` resolves to a stream, the span stays open -\n\t * and active for each step of the stream - until the stream ends.\n\t * `onSettled` runs once at that point, before the span ends. Without\n\t * OpenTelemetry `span` is undefined and `onSettled` still runs.\n\t */\n\tinSpan<T>(\n\t\tname: string,\n\t\tkind: 'INTERNAL' | 'SERVER' | 'PRODUCER',\n\t\tfn: (span: SpanLike | undefined) => Promise<T>,\n\t\tonSettled?: OnSettled\n\t): Promise<T>\n\t/** Start a span that the caller ends with `end` (long-lived streams). */\n\tstartSpan(\n\t\tname: string,\n\t\tkind: 'SERVER',\n\t\tattributes: Record<string, AttributeValue>\n\t): SpanLike | undefined\n\t/** Set OK, or ERROR with `error`, and end the span. */\n\tend(span: SpanLike | undefined, error?: unknown): void\n}\n\nexport function createTracing(otel: OtelApiLike | undefined): Tracing {\n\tconst tracer = otel?.trace.getTracer('orpc-fn')\n\tconst end: Tracing['end'] = (span, ...error) => {\n\t\tif (!span || !otel) return\n\t\tif (error.length === 0) {\n\t\t\tspan.setStatus({ code: otel.SpanStatusCode.OK })\n\t\t} else {\n\t\t\tspan.setStatus({\n\t\t\t\tcode: otel.SpanStatusCode.ERROR,\n\t\t\t\tmessage: errorMessageOf(error[0])\n\t\t\t})\n\t\t\tif (error[0] instanceof Error) span.recordException(error[0])\n\t\t}\n\t\tspan.end()\n\t}\n\treturn {\n\t\tinSpan(name, kind, fn, onSettled) {\n\t\t\tconst settle = (span: SpanLike | undefined, ...error: [] | [unknown]) => {\n\t\t\t\ttry {\n\t\t\t\t\tonSettled?.(span, ...error)\n\t\t\t\t} finally {\n\t\t\t\t\tend(span, ...error)\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst run = async (\n\t\t\t\tspan: SpanLike | undefined,\n\t\t\t\tscope?: StreamScope\n\t\t\t): Promise<Awaited<ReturnType<typeof fn>>> => {\n\t\t\t\tlet result: Awaited<ReturnType<typeof fn>>\n\t\t\t\ttry {\n\t\t\t\t\tresult = await fn(span)\n\t\t\t\t} catch (error) {\n\t\t\t\t\tsettle(span, error)\n\t\t\t\t\tthrow error\n\t\t\t\t}\n\t\t\t\tif (isAsyncIteratorObject(result)) {\n\t\t\t\t\treturn onStreamEnd(\n\t\t\t\t\t\tresult,\n\t\t\t\t\t\t(...error) => settle(span, ...error),\n\t\t\t\t\t\tscope\n\t\t\t\t\t) as typeof result\n\t\t\t\t}\n\t\t\t\tsettle(span)\n\t\t\t\treturn result\n\t\t\t}\n\t\t\tif (!tracer || !otel) return run(undefined)\n\t\t\treturn tracer.startActiveSpan(\n\t\t\t\tname,\n\t\t\t\t{ kind: otel.SpanKind[kind] },\n\t\t\t\t(span) => {\n\t\t\t\t\tconst active = otel.context.active()\n\t\t\t\t\treturn run(span, (step) => otel.context.with(active as never, step))\n\t\t\t\t}\n\t\t\t)\n\t\t},\n\t\tstartSpan(name, kind, attributes) {\n\t\t\tif (!tracer || !otel) return undefined\n\t\t\treturn tracer.startSpan(name, { kind: otel.SpanKind[kind], attributes })\n\t\t},\n\t\tend\n\t}\n}\n\nexport function errorMessageOf(error: unknown): string {\n\treturn error instanceof Error ? error.message : String(error)\n}\n"]}

package/dist/router.d.ts

@@ -0,0 +1,13 @@
+import type { AnyRouter } from '@orpc/server';
+/**
+ * Creates a router object from routes or nested routers.
+ * Simply returns the routes as a const object for type inference.
+ *
+ * @example
+ * ```ts
+ * const items = createRouter({ getItem, updateItem })
+ * export const api = createRouter({ metabase, items })
+ * ```
+ */
+export declare function createRouter<T extends AnyRouter>(routes: T): Readonly<T>;
+//# sourceMappingURL=router.d.ts.map

package/dist/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE7C;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAExE"}

package/dist/router.js

@@ -0,0 +1,14 @@
+/**
+ * Creates a router object from routes or nested routers.
+ * Simply returns the routes as a const object for type inference.
+ *
+ * @example
+ * ```ts
+ * const items = createRouter({ getItem, updateItem })
+ * export const api = createRouter({ metabase, items })
+ * ```
+ */
+export function createRouter(routes) {
+    return routes;
+}
+//# sourceMappingURL=router.js.map

package/dist/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../src/router.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAsB,MAAS;IAC1D,OAAO,MAAM,CAAA;AACd,CAAC","sourcesContent":["import type { AnyRouter } from '@orpc/server'\n\n/**\n * Creates a router object from routes or nested routers.\n * Simply returns the routes as a const object for type inference.\n *\n * @example\n * ```ts\n * const items = createRouter({ getItem, updateItem })\n * export const api = createRouter({ metabase, items })\n * ```\n */\nexport function createRouter<T extends AnyRouter>(routes: T): Readonly<T> {\n\treturn routes\n}\n"]}

package/dist/stream.d.ts

@@ -0,0 +1,13 @@
+/** A value oRPC streams to the client (an async generator or iterator). */
+export declare function isAsyncIteratorObject(value: unknown): value is AsyncIterator<unknown> & AsyncIterable<unknown>;
+/** Runs one step of a stream inside some context (e.g. its tracing span). */
+export type StreamScope = <T>(step: () => T) => T;
+/**
+ * Wraps a stream so `finish` runs once when it ends: after the last item,
+ * when it throws (with the error), or when the consumer stops early with
+ * `return()` - also before the first `next()`, which a plain async generator
+ * wrapper would miss. With `scope`, every `next`/`return`/`throw` runs inside
+ * it: a generator's body runs on those calls, long after it was created.
+ */
+export declare function onStreamEnd<T>(stream: AsyncIterator<T> & AsyncIterable<T>, finish: (...error: [] | [unknown]) => void, scope?: StreamScope): AsyncIterator<T> & AsyncIterable<T>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,OAAO,GACZ,KAAK,IAAI,aAAa,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,CAQ1D;AAED,6EAA6E;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;AAEjD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC5B,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,EAC3C,MAAM,EAAE,CAAC,GAAG,KAAK,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAC1C,KAAK,GAAE,WAA8B,GACnC,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CA0BrC"}

package/dist/stream.js

@@ -0,0 +1,44 @@
+/** A value oRPC streams to the client (an async generator or iterator). */
+export function isAsyncIteratorObject(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value[Symbol.asyncIterator] ===
+            'function' &&
+        typeof value.next === 'function');
+}
+/**
+ * Wraps a stream so `finish` runs once when it ends: after the last item,
+ * when it throws (with the error), or when the consumer stops early with
+ * `return()` - also before the first `next()`, which a plain async generator
+ * wrapper would miss. With `scope`, every `next`/`return`/`throw` runs inside
+ * it: a generator's body runs on those calls, long after it was created.
+ */
+export function onStreamEnd(stream, finish, scope = (step) => step()) {
+    let finished = false;
+    const done = (...error) => {
+        if (finished)
+            return;
+        finished = true;
+        finish(...error);
+    };
+    const settle = async (step) => {
+        try {
+            const result = await step();
+            if (!result || result.done)
+                done();
+            return result ?? { done: true, value: undefined };
+        }
+        catch (error) {
+            done(error);
+            throw error;
+        }
+    };
+    const wrapped = {
+        next: (...args) => settle(() => scope(() => stream.next(...args))),
+        return: (value) => settle(() => scope(() => stream.return?.(value))).finally(() => done()),
+        throw: (error) => settle(() => scope(() => stream.throw?.(error) ?? Promise.reject(error))),
+        [Symbol.asyncIterator]: () => wrapped
+    };
+    return wrapped;
+}
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,UAAU,qBAAqB,CACpC,KAAc;IAEd,OAAO,CACN,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAgC,CAAC,MAAM,CAAC,aAAa,CAAC;YAC7D,UAAU;QACX,OAAQ,KAAgC,CAAC,IAAI,KAAK,UAAU,CAC5D,CAAA;AACF,CAAC;AAKD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAC1B,MAA2C,EAC3C,MAA0C,EAC1C,KAAK,GAAgB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE;IAErC,IAAI,QAAQ,GAAG,KAAK,CAAA;IACpB,MAAM,IAAI,GAAG,CAAC,GAAG,KAAqB,EAAE,EAAE;QACzC,IAAI,QAAQ;YAAE,OAAM;QACpB,QAAQ,GAAG,IAAI,CAAA;QACf,MAAM,CAAC,GAAG,KAAK,CAAC,CAAA;IACjB,CAAC,CAAA;IACD,MAAM,MAAM,GAAG,KAAK,EAAE,IAAkD,EAAE,EAAE;QAC3E,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAA;YAC3B,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI;gBAAE,IAAI,EAAE,CAAA;YAClC,OAAO,MAAM,IAAI,EAAE,IAAI,EAAE,IAAa,EAAE,KAAK,EAAE,SAAS,EAAE,CAAA;QAC3D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,CAAC,KAAK,CAAC,CAAA;YACX,MAAM,KAAK,CAAA;QACZ,CAAC;IACF,CAAC,CAAA;IACD,MAAM,OAAO,GAAwC;QACpD,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;QAClE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;QACxE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAChB,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1E,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO;KACrC,CAAA;IACD,OAAO,OAAO,CAAA;AACf,CAAC","sourcesContent":["/** A value oRPC streams to the client (an async generator or iterator). */\nexport function isAsyncIteratorObject(\n\tvalue: unknown\n): value is AsyncIterator<unknown> & AsyncIterable<unknown> {\n\treturn (\n\t\ttypeof value === 'object' &&\n\t\tvalue !== null &&\n\t\ttypeof (value as AsyncIterable<unknown>)[Symbol.asyncIterator] ===\n\t\t\t'function' &&\n\t\ttypeof (value as AsyncIterator<unknown>).next === 'function'\n\t)\n}\n\n/** Runs one step of a stream inside some context (e.g. its tracing span). */\nexport type StreamScope = <T>(step: () => T) => T\n\n/**\n * Wraps a stream so `finish` runs once when it ends: after the last item,\n * when it throws (with the error), or when the consumer stops early with\n * `return()` - also before the first `next()`, which a plain async generator\n * wrapper would miss. With `scope`, every `next`/`return`/`throw` runs inside\n * it: a generator's body runs on those calls, long after it was created.\n */\nexport function onStreamEnd<T>(\n\tstream: AsyncIterator<T> & AsyncIterable<T>,\n\tfinish: (...error: [] | [unknown]) => void,\n\tscope: StreamScope = (step) => step()\n): AsyncIterator<T> & AsyncIterable<T> {\n\tlet finished = false\n\tconst done = (...error: [] | [unknown]) => {\n\t\tif (finished) return\n\t\tfinished = true\n\t\tfinish(...error)\n\t}\n\tconst settle = async (step: () => Promise<IteratorResult<T>> | undefined) => {\n\t\ttry {\n\t\t\tconst result = await step()\n\t\t\tif (!result || result.done) done()\n\t\t\treturn result ?? { done: true as const, value: undefined }\n\t\t} catch (error) {\n\t\t\tdone(error)\n\t\t\tthrow error\n\t\t}\n\t}\n\tconst wrapped: AsyncIterator<T> & AsyncIterable<T> = {\n\t\tnext: (...args) => settle(() => scope(() => stream.next(...args))),\n\t\treturn: (value) =>\n\t\t\tsettle(() => scope(() => stream.return?.(value))).finally(() => done()),\n\t\tthrow: (error) =>\n\t\t\tsettle(() => scope(() => stream.throw?.(error) ?? Promise.reject(error))),\n\t\t[Symbol.asyncIterator]: () => wrapped\n\t}\n\treturn wrapped\n}\n"]}

package/dist/types.d.ts

@@ -0,0 +1,196 @@
+import type { AnySchema, ErrorMap, InferSchemaInput, InferSchemaOutput, Meta, Schema } from '@orpc/contract';
+import type { AnyProcedure, DecoratedProcedure, Procedure, Route } from '@orpc/server';
+import type { ZodType, z } from 'zod';
+import type { BoundCall } from './bound-call.js';
+import type { FnLogger } from './logger.js';
+import type { SpanLike } from './otel.js';
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * An oRPC builder without input or output schema: `os`, `os.$context<T>()`,
+ * `os.use(...)`. A schema set on the builder is rejected by `createFn`; set it
+ * on the route instead.
+ */
+export type BuilderLike = {
+    route(route: any): unknown;
+    meta(meta: any): unknown;
+    input(schema: any): unknown;
+    output(schema: any): unknown;
+    handler(handler: any): Procedure<any, any, any, any, any, any>;
+};
+/** Input a procedure is called with (before its input schema runs). */
+export type ProcedureInput<T> = T extends Procedure<infer _TInitial, infer _TCurrent, infer TInputSchema extends AnySchema, infer _TOut, infer _TErrors, infer _TMeta> ? InferSchemaInput<TInputSchema> : unknown;
+/** What a procedure resolves to (after its output schema runs). */
+export type ProcedureOutput<T> = T extends Procedure<infer _TInitial, infer _TCurrent, infer _TIn, infer TOutputSchema extends AnySchema, infer _TErrors, infer _TMeta> ? InferSchemaOutput<TOutputSchema> : unknown;
+/** Context a procedure must be called with. */
+export type ProcedureContext<T> = T extends Procedure<infer TContext, infer _TCurrent, infer _TIn, infer _TOut, infer _TErrors, infer _TMeta> ? TContext : never;
+/** `Omit` that keeps each member of a union (handler params narrow by discriminant). */
+export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/** `fn()` options passed to oRPC's `.route()`; `RouteConfig` is derived from it. */
+export declare const ROUTE_OPTION_KEYS: readonly ["path", "method", "summary", "description", "deprecated", "successStatus", "successDescription", "inputStructure", "outputStructure", "tags"];
+/**
+ * `fn()` option names owned by the route itself. Guard and meta keys must not
+ * reuse them: such an option would be read as the route option and the guard
+ * would never run.
+ */
+export declare const RESERVED_OPTION_KEYS: readonly ["path", "method", "summary", "description", "deprecated", "successStatus", "successDescription", "inputStructure", "outputStructure", "tags", "name", "procedure", "input", "output", "handler", "live", "operationId"];
+export type ReservedOptionKey = (typeof RESERVED_OPTION_KEYS)[number];
+/** @internal Builds one route from a `procedures` builder; shared by `fn` and `createPubSub`. */
+export type BuildProcedure = (options: {
+    name: string;
+    procedure: string | undefined;
+    route: Record<string, unknown>;
+    meta: Record<string, unknown>;
+    input?: AnySchema | undefined;
+    output?: AnySchema | undefined;
+    handler: (options: {
+        input: unknown;
+        context: Record<string, unknown>;
+        signal?: AbortSignal;
+    }) => unknown;
+}) => AnyProcedure;
+/** Turns every key of `T` found in `K` into a readable type error. */
+export type RejectKeys<T, K extends PropertyKey, TMessage extends string> = {
+    [P in Extract<keyof T, K>]: TMessage;
+};
+/**
+ * Handler extras must have known keys: an index signature would claim every
+ * handler param. Intersected into `createFn`'s options to reject it.
+ */
+export type FiniteExtras<T> = string extends keyof T ? {
+    extras: 'orpc-fn: extras need known keys, not an index signature';
+} : number extends keyof T ? {
+    extras: 'orpc-fn: extras need known keys, not an index signature';
+} : unknown;
+type ProcedureOf<TBuilder> = TBuilder extends {
+    handler(handler: never): infer TProcedure;
+} ? TProcedure : never;
+/** Context a route built from this builder is called with. */
+export type InitialContextOf<TBuilder> = ProcedureContext<ProcedureOf<TBuilder>>;
+/** Context the handler sees, after the builder's middleware. */
+export type CurrentContextOf<TBuilder> = ProcedureOf<TBuilder> extends Procedure<infer _TInitial, infer TContext, infer _TIn, infer _TOut, infer _TErrors, infer _TMeta> ? TContext : never;
+type ErrorMapOf<TBuilder> = ProcedureOf<TBuilder> extends {
+    '~orpc': {
+        errorMap: infer T extends ErrorMap;
+    };
+} ? T : ErrorMap;
+type MetaOf<TBuilder> = ProcedureOf<TBuilder> extends {
+    '~orpc': {
+        meta: infer T extends Meta;
+    };
+} ? T : Meta;
+/**
+ * Everything `createFn` inferred from its options. Route types read from it;
+ * apps rarely spell it out.
+ */
+export type FnDefinition = {
+    procedures: Record<string, BuilderLike>;
+    default: string;
+    extras: object;
+    guards: object;
+    meta: object;
+    tag: string;
+    span: SpanLike;
+    logger: FnLogger;
+};
+export type ProcedureKey<TDef extends FnDefinition> = keyof TDef['procedures'] & string;
+/** Context the handler of a `procedure: TKey` route receives. */
+export type FnContext<TDef extends FnDefinition, TKey extends ProcedureKey<TDef>> = CurrentContextOf<TDef['procedures'][TKey]>;
+/** Union of every procedure's handler context: what guards and extras see. */
+export type AnyFnContext<TDef extends FnDefinition> = {
+    [K in ProcedureKey<TDef>]: FnContext<TDef, K>;
+}[ProcedureKey<TDef>];
+export type GuardParams<TContext, TMeta> = {
+    context: TContext;
+    input: unknown;
+    /** Route name (operationId). */
+    name: string;
+    /** Procedures key the route was built from. */
+    procedure: string;
+    meta: Partial<TMeta>;
+    signal: AbortSignal | undefined;
+};
+/**
+ * A check run before the handler. Its first parameter becomes an option on
+ * `fn({...})`; the guard runs only on routes that set it. Throw (usually an
+ * `ORPCError`) to refuse the call.
+ */
+export type Guard<TValue, TParams> = (value: TValue, params: TParams) => unknown;
+export type GuardOptions<TGuards> = {
+    [K in keyof TGuards]?: TGuards[K] extends (value: infer TValue, params: never) => unknown ? TValue : never;
+};
+export type HandlerParams<TDef extends FnDefinition, TInput, TKey extends ProcedureKey<TDef>> = DistributiveOmit<TDef['extras'], 'input' | 'context' | 'call' | 'signal' | 'span' | 'logger'> & {
+    input: TInput;
+    context: FnContext<TDef, TKey>;
+    /** Calls another procedure with this context and signal, in a child span. */
+    call: BoundCall<FnContext<TDef, TKey>>;
+    /** Cancellation is inherited by nested calls; pass to interruptible I/O. */
+    signal: AbortSignal | undefined;
+    /** Active OpenTelemetry span, undefined when `createFn({ otel })` is not set. */
+    span: TDef['span'] | undefined;
+    logger: TDef['logger'];
+};
+/** Route options shared by every `fn()` overload. */
+export type RouteConfig<TTag extends string = string> = Pick<Route, Exclude<(typeof ROUTE_OPTION_KEYS)[number], 'tags'>> & {
+    /** Required. Becomes the OpenAPI operationId and the span name (e.g. 'user.create'). */
+    name: string;
+    tags?: TTag[];
+};
+export type FnRouteOptions<TDef extends FnDefinition, TKey extends ProcedureKey<TDef>> = RouteConfig<TDef['tag']> & GuardOptions<TDef['guards']> & TDef['meta'] & ProcedureOption<TDef, TKey>;
+/**
+ * Which `createFn({ procedures })` builder a route uses. Optional when
+ * `createFn` has a `default`; required on every route when it has none.
+ */
+export type ProcedureOption<TDef extends FnDefinition, TKey extends ProcedureKey<TDef>> = [TDef['default']] extends [never] ? {
+    procedure: TKey;
+} : {
+    procedure?: TKey;
+};
+export type FnProcedure<TDef extends FnDefinition, TKey extends ProcedureKey<TDef>, TInputSchema extends Schema<unknown, unknown>, TOutputSchema extends Schema<unknown, unknown>> = DecoratedProcedure<InitialContextOf<TDef['procedures'][TKey]>, FnContext<TDef, TKey>, TInputSchema, TOutputSchema, ErrorMapOf<TDef['procedures'][TKey]>, MetaOf<TDef['procedures'][TKey]>>;
+type InputOf<T> = [T] extends [ZodType] ? z.output<T> : unknown;
+type ReturnOf<TOut, TReturn> = [TOut] extends [ZodType] ? z.input<TOut> : TReturn;
+/** `fn()`: four overloads for input/output schema × inferred. */
+export interface Fn<TDef extends FnDefinition> {
+    <TInput extends ZodType, TOut extends ZodType, TKey extends ProcedureKey<TDef> = TDef['default']>(options: {
+        input: TInput;
+        output: TOut;
+        handler: (params: HandlerParams<TDef, z.output<TInput>, NoInfer<TKey>>) => MaybePromise<z.input<TOut>>;
+    } & FnRouteOptions<TDef, TKey>): FnProcedure<TDef, TKey, TInput, TOut>;
+    <TInput extends ZodType, TReturn, TKey extends ProcedureKey<TDef> = TDef['default']>(options: {
+        input: TInput;
+        output?: undefined;
+        handler: (params: HandlerParams<TDef, z.output<TInput>, NoInfer<TKey>>) => MaybePromise<TReturn>;
+    } & FnRouteOptions<TDef, TKey>): FnProcedure<TDef, TKey, TInput, Schema<TReturn, TReturn>>;
+    <TOut extends ZodType, TKey extends ProcedureKey<TDef> = TDef['default']>(options: {
+        input?: undefined;
+        output: TOut;
+        handler: (params: HandlerParams<TDef, unknown, NoInfer<TKey>>) => MaybePromise<z.input<TOut>>;
+    } & FnRouteOptions<TDef, TKey>): FnProcedure<TDef, TKey, Schema<unknown, unknown>, TOut>;
+    <TReturn, TKey extends ProcedureKey<TDef> = TDef['default']>(options: {
+        input?: undefined;
+        output?: undefined;
+        handler: (params: HandlerParams<TDef, unknown, NoInfer<TKey>>) => MaybePromise<TReturn>;
+    } & FnRouteOptions<TDef, TKey>): FnProcedure<TDef, TKey, Schema<unknown, unknown>, Schema<TReturn, TReturn>>;
+    <TReturn, TInput extends ZodType | undefined = undefined, TOut extends ZodType | undefined = undefined, TKey extends ProcedureKey<TDef> = TDef['default']>(options: {
+        input?: TInput;
+        output?: TOut;
+        handler: (params: HandlerParams<TDef, InputOf<TInput>, NoInfer<TKey>>) => MaybePromise<ReturnOf<TOut, TReturn>>;
+    } & FnRouteOptions<TDef, TKey>): FnProcedure<TDef, TKey, [
+        TInput
+    ] extends [ZodType] ? TInput : Schema<unknown, unknown>, [
+        TOut
+    ] extends [ZodType] ? TOut : Schema<TReturn, TReturn>>;
+}
+/** What `fn.completed` reports, and what `onCompleted` receives. */
+export type FnCompletedEvent<TContext = unknown, TSpan = SpanLike> = {
+    name: string;
+    procedure: string;
+    durationMs: number;
+    success: boolean;
+    error: unknown;
+    input: unknown;
+    context: TContext;
+    span: TSpan | undefined;
+    meta: Record<string, unknown>;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map