@zudojs/api 1.1.1 → 1.2.1

package/dist/api/bindings/fetch/apiFetch.handler.d.ts

@@ -0,0 +1,35 @@
+import type { Serializer } from "@zudojs/serialization";
+import type { APIBindingOptions, APIOperationSource } from "../shared/apiBinding.type.js";
+/** Default limit on a request body read by the fetch binding (1 MiB). */
+export declare const DEFAULT_API_MAX_BODY_BYTES: number;
+/**
+ * Options for {@link createApiFetchHandler}. `state` receives the
+ * `Request` — derive the authenticated principal there.
+ */
+export interface APIFetchHandlerOptions extends APIBindingOptions<Request> {
+    /** Prefix for every route, e.g. `"/api"`. */
+    readonly basePath?: string;
+    /** Largest JSON request body accepted, in bytes. Defaults to 1 MiB. */
+    readonly maxBodyBytes?: number;
+    /** Response/request serializer. Defaults to `@zudojs/serialization` JSON. */
+    readonly serializer?: Serializer<unknown, string>;
+}
+/**
+ * Exposes operations as a web-standard handler,
+ * `(request: Request) => Promise<Response>`, that any Fetch API server
+ * (`@zudojs/http`, Bun, Deno, edge runtimes, Node adapters) can mount.
+ *
+ * Routes come from each operation's `metadata.http` (default
+ * `POST /<name>`), input from the query string or JSON body plus path
+ * parameters, and every response body is an {@link APIWireResult}:
+ * `{ ok: true, data }` with 200, or `{ ok: false, error }` with the error's
+ * status (422 validation, 404 unknown route, 405 wrong method, 413/415 bad
+ * body, 500 internal). Internal messages and stack traces never reach the
+ * response. The call runs under `request.signal`, so a client that
+ * disconnects cancels it; the request id comes from `x-request-id` when
+ * safe and is echoed back in the same header.
+ *
+ * @throws {TypeError | RangeError} at creation for invalid or conflicting routes.
+ */
+export declare function createApiFetchHandler(operations: APIOperationSource, options?: APIFetchHandlerOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=apiFetch.handler.d.ts.map

package/dist/api/bindings/fetch/apiFetch.handler.js

@@ -0,0 +1,99 @@
+import { createSerializer } from "@zudojs/serialization";
+import { createOperationRunner } from "../shared/apiBinding.helper.js";
+import { toApiWireResult } from "../shared/apiWireResult.helper.js";
+import { compileRouteTable } from "../route/apiRoute.table.js";
+import { APINotFoundError, createAPIError, ErrorCode } from "../../errors/index.js";
+import { normalizeRequestId } from "../../context/context.type.js";
+import { normalizeAPIError } from "../../executor/executor.core.js";
+import { readFetchInput } from "./apiFetch.input.js";
+/** Default limit on a request body read by the fetch binding (1 MiB). */
+export const DEFAULT_API_MAX_BODY_BYTES = 1024 * 1024;
+const MAX_REFLECTED_PATH = 256;
+const FALLBACK_WRITER = createSerializer("json");
+/**
+ * Exposes operations as a web-standard handler,
+ * `(request: Request) => Promise<Response>`, that any Fetch API server
+ * (`@zudojs/http`, Bun, Deno, edge runtimes, Node adapters) can mount.
+ *
+ * Routes come from each operation's `metadata.http` (default
+ * `POST /<name>`), input from the query string or JSON body plus path
+ * parameters, and every response body is an {@link APIWireResult}:
+ * `{ ok: true, data }` with 200, or `{ ok: false, error }` with the error's
+ * status (422 validation, 404 unknown route, 405 wrong method, 413/415 bad
+ * body, 500 internal). Internal messages and stack traces never reach the
+ * response. The call runs under `request.signal`, so a client that
+ * disconnects cancels it; the request id comes from `x-request-id` when
+ * safe and is echoed back in the same header.
+ *
+ * @throws {TypeError | RangeError} at creation for invalid or conflicting routes.
+ */
+export function createApiFetchHandler(operations, options = {}) {
+    const table = compileRouteTable(operations, options.basePath);
+    const run = createOperationRunner(options);
+    const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_API_MAX_BODY_BYTES;
+    const reader = options.serializer ?? createSerializer("json", { maxSize: maxBodyBytes, maxDepth: 64 });
+    const writer = options.serializer ?? createSerializer("json");
+    const respond = (body, code, requestId, extra) => {
+        let text;
+        let status = code;
+        try {
+            text = writer.serialize(body);
+        }
+        catch (error) {
+            const failure = normalizeAPIError(error, "response serialization");
+            options.onInternalError?.(failure, requestId);
+            text = FALLBACK_WRITER.serialize(toApiWireResult({ ok: false, error: failure }, requestId));
+            status = 500;
+        }
+        return new Response(text, {
+            status,
+            headers: {
+                "content-type": "application/json; charset=utf-8",
+                "cache-control": "no-store",
+                "x-content-type-options": "nosniff",
+                "x-request-id": requestId,
+                ...extra,
+            },
+        });
+    };
+    const refuse = (error, requestId, extra) => {
+        const body = toApiWireResult({ ok: false, error }, requestId);
+        return respond(body, body.ok ? 200 : body.error.statusCode, requestId, extra);
+    };
+    return async (request) => {
+        const requestId = normalizeRequestId(request.headers.get("x-request-id") ?? undefined);
+        const url = new URL(request.url);
+        const match = table.match(request.method, url.pathname);
+        if (match.kind === "not-found") {
+            const path = url.pathname.slice(0, MAX_REFLECTED_PATH);
+            return refuse(new APINotFoundError(path, request.method.slice(0, 16)), requestId);
+        }
+        if (match.kind === "bad-path") {
+            return refuse(clientError(400, "Request path is not correctly encoded."), requestId);
+        }
+        if (match.kind === "method-not-allowed") {
+            const allow = match.allow.join(", ");
+            return refuse(clientError(405, `Method not allowed; use ${allow}.`), requestId, { allow });
+        }
+        const { route, operation } = match.entry;
+        const read = await readFetchInput(request, url, route, match.params, reader, maxBodyBytes);
+        if (!read.ok) {
+            return refuse(read.error, requestId);
+        }
+        const outcome = await run({
+            operation,
+            input: read.input,
+            source: request,
+            transport: "http",
+            requestId,
+            correlationId: request.headers.get("x-correlation-id") ?? undefined,
+            signal: request.signal,
+        });
+        const body = toApiWireResult(outcome.result, outcome.requestId);
+        return respond(body, body.ok ? route.successStatus : body.error.statusCode, outcome.requestId);
+    };
+}
+function clientError(statusCode, message) {
+    return createAPIError(message, { statusCode, code: ErrorCode.API_ERROR, expose: true });
+}
+//# sourceMappingURL=apiFetch.handler.js.map

package/dist/api/bindings/fetch/apiFetch.input.d.ts

@@ -0,0 +1,29 @@
+import type { Serializer } from "@zudojs/serialization";
+import type { APIOperationRoute } from "../route/apiRoute.type.js";
+import type { APIError } from "../../errors/index.js";
+/**
+ * Operation input read from a request, or the client error explaining why
+ * it could not be read.
+ */
+export type APIFetchInput = {
+    readonly ok: true;
+    readonly input: unknown;
+} | {
+    readonly ok: false;
+    readonly error: APIError;
+};
+/**
+ * Reads operation input from a Fetch API request.
+ *
+ * `GET` / `DELETE` routes read the query string: each key becomes a
+ * string, a repeated key an array of strings (schemas coerce as needed).
+ * Body routes read a JSON body, bounded by `maxBodyBytes`; an empty body
+ * is `undefined`, and any declared content type other than JSON is
+ * refused (415) even when the body is empty. Path parameters are merged
+ * over the result and win, so the URL — not the body — names the
+ * resource. Keys that could pollute a prototype (`__proto__`,
+ * `constructor`, `prototype`) are refused at any depth, in the query and
+ * the body alike.
+ */
+export declare function readFetchInput(request: Request, url: URL, route: APIOperationRoute, params: Readonly<Record<string, string>>, serializer: Serializer<unknown, string>, maxBodyBytes: number): Promise<APIFetchInput>;
+//# sourceMappingURL=apiFetch.input.d.ts.map

package/dist/api/bindings/fetch/apiFetch.input.js

@@ -0,0 +1,74 @@
+import { readBoundedBody } from "@zudojs/rpc";
+import { findUnsafeKey } from "@zudojs/security";
+import { isPlainObject } from "@zudojs/types";
+import { createAPIError, ErrorCode } from "../../errors/index.js";
+const JSON_TYPE = /^application\/(?:[\w.+-]+\+)?json(?:\s*;|$)/i;
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Reads operation input from a Fetch API request.
+ *
+ * `GET` / `DELETE` routes read the query string: each key becomes a
+ * string, a repeated key an array of strings (schemas coerce as needed).
+ * Body routes read a JSON body, bounded by `maxBodyBytes`; an empty body
+ * is `undefined`, and any declared content type other than JSON is
+ * refused (415) even when the body is empty. Path parameters are merged
+ * over the result and win, so the URL — not the body — names the
+ * resource. Keys that could pollute a prototype (`__proto__`,
+ * `constructor`, `prototype`) are refused at any depth, in the query and
+ * the body alike.
+ */
+export async function readFetchInput(request, url, route, params, serializer, maxBodyBytes) {
+    const hasParams = route.pathParams.length > 0;
+    if (route.inputSource === "query") {
+        const query = {};
+        for (const key of new Set(url.searchParams.keys())) {
+            if (UNSAFE_KEYS.has(key)) {
+                return fail(400, ErrorCode.API_VALIDATION, `Query parameter "${key}" is not allowed.`);
+            }
+            const values = url.searchParams.getAll(key);
+            query[key] = values.length === 1 ? values[0] : values;
+        }
+        return { ok: true, input: { ...query, ...params } };
+    }
+    const body = await readBoundedBody(request, maxBodyBytes);
+    if (!body.ok) {
+        return body.reason === "too-large"
+            ? fail(413, ErrorCode.PAYLOAD_TOO_LARGE, `Request body exceeds ${maxBodyBytes} bytes.`)
+            : fail(400, ErrorCode.HTTP_BODY, "Request body could not be read.");
+    }
+    // A declared non-JSON type is refused even with an empty body: an HTML
+    // form can post `text/plain`, `multipart/form-data` or urlencoded bodies
+    // cross-site without a CORS preflight, which would otherwise run an
+    // input-less operation on the victim's cookies.
+    const contentType = request.headers.get("content-type");
+    if (contentType !== null && !JSON_TYPE.test(contentType)) {
+        return fail(415, ErrorCode.HTTP_UNSUPPORTED_BODY_TYPE, "Request body must be application/json.");
+    }
+    let value;
+    if (body.text.trim().length > 0) {
+        if (contentType === null) {
+            return fail(415, ErrorCode.HTTP_UNSUPPORTED_BODY_TYPE, "Request body must be application/json.");
+        }
+        try {
+            value = serializer.deserialize(body.text);
+        }
+        catch {
+            return fail(400, ErrorCode.HTTP_BODY_PARSE, "Request body is not valid JSON.");
+        }
+        const unsafe = findUnsafeKey(value);
+        if (unsafe !== undefined) {
+            return fail(400, ErrorCode.API_VALIDATION, `Request body key "${unsafe}" is not allowed.`);
+        }
+    }
+    if (!hasParams) {
+        return { ok: true, input: value };
+    }
+    if (value !== undefined && !isPlainObject(value)) {
+        return fail(400, ErrorCode.API_VALIDATION, "Request body must be a JSON object.");
+    }
+    return { ok: true, input: { ...(value ?? {}), ...params } };
+}
+function fail(statusCode, code, message) {
+    return { ok: false, error: createAPIError(message, { statusCode, code, expose: true }) };
+}
+//# sourceMappingURL=apiFetch.input.js.map

package/dist/api/bindings/fetch/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Web-standard HTTP binding: exposes operations as a
+ * `(request: Request) => Promise<Response>` handler that any Fetch API
+ * server can mount, with routes taken from each operation's
+ * `metadata.http`.
+ */
+export type { APIFetchHandlerOptions } from "./apiFetch.handler.js";
+export { createApiFetchHandler, DEFAULT_API_MAX_BODY_BYTES } from "./apiFetch.handler.js";
+export type { APIFetchInput } from "./apiFetch.input.js";
+export { readFetchInput } from "./apiFetch.input.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/bindings/fetch/index.js

@@ -0,0 +1,9 @@
+/**
+ * Web-standard HTTP binding: exposes operations as a
+ * `(request: Request) => Promise<Response>` handler that any Fetch API
+ * server can mount, with routes taken from each operation's
+ * `metadata.http`.
+ */
+export { createApiFetchHandler, DEFAULT_API_MAX_BODY_BYTES } from "./apiFetch.handler.js";
+export { readFetchInput } from "./apiFetch.input.js";
+//# sourceMappingURL=index.js.map

package/dist/api/bindings/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bindings that expose one set of operations over many transports — HTTP
+ * (a web-standard fetch handler), RPC, queues and the command line, plus
+ * OpenAPI route descriptors — with
+ * the same executor, interceptors, validation and client-safe error shape
+ * on every one.
+ *
+ * This barrel is the package's public binding surface; runner and
+ * route-matching internals stay in the subfolder barrels.
+ */
+export type { APIBindingOptions, APIOperationSource, APIWireError, APIWireResult, } from "./shared/index.js";
+export { API_INTERNAL_ERROR_MESSAGE, toApiWireError, toApiWireResult, } from "./shared/index.js";
+export type { APIHttpMethod, APIRouteInputSource, APIOperationHttpOptions, APIOperationRoute, DescribeApiRoutesOptions, } from "./route/index.js";
+export { describeApiRoutes, resolveApiRoute } from "./route/index.js";
+export type { APIFetchHandlerOptions } from "./fetch/index.js";
+export { createApiFetchHandler, DEFAULT_API_MAX_BODY_BYTES } from "./fetch/index.js";
+export type { APIRpcBindingOptions, APIRpcProcedureTarget } from "./rpc/index.js";
+export { API_RPC_TIMEOUT_MARGIN_MS, apiErrorToRPCError, createApiRpcProcedure, registerApiRpcProcedures, } from "./rpc/index.js";
+export type { APIQueueBindingOptions, APIQueueTarget } from "./queue/index.js";
+export { bindApiQueue, createApiQueueProcessor } from "./queue/index.js";
+export type { APICliInvocation, APICliIO, APICliOptions, APICliParseResult, APICliExitCodeValue, } from "./cli/index.js";
+export { APICliExitCode, parseApiCliArgs, runApiCli } from "./cli/index.js";
+export type { ToOpenAPIRouteDescriptorsOptions } from "./openapi/index.js";
+export { apiSuccessBodySchema, apiWireErrorBodySchema, toOpenAPIRouteDescriptor, toOpenAPIRouteDescriptors, } from "./openapi/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/bindings/index.js

@@ -0,0 +1,18 @@
+/**
+ * Bindings that expose one set of operations over many transports — HTTP
+ * (a web-standard fetch handler), RPC, queues and the command line, plus
+ * OpenAPI route descriptors — with
+ * the same executor, interceptors, validation and client-safe error shape
+ * on every one.
+ *
+ * This barrel is the package's public binding surface; runner and
+ * route-matching internals stay in the subfolder barrels.
+ */
+export { API_INTERNAL_ERROR_MESSAGE, toApiWireError, toApiWireResult, } from "./shared/index.js";
+export { describeApiRoutes, resolveApiRoute } from "./route/index.js";
+export { createApiFetchHandler, DEFAULT_API_MAX_BODY_BYTES } from "./fetch/index.js";
+export { API_RPC_TIMEOUT_MARGIN_MS, apiErrorToRPCError, createApiRpcProcedure, registerApiRpcProcedures, } from "./rpc/index.js";
+export { bindApiQueue, createApiQueueProcessor } from "./queue/index.js";
+export { APICliExitCode, parseApiCliArgs, runApiCli } from "./cli/index.js";
+export { apiSuccessBodySchema, apiWireErrorBodySchema, toOpenAPIRouteDescriptor, toOpenAPIRouteDescriptors, } from "./openapi/index.js";
+//# sourceMappingURL=index.js.map

package/dist/api/bindings/openapi/apiOpenAPI.descriptor.d.ts

@@ -0,0 +1,37 @@
+import type { OpenAPIRouteDescriptor } from "@zudojs/openapi";
+import type { APIOperationSource } from "../shared/apiBinding.type.js";
+import type { APIOperationRoute } from "../route/apiRoute.type.js";
+import type { DescribeApiRoutesOptions } from "../route/apiRoute.table.js";
+/**
+ * Options for {@link toOpenAPIRouteDescriptors}.
+ */
+export type ToOpenAPIRouteDescriptorsOptions = DescribeApiRoutesOptions;
+/**
+ * Converts an operation set into `@zudojs/openapi` route descriptors, so
+ * the operations served by `createApiFetchHandler` can be documented in
+ * one call:
+ *
+ * ```ts
+ * const document = createOpenAPIDocumentFromRoutes(
+ *   toOpenAPIRouteDescriptors(registry, { basePath: "/api" }),
+ *   { info: { title: "Users", version: "1.0.0" } },
+ * );
+ * ```
+ *
+ * Each descriptor carries the route's method, path, `operationId`,
+ * description, tags and deprecation. The input schema becomes `query`
+ * (`GET` / `DELETE`) or `body`, with path-bound fields moved to `params`.
+ * `responses` documents 200 with the `{ ok: true, data }` envelope around
+ * the output schema, and 422, 404, 409, 500 and 504 with the
+ * `{ ok: false, error }` body. Only `@zudojs/schema` schemas can be
+ * converted; input or output declared with another library is left
+ * undocumented (`data` is then `unknown`).
+ *
+ * @throws {TypeError | RangeError} as `describeApiRoutes`.
+ */
+export declare function toOpenAPIRouteDescriptors(operations: APIOperationSource, options?: ToOpenAPIRouteDescriptorsOptions): readonly OpenAPIRouteDescriptor[];
+/**
+ * Converts one {@link APIOperationRoute} into an OpenAPI route descriptor.
+ */
+export declare function toOpenAPIRouteDescriptor(route: APIOperationRoute): OpenAPIRouteDescriptor;
+//# sourceMappingURL=apiOpenAPI.descriptor.d.ts.map

package/dist/api/bindings/openapi/apiOpenAPI.descriptor.js

@@ -0,0 +1,67 @@
+import { describeApiRoutes } from "../route/apiRoute.table.js";
+import { apiSuccessBodySchema, apiWireErrorBodySchema, splitInputSchema, } from "./apiOpenAPI.schemas.js";
+/**
+ * Error responses every operation can produce over the fetch binding,
+ * each documented with the `{ ok: false, error }` body.
+ */
+const ERROR_RESPONSES = [
+    ["422", "Input failed validation."],
+    ["404", "No operation is bound to this method and path."],
+    ["409", "The operation reported a conflict."],
+    ["500", "Internal error. The message is generic; detail is logged server-side."],
+    ["504", "The operation timed out."],
+];
+/**
+ * Converts an operation set into `@zudojs/openapi` route descriptors, so
+ * the operations served by `createApiFetchHandler` can be documented in
+ * one call:
+ *
+ * ```ts
+ * const document = createOpenAPIDocumentFromRoutes(
+ *   toOpenAPIRouteDescriptors(registry, { basePath: "/api" }),
+ *   { info: { title: "Users", version: "1.0.0" } },
+ * );
+ * ```
+ *
+ * Each descriptor carries the route's method, path, `operationId`,
+ * description, tags and deprecation. The input schema becomes `query`
+ * (`GET` / `DELETE`) or `body`, with path-bound fields moved to `params`.
+ * `responses` documents 200 with the `{ ok: true, data }` envelope around
+ * the output schema, and 422, 404, 409, 500 and 504 with the
+ * `{ ok: false, error }` body. Only `@zudojs/schema` schemas can be
+ * converted; input or output declared with another library is left
+ * undocumented (`data` is then `unknown`).
+ *
+ * @throws {TypeError | RangeError} as `describeApiRoutes`.
+ */
+export function toOpenAPIRouteDescriptors(operations, options = {}) {
+    return Object.freeze(describeApiRoutes(operations, options).map(toOpenAPIRouteDescriptor));
+}
+/**
+ * Converts one {@link APIOperationRoute} into an OpenAPI route descriptor.
+ */
+export function toOpenAPIRouteDescriptor(route) {
+    const { params, rest } = splitInputSchema(route.input, route.pathParams);
+    const responses = {
+        "200": { schema: apiSuccessBodySchema(route.output), description: "Success." },
+    };
+    for (const [status, description] of ERROR_RESPONSES) {
+        responses[status] = { schema: apiWireErrorBodySchema, description };
+    }
+    return Object.freeze({
+        method: route.method,
+        path: route.path,
+        operationId: route.operationId,
+        ...(route.description !== undefined ? { description: route.description } : {}),
+        ...(route.tags !== undefined ? { tags: route.tags } : {}),
+        ...(route.deprecated !== undefined ? { deprecated: route.deprecated } : {}),
+        ...(params !== undefined ? { params: params } : {}),
+        ...(rest !== undefined
+            ? route.inputSource === "query"
+                ? { query: rest }
+                : { body: rest }
+            : {}),
+        responses: Object.freeze(responses),
+    });
+}
+//# sourceMappingURL=apiOpenAPI.descriptor.js.map

package/dist/api/bindings/openapi/apiOpenAPI.schemas.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The `{ ok: false, error }` body every binding sends on failure, as a
+ * `@zudojs/schema` schema for OpenAPI documents.
+ */
+export declare const apiWireErrorBodySchema: import("@zudojs/schema").ObjectSchema<{
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        statusCode: number;
+        requestId: string;
+        issues?: string[] | undefined;
+    };
+}>;
+/**
+ * Builds the `{ ok: true, data }` success envelope around an operation's
+ * output schema. An output that OpenAPI generation cannot convert (a
+ * Standard Schema from another library), or no output at all, is
+ * documented as `data: unknown`.
+ */
+export declare function apiSuccessBodySchema(output: unknown): unknown;
+/**
+ * Splits an input schema into the path-parameter part and the rest, so
+ * a field bound from the path is not also documented as a query parameter
+ * or body property. Returns `undefined` parts for input OpenAPI cannot
+ * convert.
+ */
+export declare function splitInputSchema(input: unknown, pathParams: readonly string[]): {
+    readonly params?: unknown;
+    readonly rest?: unknown;
+};
+//# sourceMappingURL=apiOpenAPI.schemas.d.ts.map

