@zudojs/api 1.1.1 → 1.2.0

package/dist/api/bindings/route/apiRoute.resolver.d.ts

@@ -0,0 +1,33 @@
+import type { APIOperation } from "../../operation/operation.type.js";
+import type { APIOperationRoute } from "./apiRoute.type.js";
+/**
+ * Splits and validates a path template, returning its segments.
+ *
+ * @throws {TypeError} if `path` is not a string.
+ * @throws {RangeError} if `path` is empty, over-long, does not start with
+ * `/`, has an empty or illegal segment, or repeats a parameter name.
+ */
+export declare function parseRoutePath(path: unknown, label: string): readonly string[];
+/**
+ * Validates `metadata.http` on an operation definition.
+ *
+ * @throws {TypeError | RangeError} for an unknown method or invalid path.
+ */
+export declare function assertValidHttpOptions(http: unknown, operationName: string): void;
+/**
+ * Resolves the HTTP route of one operation.
+ *
+ * Without `metadata.http` the route is `POST /<operation name>`; a name
+ * whose default path would contain an empty or `:`-prefixed segment must
+ * declare `metadata.http.path` explicitly.
+ *
+ * @param basePath Prefix such as `"/api"`; `"/"` or `undefined` for none.
+ * @throws {TypeError | RangeError} if the route or base path is invalid.
+ */
+export declare function resolveApiRoute(operation: APIOperation, basePath?: string): APIOperationRoute;
+/**
+ * Returns the conflict key of a route: two routes with the same method
+ * and the same path shape (parameter names ignored) can never both match.
+ */
+export declare function routeConflictKey(route: APIOperationRoute): string;
+//# sourceMappingURL=apiRoute.resolver.d.ts.map

package/dist/api/bindings/route/apiRoute.resolver.js