package/dist/api/bindings/openapi/apiOpenAPI.schemas.js

@@ -0,0 +1,62 @@
+import { isSchemaDefinition } from "@zudojs/openapi";
+import { schema } from "@zudojs/schema";
+/**
+ * The `{ ok: false, error }` body every binding sends on failure, as a
+ * `@zudojs/schema` schema for OpenAPI documents.
+ */
+export const apiWireErrorBodySchema = schema.object({
+    ok: schema.literal(false),
+    error: schema.object({
+        code: schema.string(),
+        message: schema.string(),
+        statusCode: schema.number(),
+        requestId: schema.string(),
+        issues: schema.optional(schema.array(schema.string())),
+    }),
+});
+/**
+ * Builds the `{ ok: true, data }` success envelope around an operation's
+ * output schema. An output that OpenAPI generation cannot convert (a
+ * Standard Schema from another library), or no output at all, is
+ * documented as `data: unknown`.
+ */
+export function apiSuccessBodySchema(output) {
+    const data = isSchemaDefinition(output) ? output : schema.unknown();
+    return schema.object({
+        ok: schema.literal(true),
+        data: data,
+    });
+}
+function isSplittable(value) {
+    const candidate = value;
+    return (isSchemaDefinition(value) &&
+        candidate?._type === "object" &&
+        typeof candidate.shape === "object" &&
+        typeof candidate.pick === "function" &&
+        typeof candidate.omit === "function");
+}
+/**
+ * Splits an input schema into the path-parameter part and the rest, so
+ * a field bound from the path is not also documented as a query parameter
+ * or body property. Returns `undefined` parts for input OpenAPI cannot
+ * convert.
+ */
+export function splitInputSchema(input, pathParams) {
+    if (!isSchemaDefinition(input)) {
+        return {};
+    }
+    if (!isSplittable(input)) {
+        return { rest: input };
+    }
+    const bound = pathParams.filter((name) => Object.hasOwn(input.shape, name));
+    if (bound.length === 0) {
+        return { rest: input };
+    }
+    const rest = input.omit(bound);
+    const restEmpty = Object.keys(rest.shape ?? {}).length === 0;
+    return {
+        params: input.pick(bound),
+        ...(restEmpty ? {} : { rest }),
+    };
+}
+//# sourceMappingURL=apiOpenAPI.schemas.js.map