@@ -0,0 +1,109 @@
+const METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+const MAX_PATH_LENGTH = 512;
+const LITERAL_SEGMENT = /^[A-Za-z0-9._~!$&'()*+,;=@-][A-Za-z0-9._~!$&'()*+,;=@:-]*$/;
+const PARAM_SEGMENT = /^:([A-Za-z_][A-Za-z0-9_]*)$/;
+const UNSAFE_PARAM_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Splits and validates a path template, returning its segments.
+ *
+ * @throws {TypeError} if `path` is not a string.
+ * @throws {RangeError} if `path` is empty, over-long, does not start with
+ * `/`, has an empty or illegal segment, or repeats a parameter name.
+ */
+export function parseRoutePath(path, label) {
+    if (typeof path !== "string") {
+        throw new TypeError(`${label} must be a string, received ${typeof path}.`);
+    }
+    if (path.length === 0 || path.length > MAX_PATH_LENGTH || !path.startsWith("/")) {
+        throw new RangeError(`${label} must start with "/" and be at most ${MAX_PATH_LENGTH} characters.`);
+    }
+    const trimmed = path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+    const segments = trimmed === "/" ? [] : trimmed.slice(1).split("/");
+    const params = new Set();
+    for (const segment of segments) {
+        const param = PARAM_SEGMENT.exec(segment)?.[1];
+        if (param !== undefined) {
+            if (UNSAFE_PARAM_NAMES.has(param) || params.has(param)) {
+                throw new RangeError(`${label} "${path}" repeats or misuses parameter ":${param}".`);
+            }
+            params.add(param);
+        }
+        else if (!LITERAL_SEGMENT.test(segment)) {
+            throw new RangeError(`${label} "${path}" has an empty or invalid segment "${segment}".`);
+        }
+    }
+    return segments;
+}
+/**
+ * Validates `metadata.http` on an operation definition.
+ *
+ * @throws {TypeError | RangeError} for an unknown method or invalid path.
+ */
+export function assertValidHttpOptions(http, operationName) {
+    if (http === undefined) {
+        return;
+    }
+    if (typeof http !== "object" || http === null) {
+        throw new TypeError(`Operation "${operationName}" metadata.http must be an object.`);
+    }
+    const { method, path } = http;
+    if (method !== undefined && (typeof method !== "string" || !METHODS.has(method))) {
+        throw new RangeError(`Operation "${operationName}" metadata.http.method must be one of ${[...METHODS].join(", ")}.`);
+    }
+    if (path !== undefined) {
+        parseRoutePath(path, `Operation "${operationName}" metadata.http.path`);
+    }
+}
+/**
+ * Resolves the HTTP route of one operation.
+ *
+ * Without `metadata.http` the route is `POST /<operation name>`; a name
+ * whose default path would contain an empty or `:`-prefixed segment must
+ * declare `metadata.http.path` explicitly.
+ *
+ * @param basePath Prefix such as `"/api"`; `"/"` or `undefined` for none.
+ * @throws {TypeError | RangeError} if the route or base path is invalid.
+ */
+export function resolveApiRoute(operation, basePath) {
+    const http = operation.metadata?.http;
+    assertValidHttpOptions(http, operation.name);
+    const method = http?.method ?? "POST";
+    const own = http?.path ?? `/${operation.name}`;
+    const ownSegments = parseRoutePath(own, `Operation "${operation.name}" route path`);
+    if (http?.path === undefined && ownSegments.some((s) => s.startsWith(":"))) {
+        throw new RangeError(`Operation "${operation.name}" cannot use its name as a path; declare metadata.http.path.`);
+    }
+    const baseSegments = basePath === undefined ? [] : parseRoutePath(basePath, "basePath");
+    const segments = [...baseSegments, ...ownSegments];
+    const path = `/${segments.join("/")}`;
+    parseRoutePath(path, `Operation "${operation.name}" route path`);
+    const pathParams = segments.filter((s) => s.startsWith(":")).map((s) => s.slice(1));
+    const inputSource = method === "GET" || method === "DELETE" ? "query" : "body";
+    const metadata = operation.metadata;
+    return Object.freeze({
+        operationId: operation.name,
+        method,
+        path,
+        pathParams: Object.freeze(pathParams),
+        inputSource,
+        ...(operation.input !== undefined ? { input: operation.input } : {}),
+        ...(operation.output !== undefined ? { output: operation.output } : {}),
+        ...(metadata?.description !== undefined ? { description: metadata.description } : {}),
+        ...(metadata?.tags !== undefined ? { tags: metadata.tags } : {}),
+        ...(metadata?.deprecated !== undefined ? { deprecated: metadata.deprecated } : {}),
+        ...(metadata?.version !== undefined ? { version: metadata.version } : {}),
+        successStatus: 200,
+    });
+}
+/**
+ * Returns the conflict key of a route: two routes with the same method
+ * and the same path shape (parameter names ignored) can never both match.
+ */
+export function routeConflictKey(route) {
+    const shape = route.path
+        .split("/")
+        .map((segment) => (segment.startsWith(":") ? ":" : segment))
+        .join("/");
+    return `${route.method} ${shape}`;
+}
+//# sourceMappingURL=apiRoute.resolver.js.map

package/dist/api/bindings/route/apiRoute.table.d.ts

@@ -0,0 +1,53 @@
+import type { APIOperation } from "../../operation/operation.type.js";
+import type { APIOperationSource } from "../shared/apiBinding.type.js";
+import type { APIOperationRoute } from "./apiRoute.type.js";
+/**
+ * Options for {@link describeApiRoutes}.
+ */
+export interface DescribeApiRoutesOptions {
+    /** Prefix for every route, e.g. `"/api"`. */
+    readonly basePath?: string;
+}
+/** A route paired with the operation it runs. */
+export interface APIRouteEntry {
+    readonly route: APIOperationRoute;
+    readonly operation: APIOperation;
+    readonly segments: readonly string[];
+}
+/**
+ * Result of matching a request against a route table.
+ */
+export type APIRouteMatch = {
+    readonly kind: "found";
+    readonly entry: APIRouteEntry;
+    readonly params: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "method-not-allowed";
+    readonly allow: readonly string[];
+} | {
+    readonly kind: "not-found";
+} | {
+    readonly kind: "bad-path";
+};
+/**
+ * Describes the HTTP route of every operation — the structural contract
+ * `@zudojs/http` mounts and `@zudojs/openapi` documents.
+ *
+ * @throws {TypeError | RangeError} if a route is invalid, or if two
+ * operations bind the same method and path shape.
+ */
+export declare function describeApiRoutes(operations: APIOperationSource, options?: DescribeApiRoutesOptions): readonly APIOperationRoute[];
+/**
+ * A compiled, immutable route table.
+ */
+export interface APIRouteTable {
+    readonly entries: readonly APIRouteEntry[];
+    match(method: string, pathname: string): APIRouteMatch;
+}
+/**
+ * Compiles operations into a route table for request matching.
+ *
+ * @throws {TypeError | RangeError} as {@link describeApiRoutes}.
+ */
+export declare function compileRouteTable(operations: APIOperationSource, basePath?: string): APIRouteTable;
+//# sourceMappingURL=apiRoute.table.d.ts.map