package/dist/api/bindings/openapi/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OpenAPI bridge: converts an operation set into `@zudojs/openapi` route
+ * descriptors, so `createOpenAPIDocumentFromRoutes` documents exactly
+ * what `createApiFetchHandler` serves, envelopes included.
+ */
+export type { ToOpenAPIRouteDescriptorsOptions } from "./apiOpenAPI.descriptor.js";
+export { toOpenAPIRouteDescriptor, toOpenAPIRouteDescriptors, } from "./apiOpenAPI.descriptor.js";
+export { apiSuccessBodySchema, apiWireErrorBodySchema, splitInputSchema, } from "./apiOpenAPI.schemas.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/bindings/openapi/index.js

@@ -0,0 +1,8 @@
+/**
+ * OpenAPI bridge: converts an operation set into `@zudojs/openapi` route
+ * descriptors, so `createOpenAPIDocumentFromRoutes` documents exactly
+ * what `createApiFetchHandler` serves, envelopes included.
+ */
+export { toOpenAPIRouteDescriptor, toOpenAPIRouteDescriptors, } from "./apiOpenAPI.descriptor.js";
+export { apiSuccessBodySchema, apiWireErrorBodySchema, splitInputSchema, } from "./apiOpenAPI.schemas.js";
+//# sourceMappingURL=index.js.map