package/dist/api/bindings/route/apiRoute.table.js

@@ -0,0 +1,95 @@
+import { listOperations } from "../shared/apiBinding.helper.js";
+import { resolveApiRoute, routeConflictKey } from "./apiRoute.resolver.js";
+/**
+ * Describes the HTTP route of every operation — the structural contract
+ * `@zudojs/http` mounts and `@zudojs/openapi` documents.
+ *
+ * @throws {TypeError | RangeError} if a route is invalid, or if two
+ * operations bind the same method and path shape.
+ */
+export function describeApiRoutes(operations, options = {}) {
+    return Object.freeze(compileEntries(operations, options.basePath).map((e) => e.route));
+}
+function compileEntries(operations, basePath) {
+    const owners = new Map();
+    const entries = listOperations(operations).map((operation) => {
+        const route = resolveApiRoute(operation, basePath);
+        const key = routeConflictKey(route);
+        const owner = owners.get(key);
+        if (owner !== undefined) {
+            throw new RangeError(`Operations "${owner}" and "${operation.name}" both bind ${route.method} ${route.path}.`);
+        }
+        owners.set(key, operation.name);
+        const segments = route.path === "/" ? [] : route.path.slice(1).split("/");
+        return { route, operation, segments };
+    });
+    return entries.sort((a, b) => specificity(a.segments, b.segments));
+}
+/** Orders literal segments before parameters, so `/users/me` beats `/users/:id`. */
+function specificity(a, b) {
+    for (let i = 0; i < Math.min(a.length, b.length); i += 1) {
+        const diff = Number(a[i].startsWith(":")) - Number(b[i].startsWith(":"));
+        if (diff !== 0) {
+            return diff;
+        }
+    }
+    return 0;
+}
+/**
+ * Compiles operations into a route table for request matching.
+ *
+ * @throws {TypeError | RangeError} as {@link describeApiRoutes}.
+ */
+export function compileRouteTable(operations, basePath) {
+    const entries = Object.freeze(compileEntries(operations, basePath));
+    return Object.freeze({
+        entries,
+        match(method, pathname) {
+            const trimmed = pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+            const parts = trimmed === "/" || trimmed === "" ? [] : trimmed.slice(1).split("/");
+            const allow = new Set();
+            for (const entry of entries) {
+                const params = matchSegments(entry.segments, parts);
+                if (params === "bad") {
+                    return { kind: "bad-path" };
+                }
+                if (params === undefined) {
+                    continue;
+                }
+                if (entry.route.method === method) {
+                    return { kind: "found", entry, params };
+                }
+                allow.add(entry.route.method);
+            }
+            return allow.size > 0
+                ? { kind: "method-not-allowed", allow: [...allow] }
+                : { kind: "not-found" };
+        },
+    });
+}
+function matchSegments(template, parts) {
+    if (template.length !== parts.length) {
+        return undefined;
+    }
+    const params = {};
+    for (let i = 0; i < template.length; i += 1) {
+        const expected = template[i];
+        const actual = parts[i];
+        if (expected.startsWith(":")) {
+            if (actual.length === 0) {
+                return undefined;
+            }
+            try {
+                params[expected.slice(1)] = decodeURIComponent(actual);
+            }
+            catch {
+                return "bad";
+            }
+        }
+        else if (expected !== actual) {
+            return undefined;
+        }
+    }
+    return params;
+}
+//# sourceMappingURL=apiRoute.table.js.map

package/dist/api/bindings/route/apiRoute.type.d.ts

@@ -0,0 +1,65 @@
+/**
+ * HTTP route description for an operation.
+ *
+ * `@zudojs/api` does not import `@zudojs/http`; these types are the
+ * structural contract an HTTP layer (and OpenAPI generation) consumes.
+ */
+/** HTTP methods an operation can be bound to. */
+export type APIHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Where a route reads operation input from: the query string (`GET`,
+ * `DELETE`) or a JSON request body (`POST`, `PUT`, `PATCH`). Path
+ * parameters are merged into the input either way.
+ */
+export type APIRouteInputSource = "query" | "body";
+/**
+ * HTTP binding declared on an operation as `metadata.http`.
+ *
+ * Both fields are optional: an operation without them is served at
+ * `POST /<operation name>`.
+ */
+export interface APIOperationHttpOptions {
+    /** HTTP method. Defaults to `"POST"`. */
+    readonly method?: APIHttpMethod;
+    /**
+     * Path template, e.g. `"/users/:id"`. A segment starting with `:` is a
+     * path parameter merged into the input under that name. Defaults to
+     * `"/" + operation.name`.
+     */
+    readonly path?: string;
+}
+/**
+ * Stable, structural description of one operation's HTTP route.
+ *
+ * Produced by {@link describeApiRoutes}; consumed by `@zudojs/http` to
+ * mount routes and by `@zudojs/openapi` to generate documents. Contains
+ * only plain data plus the operation's own schema objects, so it can be
+ * read without importing this package's classes.
+ */
+export interface APIOperationRoute {
+    /** The operation's name — unique, and usable as an OpenAPI `operationId`. */
+    readonly operationId: string;
+    /** HTTP method. */
+    readonly method: APIHttpMethod;
+    /** Full path template including any base path, e.g. `"/api/users/:id"`. */
+    readonly path: string;
+    /** Names of the `:param` segments in `path`, in order. */
+    readonly pathParams: readonly string[];
+    /** Where non-path input is read from. */
+    readonly inputSource: APIRouteInputSource;
+    /** Input schema declared on the operation, if any. */
+    readonly input?: unknown;
+    /** Output schema declared on the operation, if any. */
+    readonly output?: unknown;
+    /** `metadata.description`. */
+    readonly description?: string;
+    /** `metadata.tags`. */
+    readonly tags?: readonly string[];
+    /** `metadata.deprecated`. */
+    readonly deprecated?: boolean;
+    /** `metadata.version`. */
+    readonly version?: string;
+    /** Status sent for a successful call. Always `200`. */
+    readonly successStatus: 200;
+}
+//# sourceMappingURL=apiRoute.type.d.ts.map

package/dist/api/bindings/route/apiRoute.type.js

@@ -0,0 +1,8 @@
+/**
+ * HTTP route description for an operation.
+ *
+ * `@zudojs/api` does not import `@zudojs/http`; these types are the
+ * structural contract an HTTP layer (and OpenAPI generation) consumes.
+ */
+export {};
+//# sourceMappingURL=apiRoute.type.js.map

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

@@ -0,0 +1,11 @@
+/**
+ * HTTP routes for operations: the structural {@link APIOperationRoute}
+ * contract (method, path template, operation id, schemas) that an HTTP
+ * layer mounts and OpenAPI generation documents, plus route resolution,
+ * validation and request matching.
+ */
+export type { APIHttpMethod, APIRouteInputSource, APIOperationHttpOptions, APIOperationRoute, } from "./apiRoute.type.js";
+export { assertValidHttpOptions, parseRoutePath, resolveApiRoute, routeConflictKey, } from "./apiRoute.resolver.js";
+export type { DescribeApiRoutesOptions, APIRouteEntry, APIRouteMatch, APIRouteTable, } from "./apiRoute.table.js";
+export { compileRouteTable, describeApiRoutes } from "./apiRoute.table.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * HTTP routes for operations: the structural {@link APIOperationRoute}
+ * contract (method, path template, operation id, schemas) that an HTTP
+ * layer mounts and OpenAPI generation documents, plus route resolution,
+ * validation and request matching.
+ */
+export { assertValidHttpOptions, parseRoutePath, resolveApiRoute, routeConflictKey, } from "./apiRoute.resolver.js";
+export { compileRouteTable, describeApiRoutes } from "./apiRoute.table.js";
+//# sourceMappingURL=index.js.map

package/dist/api/bindings/rpc/apiRpc.binding.d.ts