package/dist/api/bindings/queue/apiQueue.binding.d.ts

@@ -0,0 +1,39 @@
+import type { Job, Processor } from "@zudojs/queue";
+import type { AnyAPIOperation } from "../../operation/operation.type.js";
+import type { APIBindingOptions, APIOperationSource } from "../shared/apiBinding.type.js";
+/**
+ * Options for the queue binding. `state` receives the `Job` being run.
+ */
+export type APIQueueBindingOptions = APIBindingOptions<Job<unknown>>;
+/**
+ * Anything a processor can be registered on — a `Queue` from
+ * `@zudojs/queue`, such as `createInMemoryQueue(...)`.
+ */
+export interface APIQueueTarget<TData> {
+    process(name: string, processor: Processor<TData>): void;
+}
+/**
+ * Wraps one operation as a queue processor.
+ *
+ * `job.data` is the operation input. The operation runs through the
+ * executor — validation, interceptors, timeout — under the job's abort
+ * signal, with the job id as request id and `job.metadata.correlationId`
+ * as correlation id. Success completes the job with the operation's
+ * output as its result. A failure throws an `APIError` carrying the same
+ * client-safe message and code the other bindings expose (the original
+ * is its `cause`), so the queue retries and dead-letters it as usual and
+ * `job.error` never holds internal detail; the original error also goes
+ * to `onInternalError`.
+ *
+ * Every failure is retried up to the job's `attempts`, validation
+ * failures included — enqueue with `attempts: 1` when input is not
+ * already known to be valid.
+ */
+export declare function createApiQueueProcessor<TData = unknown>(operation: AnyAPIOperation, options?: APIQueueBindingOptions): Processor<TData>;
+/**
+ * Registers a processor for every operation, under the operation's name
+ * as job name, and returns the job names. Enqueue work with
+ * `queue.add(operation.name, input)`.
+ */
+export declare function bindApiQueue<TData = unknown>(queue: APIQueueTarget<TData>, operations: APIOperationSource, options?: APIQueueBindingOptions): readonly string[];
+//# sourceMappingURL=apiQueue.binding.d.ts.map