@@ -0,0 +1,46 @@
+import type { RPCContext, RPCProcedure } from "@zudojs/rpc";
+import type { AnyAPIOperation, APIOperation } from "../../operation/operation.type.js";
+import type { APIBindingOptions, APIOperationSource } from "../shared/apiBinding.type.js";
+/**
+ * Extra time the RPC dispatcher allows beyond an operation's own
+ * deadline, so the executor's `APITimeoutError` (mapped to
+ * `RPC_TIMEOUT`) is what a slow call reports.
+ */
+export declare const API_RPC_TIMEOUT_MARGIN_MS = 1000;
+/**
+ * Options for the RPC binding. `state` receives the `RPCContext` — read
+ * the transport-verified `context.auth` there, never frame `metadata`.
+ */
+export interface APIRpcBindingOptions extends APIBindingOptions<RPCContext> {
+    /**
+     * Maps an operation to its procedure name. Defaults to the operation
+     * name, which must then satisfy the RPC name rule (`"users.get"`).
+     */
+    readonly procedureName?: (operation: APIOperation) => string;
+}
+/**
+ * Anything procedures can be registered on: an `RPCServer`, an
+ * `RPCProcedureRegistry`, or an `RPCProcedureRouter`.
+ */
+export interface APIRpcProcedureTarget {
+    register(procedure: RPCProcedure): unknown;
+}
+/**
+ * Wraps one operation as an RPC procedure.
+ *
+ * The handler runs the operation through the executor — schema
+ * validation, interceptors and the operation timeout all apply — under
+ * the RPC call's abort signal, with the frame's request id and
+ * correlation id. A failed result is thrown as the matching RPC error
+ * (see `apiErrorToRPCError`), so the RPC server maps it to a wire code.
+ *
+ * @throws {RPCInvalidRequestError} if the procedure name is not a valid
+ * RPC name.
+ */
+export declare function createApiRpcProcedure(operation: AnyAPIOperation, options?: APIRpcBindingOptions): RPCProcedure;
+/**
+ * Registers every operation as an RPC procedure and returns the
+ * procedure names, in registration order.
+ */
+export declare function registerApiRpcProcedures(target: APIRpcProcedureTarget, operations: APIOperationSource, options?: APIRpcBindingOptions): readonly string[];
+//# sourceMappingURL=apiRpc.binding.d.ts.map

package/dist/api/bindings/rpc/apiRpc.binding.js

@@ -0,0 +1,63 @@
+import { createRPCProcedure } from "@zudojs/rpc";
+import { createOperationRunner, listOperations } from "../shared/apiBinding.helper.js";
+import { resolveOperationTimeout } from "../../operation/operation.type.js";
+import { apiErrorToRPCError } from "./apiRpc.errors.js";
+/**
+ * Extra time the RPC dispatcher allows beyond an operation's own
+ * deadline, so the executor's `APITimeoutError` (mapped to
+ * `RPC_TIMEOUT`) is what a slow call reports.
+ */
+export const API_RPC_TIMEOUT_MARGIN_MS = 1_000;
+/**
+ * Wraps one operation as an RPC procedure.
+ *
+ * The handler runs the operation through the executor — schema
+ * validation, interceptors and the operation timeout all apply — under
+ * the RPC call's abort signal, with the frame's request id and
+ * correlation id. A failed result is thrown as the matching RPC error
+ * (see `apiErrorToRPCError`), so the RPC server maps it to a wire code.
+ *
+ * @throws {RPCInvalidRequestError} if the procedure name is not a valid
+ * RPC name.
+ */
+export function createApiRpcProcedure(operation, options = {}) {
+    return buildProcedure(operation, options, createOperationRunner(options));
+}
+/**
+ * Registers every operation as an RPC procedure and returns the
+ * procedure names, in registration order.
+ */
+export function registerApiRpcProcedures(target, operations, options = {}) {
+    const run = createOperationRunner(options);
+    const names = [];
+    for (const operation of listOperations(operations)) {
+        const procedure = buildProcedure(operation, options, run);
+        target.register(procedure);
+        names.push(procedure.name);
+    }
+    return Object.freeze(names);
+}
+function buildProcedure(operation, options, run) {
+    const name = options.procedureName?.(operation) ?? operation.name;
+    const metadata = operation.metadata;
+    return createRPCProcedure(name, async (input, context) => {
+        const { result } = await run({
+            operation,
+            input,
+            source: context,
+            transport: "rpc",
+            requestId: context.metadata.requestId ?? context.request.id,
+            correlationId: context.metadata.correlationId,
+            signal: context.signal,
+        });
+        if (!result.ok) {
+            throw apiErrorToRPCError(result.error, name);
+        }
+        return result.data;
+    }, {
+        timeout: resolveOperationTimeout(operation) + API_RPC_TIMEOUT_MARGIN_MS,
+        ...(metadata?.description !== undefined ? { description: metadata.description } : {}),
+        ...(metadata?.idempotent !== undefined ? { idempotent: metadata.idempotent } : {}),
+    });
+}
+//# sourceMappingURL=apiRpc.binding.js.map