package/dist/api/bindings/queue/apiQueue.binding.js

@@ -0,0 +1,65 @@
+import { createJobResult } from "@zudojs/queue";
+import { createOperationRunner, listOperations } from "../shared/apiBinding.helper.js";
+import { toApiWireError } from "../shared/apiWireResult.helper.js";
+import { createAPIError } from "../../errors/index.js";
+/**
+ * Wraps one operation as a queue processor.
+ *
+ * `job.data` is the operation input. The operation runs through the
+ * executor — validation, interceptors, timeout — under the job's abort
+ * signal, with the job id as request id and `job.metadata.correlationId`
+ * as correlation id. Success completes the job with the operation's
+ * output as its result. A failure throws an `APIError` carrying the same
+ * client-safe message and code the other bindings expose (the original
+ * is its `cause`), so the queue retries and dead-letters it as usual and
+ * `job.error` never holds internal detail; the original error also goes
+ * to `onInternalError`.
+ *
+ * Every failure is retried up to the job's `attempts`, validation
+ * failures included — enqueue with `attempts: 1` when input is not
+ * already known to be valid.
+ */
+export function createApiQueueProcessor(operation, options = {}) {
+    return buildProcessor(operation, createOperationRunner(options));
+}
+/**
+ * Registers a processor for every operation, under the operation's name
+ * as job name, and returns the job names. Enqueue work with
+ * `queue.add(operation.name, input)`.
+ */
+export function bindApiQueue(queue, operations, options = {}) {
+    const run = createOperationRunner(options);
+    const names = [];
+    for (const operation of listOperations(operations)) {
+        queue.process(operation.name, buildProcessor(operation, run));
+        names.push(operation.name);
+    }
+    return Object.freeze(names);
+}
+function buildProcessor(operation, run) {
+    return async (job, context) => {
+        const started = Date.now();
+        const { result, requestId } = await run({
+            operation,
+            input: job.data,
+            source: job,
+            transport: "queue",
+            requestId: job.id,
+            correlationId: job.metadata?.["correlationId"],
+            signal: context.signal,
+        });
+        if (!result.ok) {
+            const wire = toApiWireError(result.error, requestId);
+            throw createAPIError(wire.message, {
+                code: wire.code,
+                statusCode: wire.statusCode,
+                expose: result.error.expose,
+                cause: result.error,
+            });
+        }
+        // Wrapped in a JobResult so an output that happens to carry a
+        // `success` field is not mistaken for a JobResult by the queue.
+        return createJobResult(result.data, Date.now() - started);
+    };
+}
+//# sourceMappingURL=apiQueue.binding.js.map

package/dist/api/bindings/queue/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Queue binding: consumes `@zudojs/queue` jobs by running the operation
+ * named by the job, with the job payload as input.
+ */
+export type { APIQueueBindingOptions, APIQueueTarget } from "./apiQueue.binding.js";
+export { bindApiQueue, createApiQueueProcessor } from "./apiQueue.binding.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/bindings/queue/index.js

@@ -0,0 +1,6 @@
+/**
+ * Queue binding: consumes `@zudojs/queue` jobs by running the operation
+ * named by the job, with the job payload as input.
+ */
+export { bindApiQueue, createApiQueueProcessor } from "./apiQueue.binding.js";
+//# sourceMappingURL=index.js.map