package/dist/api/bindings/rpc/apiRpc.errors.d.ts

@@ -0,0 +1,20 @@
+import { RPCError } from "@zudojs/errors";
+import type { APIError } from "../../errors/index.js";
+/**
+ * Converts an operation's `APIError` into the RPC error the RPC server
+ * maps onto the wire.
+ *
+ * Errors with an RPC equivalent become it, so a remote caller sees the
+ * same wire codes (`RPC_VALIDATION_ERROR` with issue `details`,
+ * `RPC_UNAUTHENTICATED`, `RPC_FORBIDDEN`, `RPC_RATE_LIMITED`,
+ * `RPC_TIMEOUT`, `RPC_CANCELLED`, `RPC_UNAVAILABLE`) as for a native
+ * procedure. Anything else — `APIConflictError`, `APINotFoundError`, a
+ * custom `createAPIError` — becomes an `RPCError` that keeps the API
+ * error's `code`, `statusCode` and `expose` flag, so a domain code such as
+ * `ERR_API_CONFLICT` survives the trip while a non-exposed message is
+ * still withheld. A typed error built with `expose: false` keeps its code
+ * but travels with the generic internal message, exactly as over HTTP.
+ * The original error is kept as `cause` for `onInternalError`.
+ */
+export declare function apiErrorToRPCError(error: APIError, procedure: string): RPCError;
+//# sourceMappingURL=apiRpc.errors.d.ts.map

package/dist/api/bindings/rpc/apiRpc.errors.js

@@ -0,0 +1,64 @@
+import { ErrorCode, RPCAuthenticationError, RPCCancelledError, RPCError, RPCForbiddenError, RPCInternalError, RPCRateLimitedError, RPCTimeoutError, RPCUnavailableError, RPCValidationError, } from "@zudojs/errors";
+import { API_INTERNAL_ERROR_MESSAGE } from "../shared/apiWireResult.helper.js";
+import { APIRateLimitError, APITimeoutError, APIValidationError, } from "../../errors/index.js";
+/**
+ * Converts an operation's `APIError` into the RPC error the RPC server
+ * maps onto the wire.
+ *
+ * Errors with an RPC equivalent become it, so a remote caller sees the
+ * same wire codes (`RPC_VALIDATION_ERROR` with issue `details`,
+ * `RPC_UNAUTHENTICATED`, `RPC_FORBIDDEN`, `RPC_RATE_LIMITED`,
+ * `RPC_TIMEOUT`, `RPC_CANCELLED`, `RPC_UNAVAILABLE`) as for a native
+ * procedure. Anything else — `APIConflictError`, `APINotFoundError`, a
+ * custom `createAPIError` — becomes an `RPCError` that keeps the API
+ * error's `code`, `statusCode` and `expose` flag, so a domain code such as
+ * `ERR_API_CONFLICT` survives the trip while a non-exposed message is
+ * still withheld. A typed error built with `expose: false` keeps its code
+ * but travels with the generic internal message, exactly as over HTTP.
+ * The original error is kept as `cause` for `onInternalError`.
+ */
+export function apiErrorToRPCError(error, procedure) {
+    return withCause(translate(error, procedure), error);
+}
+function translate(error, procedure) {
+    // The RPC server sends the message of every typed error below, so an
+    // error built with `expose: false` must not hand its message over: the
+    // HTTP, CLI and queue bindings all replace it with the generic text.
+    const exposed = error.expose === true;
+    const message = exposed ? error.message : API_INTERNAL_ERROR_MESSAGE;
+    switch (error.code) {
+        case ErrorCode.API_VALIDATION:
+            return new RPCValidationError(message, exposed && error instanceof APIValidationError ? error.issues : [], procedure);
+        case ErrorCode.API_AUTHENTICATION:
+            return new RPCAuthenticationError(message, procedure);
+        case ErrorCode.API_AUTHORIZATION:
+            return new RPCForbiddenError(message, procedure);
+        case ErrorCode.API_RATE_LIMIT:
+            return new RPCRateLimitedError(message, error instanceof APIRateLimitError ? error.retryAfterSeconds : undefined, procedure);
+        case ErrorCode.API_TIMEOUT:
+            return new RPCTimeoutError(error instanceof APITimeoutError ? error.timeoutMs : 0, procedure);
+        case ErrorCode.OPERATION_CANCELLED:
+            return new RPCCancelledError(message, procedure);
+        case ErrorCode.API_UNAVAILABLE:
+            return new RPCUnavailableError(message, procedure);
+        case ErrorCode.API_INTERNAL:
+            return new RPCInternalError(message, procedure);
+        default:
+            return new RPCError(message, {
+                code: error.code,
+                statusCode: error.statusCode,
+                expose: error.expose,
+                procedureName: procedure,
+            });
+    }
+}
+function withCause(error, cause) {
+    Object.defineProperty(error, "cause", {
+        value: cause,
+        enumerable: false,
+        configurable: true,
+        writable: true,
+    });
+    return error;
+}
+//# sourceMappingURL=apiRpc.errors.js.map

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

@@ -0,0 +1,9 @@
+/**
+ * RPC binding: registers operations as `@zudojs/rpc` procedures, so any
+ * RPC transport (in-memory, HTTP) can call them, with API errors mapped
+ * onto RPC wire codes.
+ */
+export type { APIRpcBindingOptions, APIRpcProcedureTarget } from "./apiRpc.binding.js";
+export { API_RPC_TIMEOUT_MARGIN_MS, createApiRpcProcedure, registerApiRpcProcedures, } from "./apiRpc.binding.js";
+export { apiErrorToRPCError } from "./apiRpc.errors.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,8 @@
+/**
+ * RPC binding: registers operations as `@zudojs/rpc` procedures, so any
+ * RPC transport (in-memory, HTTP) can call them, with API errors mapped
+ * onto RPC wire codes.
+ */
+export { API_RPC_TIMEOUT_MARGIN_MS, createApiRpcProcedure, registerApiRpcProcedures, } from "./apiRpc.binding.js";
+export { apiErrorToRPCError } from "./apiRpc.errors.js";
+//# sourceMappingURL=index.js.map

package/dist/api/bindings/shared/apiBinding.helper.d.ts

@@ -0,0 +1,44 @@
+import type { APIOperation } from "../../operation/operation.type.js";
+import type { APIResult } from "../../result/apiResult.type.js";
+import type { APITransportKind } from "../../context/contextKey.type.js";
+import type { APIBindingOptions, APIOperationSource } from "./apiBinding.type.js";
+/**
+ * Lists the operations of a source, validating a plain list the way the
+ * registry validates on `register`.
+ *
+ * @throws {TypeError | RangeError} for a malformed operation or a
+ * duplicated name in a list.
+ */
+export declare function listOperations(source: APIOperationSource): readonly APIOperation[];
+/**
+ * One call as a binding describes it to the runner.
+ */
+export interface APIBoundCall<TSource> {
+    readonly operation: APIOperation;
+    readonly input: unknown;
+    readonly source: TSource;
+    readonly transport: APITransportKind;
+    /** Untrusted request id from the transport; normalized before use. */
+    readonly requestId?: unknown;
+    /** Untrusted correlation id; recorded only when it is a safe id. */
+    readonly correlationId?: unknown;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Outcome of {@link createOperationRunner}'s `run`: the executor's result
+ * and the request id the call ran under.
+ */
+export interface APIBoundOutcome {
+    readonly result: APIResult<unknown>;
+    readonly requestId: string;
+}
+/**
+ * Creates the function every binding runs calls through, so the context,
+ * interceptors, error normalization and internal-error reporting are
+ * identical over HTTP, RPC, queues and the CLI. Input carrying a
+ * `__proto__`, `constructor` or `prototype` key anywhere is refused with
+ * an `APIValidationError` after `state` runs and before the operation
+ * does. `run` never throws.
+ */
+export declare function createOperationRunner<TSource>(options: APIBindingOptions<TSource>): (call: APIBoundCall<TSource>) => Promise<APIBoundOutcome>;
+//# sourceMappingURL=apiBinding.helper.d.ts.map