@zudojs/api 1.1.0 → 1.2.0

package/dist/api/executor/executor.deadline.d.ts

@@ -0,0 +1,40 @@
+import type { APIContext } from "../context/context.type.js";
+import type { APIError } from "../errors/index.js";
+/**
+ * Error for an execution cancelled by the caller's `AbortSignal`.
+ *
+ * Carries `ErrorCode.OPERATION_CANCELLED` — branch on that, not on the
+ * status code. `statusCode` is 499, an nginx convention ("Client Closed
+ * Request") rather than an IANA status; this package is
+ * transport-agnostic, so each adapter should map the *code* onto whatever
+ * its protocol calls "cancelled" (gRPC `CANCELLED`, a dropped queue
+ * message, a non-zero CLI exit) rather than passing 499 to the wire.
+ */
+export declare function abortedError(operationName: string): APIError;
+/**
+ * Returns a view of `context` whose `signal` is `signal`.
+ *
+ * Every other member resolves through the original context — `get`,
+ * `set` and `metadata` are delegated to it, so a value an interceptor set
+ * is visible to the handler and vice versa, and any extra members of a
+ * hand-rolled context are reachable through the prototype chain.
+ */
+export declare function withContextSignal(context: APIContext, signal: AbortSignal): APIContext;
+/**
+ * Runs `run` under a deadline and the caller's abort signal.
+ *
+ * `run` receives an `AbortSignal` that aborts when the deadline elapses
+ * (reason: the `APITimeoutError` the call fails with) or the caller's
+ * signal aborts (reason: the `OPERATION_CANCELLED` error the call fails
+ * with). A cooperative handler that passes it on (to `fetch`, a driver
+ * query, a loop check) therefore stops working instead of running on
+ * with its result discarded — the source of duplicate side effects when
+ * a client retries a timed-out call.
+ *
+ * `timeoutMs` is always a positive integer here — `defineOperation`
+ * rejects anything else and `resolveOperationTimeout` substitutes the
+ * default for hand-rolled operations — so the deadline can never be
+ * silently disabled.
+ */
+export declare function withDeadline<T>(run: (signal: AbortSignal) => Promise<T> | T, timeoutMs: number, operationName: string, callerSignal?: AbortSignal): Promise<T>;
+//# sourceMappingURL=executor.deadline.d.ts.map

package/dist/api/executor/executor.deadline.js

@@ -0,0 +1,93 @@
+import { APITimeoutError, createAPIError, ErrorCode } from "../errors/index.js";
+/**
+ * Error for an execution cancelled by the caller's `AbortSignal`.
+ *
+ * Carries `ErrorCode.OPERATION_CANCELLED` — branch on that, not on the
+ * status code. `statusCode` is 499, an nginx convention ("Client Closed
+ * Request") rather than an IANA status; this package is
+ * transport-agnostic, so each adapter should map the *code* onto whatever
+ * its protocol calls "cancelled" (gRPC `CANCELLED`, a dropped queue
+ * message, a non-zero CLI exit) rather than passing 499 to the wire.
+ */
+export function abortedError(operationName) {
+    return createAPIError(`Operation "${operationName}" was aborted.`, {
+        code: ErrorCode.OPERATION_CANCELLED,
+        statusCode: 499,
+        expose: true,
+    });
+}
+/**
+ * Returns a view of `context` whose `signal` is `signal`.
+ *
+ * Every other member resolves through the original context — `get`,
+ * `set` and `metadata` are delegated to it, so a value an interceptor set
+ * is visible to the handler and vice versa, and any extra members of a
+ * hand-rolled context are reachable through the prototype chain.
+ */
+export function withContextSignal(context, signal) {
+    const derived = Object.create(context, {
+        signal: { value: signal, enumerable: true },
+        requestId: { value: context.requestId, enumerable: true },
+        state: { value: context.state, enumerable: true },
+        get: { value: context.get.bind(context), enumerable: true },
+        set: { value: context.set.bind(context), enumerable: true },
+        metadata: { get: () => context.metadata, enumerable: true },
+    });
+    return Object.freeze(derived);
+}
+/**
+ * Runs `run` under a deadline and the caller's abort signal.
+ *
+ * `run` receives an `AbortSignal` that aborts when the deadline elapses
+ * (reason: the `APITimeoutError` the call fails with) or the caller's
+ * signal aborts (reason: the `OPERATION_CANCELLED` error the call fails
+ * with). A cooperative handler that passes it on (to `fetch`, a driver
+ * query, a loop check) therefore stops working instead of running on
+ * with its result discarded — the source of duplicate side effects when
+ * a client retries a timed-out call.
+ *
+ * `timeoutMs` is always a positive integer here — `defineOperation`
+ * rejects anything else and `resolveOperationTimeout` substitutes the
+ * default for hand-rolled operations — so the deadline can never be
+ * silently disabled.
+ */
+export function withDeadline(run, timeoutMs, operationName, callerSignal) {
+    const controller = new AbortController();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            clearTimeout(timer);
+            callerSignal?.removeEventListener("abort", onAbort);
+        };
+        const fail = (error) => {
+            cleanup();
+            if (!controller.signal.aborted) {
+                controller.abort(error);
+            }
+            reject(error);
+        };
+        const onAbort = () => fail(abortedError(operationName));
+        const timer = setTimeout(() => fail(new APITimeoutError(timeoutMs)), timeoutMs);
+        callerSignal?.addEventListener("abort", onAbort, { once: true });
+        if (callerSignal?.aborted) {
+            onAbort();
+            return;
+        }
+        let pending;
+        try {
+            // `Promise.resolve`: a hand-rolled operation whose handler returns
+            // synchronously is a legal JavaScript caller.
+            pending = Promise.resolve(run(controller.signal));
+        }
+        catch (error) {
+            pending = Promise.reject(error);
+        }
+        pending.then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
+//# sourceMappingURL=executor.deadline.js.map

package/dist/api/executor/executor.issues.d.ts

@@ -0,0 +1,19 @@
+import type { APISchemaIssue } from "../schema/index.js";
+/**
+ * Truncates `value` to at most `max` characters, marking the cut with `…`.
+ */
+export declare function truncate(value: string, max: number): string;
+/**
+ * Renders a Standard Schema issue path as a dotted string. Path segments
+ * are field names, never submitted values, so they are safe to expose.
+ */
+export declare function formatIssuePath(issue: APISchemaIssue): string;
+/**
+ * Converts schema issues into the capped, redacted list carried on the
+ * client-facing `APIValidationError`.
+ *
+ * With `exposeMessages` off (the default), each entry names only the
+ * failing path (`"user.email: invalid"`), never the submitted value.
+ */
+export declare function toClientIssues(issues: ReadonlyArray<APISchemaIssue>, limit: number, exposeMessages: boolean): readonly string[];
+//# sourceMappingURL=executor.issues.d.ts.map

package/dist/api/executor/executor.issues.js

@@ -0,0 +1,46 @@
+import { MAX_VALIDATION_ISSUE_LENGTH } from "../constants.js";
+/**
+ * Truncates `value` to at most `max` characters, marking the cut with `…`.
+ */
+export function truncate(value, max) {
+    const text = typeof value === "string" ? value : String(value);
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/**
+ * Renders a Standard Schema issue path as a dotted string. Path segments
+ * are field names, never submitted values, so they are safe to expose.
+ */
+export function formatIssuePath(issue) {
+    const path = issue.path;
+    if (path === undefined || path.length === 0) {
+        return "(root)";
+    }
+    return path
+        .map((segment) => {
+        const key = typeof segment === "object" && segment !== null && "key" in segment
+            ? segment.key
+            : segment;
+        return truncate(String(key), 64);
+    })
+        .join(".");
+}
+/**
+ * Converts schema issues into the capped, redacted list carried on the
+ * client-facing `APIValidationError`.
+ *
+ * With `exposeMessages` off (the default), each entry names only the
+ * failing path (`"user.email: invalid"`), never the submitted value.
+ */
+export function toClientIssues(issues, limit, exposeMessages) {
+    const shown = issues
+        .slice(0, limit)
+        .map((issue) => exposeMessages
+        ? truncate(issue.message, MAX_VALIDATION_ISSUE_LENGTH)
+        : `${formatIssuePath(issue)}: invalid`);
+    const omitted = issues.length - shown.length;
+    if (omitted > 0) {
+        shown.push(`… and ${omitted} more issue(s) omitted.`);
+    }
+    return shown;
+}
+//# sourceMappingURL=executor.issues.js.map

package/dist/api/executor/executor.normalize.d.ts

@@ -0,0 +1,16 @@
+import type { APIError } from "../errors/index.js";
+/**
+ * Error normalizer for converting unknown errors into APIError instances.
+ *
+ * APIErrors pass through untouched. Everything else is wrapped in an
+ * `APIInternalError` (`expose: false`) carrying a generic message; the
+ * original error is preserved on `cause` for logging.
+ *
+ * The wrapper's own message is deliberately *not* a copy of the original.
+ * `BaseError.toJSON()` in `@zudojs/errors` 0.1.0 emits `message`, `stack`
+ * and the serialized `cause` regardless of `expose`, so a transport doing
+ * `res.json(result.error)` would otherwise ship the raw driver message
+ * (connection strings, constraint names, file paths, tokens) to a client.
+ */
+export declare function normalizeAPIError(error: unknown, operationName?: string): APIError;
+//# sourceMappingURL=executor.normalize.d.ts.map

package/dist/api/executor/executor.normalize.js

@@ -0,0 +1,45 @@
+import { APIInternalError, isAPIError } from "../errors/index.js";
+/**
+ * Error normalizer for converting unknown errors into APIError instances.
+ *
+ * APIErrors pass through untouched. Everything else is wrapped in an
+ * `APIInternalError` (`expose: false`) carrying a generic message; the
+ * original error is preserved on `cause` for logging.
+ *
+ * The wrapper's own message is deliberately *not* a copy of the original.
+ * `BaseError.toJSON()` in `@zudojs/errors` 0.1.0 emits `message`, `stack`
+ * and the serialized `cause` regardless of `expose`, so a transport doing
+ * `res.json(result.error)` would otherwise ship the raw driver message
+ * (connection strings, constraint names, file paths, tokens) to a client.
+ */
+export function normalizeAPIError(error, operationName) {
+    if (isAPIError(error)) {
+        return error;
+    }
+    const where = operationName !== undefined && operationName !== ""
+        ? `operation "${operationName}"`
+        : "an API operation";
+    const wrapped = error instanceof Error
+        ? new APIInternalError(`An unexpected internal error occurred in ${where}.`)
+        : new APIInternalError(`A non-error value (${describeValueType(error)}) was thrown in ${where}.`);
+    // `APIInternalError`'s subclass constructor forwards only
+    // `{ endpoint, method }`, so `cause` cannot be passed through it.
+    // `APIError` / `createAPIError` *do* accept `cause`, but constructing
+    // through them would lose the `APIInternalError` class identity that
+    // consumers match on. `cause` is a declared writable class field on
+    // `BaseError`, so assigning it after construction is equivalent for
+    // `toJSON()` and for `error.cause` reads; only the native `[[cause]]`
+    // slot differs.
+    wrapped.cause = error;
+    return wrapped;
+}
+function describeValueType(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    return typeof value;
+}
+//# sourceMappingURL=executor.normalize.js.map

package/dist/api/executor/executor.type.d.ts

@@ -0,0 +1,33 @@
+import type { APIInterceptor } from "../interceptors/interceptor.type.js";
+/**
+ * Options for {@link APIExecutor}.
+ */
+export interface APIExecutorOptions {
+    /** Interceptor pipeline, outermost first. */
+    readonly interceptors?: readonly APIInterceptor[];
+    /**
+     * Whether raw schema issue messages are copied into the client-facing
+     * `APIValidationError` (which is `expose: true`).
+     *
+     * Default `false`. Schema messages routinely interpolate the received
+     * value — Zod's built-in messages do for several checks, and most
+     * hand-written `message:` strings do — which would put submitted
+     * secrets straight into a 422 body. With the default, clients receive
+     * one entry per failing path (`"user.email: invalid"`) naming *where*
+     * validation failed but never echoing *what* was submitted.
+     *
+     * Set to `true` only when every schema in the process is known to
+     * produce value-free messages.
+     */
+    readonly exposeValidationMessages?: boolean;
+    /**
+     * Maximum number of validation issues carried on a single
+     * `APIValidationError`. Defaults to `MAX_VALIDATION_ISSUES`.
+     *
+     * A schema over a large array emits one issue per failing element, so
+     * an uncapped list is an amplification vector: the executor is the
+     * layer on the untrusted-input boundary and caps it here.
+     */
+    readonly maxValidationIssues?: number;
+}
+//# sourceMappingURL=executor.type.d.ts.map

package/dist/api/executor/executor.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=executor.type.js.map

package/dist/api/executor/executor.validation.d.ts

@@ -0,0 +1,31 @@
+import type { APIResult } from "../result/apiResult.type.js";
+import type { APIOperation } from "../operation/operation.type.js";
+/**
+ * How client-facing validation issues are reported.
+ */
+export interface APIInputIssueOptions {
+    /** Maximum number of issues carried on the error. */
+    readonly maxIssues: number;
+    /** Whether raw schema messages are copied (otherwise paths only). */
+    readonly exposeMessages: boolean;
+}
+/**
+ * Validates input against `operation.input`, returning the validated
+ * (possibly transformed) value, or a client-facing `APIValidationError`
+ * (422) whose issues name failing paths, never submitted values.
+ *
+ * A schema that throws, or is unrecognised, fails closed with an
+ * internal error rather than letting the input through.
+ */
+export declare function validateOperationInput<TInput, TOutput>(operation: APIOperation<TInput, TOutput>, input: TInput, options: APIInputIssueOptions): Promise<APIResult<TInput>>;
+/**
+ * Validates handler output against `operation.output`.
+ *
+ * A response that does not match its declared schema is a server bug,
+ * not a client mistake, so failures surface as an `APIInternalError`
+ * (500, `expose: false`) naming only the failing paths — never the
+ * offending values, which are exactly the fields (password hashes,
+ * internal audit columns) that should not reach a client.
+ */
+export declare function validateOperationOutput<TInput, TOutput>(operation: APIOperation<TInput, TOutput>, output: TOutput, maxIssues: number): Promise<APIResult<TOutput>>;
+//# sourceMappingURL=executor.validation.d.ts.map

package/dist/api/executor/executor.validation.js

@@ -0,0 +1,58 @@
+import { apiFailure, apiSuccess } from "../result/apiResult.type.js";
+import { APIInternalError, APIValidationError } from "../errors/index.js";
+import { validateWithSchema } from "../schema/index.js";
+import { normalizeAPIError } from "./executor.normalize.js";
+import { formatIssuePath, toClientIssues } from "./executor.issues.js";
+/**
+ * Validates input against `operation.input`, returning the validated
+ * (possibly transformed) value, or a client-facing `APIValidationError`
+ * (422) whose issues name failing paths, never submitted values.
+ *
+ * A schema that throws, or is unrecognised, fails closed with an
+ * internal error rather than letting the input through.
+ */
+export async function validateOperationInput(operation, input, options) {
+    if (operation.input === undefined) {
+        return apiSuccess(input);
+    }
+    try {
+        const validation = await validateWithSchema(operation.input, input);
+        if (!validation.ok) {
+            return apiFailure(new APIValidationError(`Invalid input for operation "${operation.name}".`, toClientIssues(validation.issues, options.maxIssues, options.exposeMessages)));
+        }
+        return apiSuccess(validation.value);
+    }
+    catch (error) {
+        return apiFailure(normalizeAPIError(error, operation.name));
+    }
+}
+/**
+ * Validates handler output against `operation.output`.
+ *
+ * A response that does not match its declared schema is a server bug,
+ * not a client mistake, so failures surface as an `APIInternalError`
+ * (500, `expose: false`) naming only the failing paths — never the
+ * offending values, which are exactly the fields (password hashes,
+ * internal audit columns) that should not reach a client.
+ */
+export async function validateOperationOutput(operation, output, maxIssues) {
+    if (operation.output === undefined) {
+        return apiSuccess(output);
+    }
+    let validation;
+    try {
+        validation = await validateWithSchema(operation.output, output);
+    }
+    catch (error) {
+        return apiFailure(normalizeAPIError(error, operation.name));
+    }
+    if (!validation.ok) {
+        const paths = validation.issues
+            .slice(0, maxIssues)
+            .map(formatIssuePath)
+            .join(", ");
+        return apiFailure(new APIInternalError(`Invalid output for operation "${operation.name}" at: ${paths}.`));
+    }
+    return apiSuccess(validation.value);
+}
+//# sourceMappingURL=executor.validation.js.map

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

@@ -1,4 +1,11 @@
+/**
+ * @zudojs/api/executor
+ *
+ * Runs an operation through its interceptor pipeline: interceptors first,
+ * then input validation, the handler under its deadline and abort signal,
+ * and output validation.
+ */
 export { APIExecutor } from "./executor.core.js";
-export { normalizeAPIError } from "./executor.core.js";
-export type { APIExecutorOptions } from "./executor.core.js";
+export { normalizeAPIError } from "./executor.normalize.js";
+export type { APIExecutorOptions } from "./executor.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/api/executor/index.js

@@ -1,3 +1,10 @@
+/**
+ * @zudojs/api/executor
+ *
+ * Runs an operation through its interceptor pipeline: interceptors first,
+ * then input validation, the handler under its deadline and abort signal,
+ * and output validation.
+ */
 export { APIExecutor } from "./executor.core.js";
-export { normalizeAPIError } from "./executor.core.js";
+export { normalizeAPIError } from "./executor.normalize.js";
 //# sourceMappingURL=index.js.map

package/dist/api/handler/handler.type.d.ts

@@ -3,10 +3,13 @@ import type { APIContext } from "../context/context.type.js";
  * Handler for an API operation.
  *
  * Receives the operation input and the execution context, and returns
- * the operation output. Input is validated by the executor only when the
- * operation's `input` is a Standard Schema (https://standardschema.dev,
- * implemented by Zod, Valibot, ArkType, …); otherwise it is passed
- * through as-is and the handler must validate it itself.
+ * the operation output. When the operation declares an `input` schema (a
+ * Standard Schema or a `safeParse` schema), the handler receives the
+ * validated value; without one, input is passed through as-is and the
+ * handler must validate it itself.
+ *
+ * `context.signal` aborts when the operation's deadline elapses or the
+ * caller aborts; pass it to anything cancellable.
  */
 export type APIHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: APIContext) => Promise<TOutput>;
 //# sourceMappingURL=handler.type.d.ts.map

package/dist/api/interceptors/interceptor.type.d.ts

@@ -7,13 +7,14 @@ import type { APIOperation } from "../operation/operation.type.js";
 export interface APIExecutionContext<TInput = unknown, TOutput = unknown> {
     readonly operation: APIOperation<TInput, TOutput>;
     /**
-     * The input the handler will receive.
+     * The input as the caller sent it, not yet validated.
      *
      * Writable on purpose: an interceptor may replace it before calling
-     * `next()` (to sanitize, scope to a tenant, or apply a default) and the
-     * handler receives the replacement. The executor reads this field at
-     * handler-invocation time, so a replacement made by any interceptor in
-     * the chain takes effect.
+     * `next()` (to sanitize, scope to a tenant, or apply a default). The
+     * executor reads this field after the last interceptor calls `next()`,
+     * validates it against the operation's `input` schema, and hands the
+     * validated value to the handler, so a replacement made by any
+     * interceptor in the chain takes effect and cannot bypass the schema.
      */
     input: TInput;
     readonly context: APIContext;

package/dist/api/operation/operation.type.d.ts

@@ -1,4 +1,6 @@
 import type { APIHandler } from "../handler/handler.type.js";
+import type { APIOperationHttpOptions } from "../bindings/route/apiRoute.type.js";
+import type { APIInputSchema, DefineOperationWithSchemaOptions, InferAPISchemaOutput } from "./operationSchema.type.js";
 /**
  * Metadata for an API operation.
  */
@@ -13,6 +15,12 @@ export interface APIOperationMetadata {
      */
     readonly timeout?: number;
     readonly idempotent?: boolean;
+    /**
+     * HTTP binding used by `createApiFetchHandler` and `describeApiRoutes`:
+     * method and path template (`"/users/:id"`). Defaults to
+     * `POST /<name>`. Validated by {@link defineOperation}.
+     */
+    readonly http?: APIOperationHttpOptions;
 }
 /**
  * Core API operation contract.
@@ -130,9 +138,18 @@ export declare function freezeOperationMetadata(metadata: APIOperationMetadata |
  * unusable timeout fails here, at startup, rather than on the first
  * request that reaches the operation.
  *
+ * Without type arguments, the handler's `input` is inferred from the
+ * `input` schema (a Standard Schema's output type, or a `safeParse`
+ * schema's success `data`), also inline in `registry.register(...)` or an
+ * operation list. With explicit type arguments
+ * (`defineOperation<TInput, TOutput>(...)`) they are used as given. The
+ * return type never takes part in inference, so a contextual type such as
+ * `AnyAPIOperation` cannot turn the handler's `input` into `never`.
+ *
  * @throws {TypeError} if `name` or `handler` has the wrong type, or if
  * `input` / `output` is set but is not a recognised schema.
  * @throws {RangeError} if `name` or a supplied `timeout` is out of range.
  */
-export declare function defineOperation<TInput = unknown, TOutput = unknown>(options: DefineOperationOptions<TInput, TOutput>): APIOperation<TInput, TOutput>;
+export declare function defineOperation<TSchema extends APIInputSchema, TOutput = unknown>(options: DefineOperationWithSchemaOptions<TSchema, TOutput>): APIOperation<NoInfer<InferAPISchemaOutput<TSchema>>, NoInfer<TOutput>>;
+export declare function defineOperation<TInput = unknown, TOutput = unknown>(options: DefineOperationOptions<TInput, TOutput>): APIOperation<NoInfer<TInput>, NoInfer<TOutput>>;
 //# sourceMappingURL=operation.type.d.ts.map

package/dist/api/operation/operation.type.js

@@ -1,4 +1,5 @@
 import { assertAPISchema } from "../schema/index.js";
+import { assertValidHttpOptions } from "../bindings/route/apiRoute.resolver.js";
 import { DEFAULT_OPERATION_TIMEOUT, MAX_OPERATION_NAME_LENGTH, MAX_OPERATION_TIMEOUT, } from "../constants.js";
 const OPERATION_NAME_PATTERN = /^[A-Za-z0-9._:/-]+$/;
 /**
@@ -93,19 +94,11 @@ export function freezeOperationMetadata(metadata) {
     if (Array.isArray(metadata.tags)) {
         Object.freeze(metadata.tags);
     }
+    if (typeof metadata.http === "object" && metadata.http !== null) {
+        Object.freeze(metadata.http);
+    }
     return Object.freeze(metadata);
 }
-/**
- * Creates a new API operation definition.
- *
- * Validates the definition eagerly — a bad name, a missing handler, or an
- * unusable timeout fails here, at startup, rather than on the first
- * request that reaches the operation.
- *
- * @throws {TypeError} if `name` or `handler` has the wrong type, or if
- * `input` / `output` is set but is not a recognised schema.
- * @throws {RangeError} if `name` or a supplied `timeout` is out of range.
- */
 export function defineOperation(options) {
     assertValidOperationShape(options);
     if (options.timeout !== undefined) {
@@ -114,6 +107,7 @@ export function defineOperation(options) {
     if (options.metadata?.timeout !== undefined) {
         assertValidTimeout(options.metadata.timeout, "Operation metadata.timeout");
     }
+    assertValidHttpOptions(options.metadata?.http, options.name);
     // Explicit field list rather than `...options`: an operation carries
     // exactly the contract fields, never arbitrary extra properties.
     const operation = {

package/dist/api/operation/operationSchema.type.d.ts

@@ -0,0 +1,56 @@
+import type { APIHandler } from "../handler/handler.type.js";
+import type { APIOperationMetadata } from "./operation.type.js";
+/**
+ * A schema the executor can validate against, as a type: a Standard
+ * Schema (a `"~standard"` object with `validate`, implemented by Zod,
+ * Valibot, ArkType, …) or a `safeParse` schema such as `@zudojs/schema`.
+ */
+export type APIInputSchema = {
+    readonly "~standard": {
+        validate(value: unknown): unknown;
+    };
+} | {
+    safeParse(value: unknown): unknown;
+};
+/**
+ * The value a schema produces on success — what the executor hands the
+ * handler after validating the input.
+ *
+ * Read from a Standard Schema's `"~standard".types.output`, or from the
+ * `data` of a `safeParse` success result (`@zudojs/schema`, Zod). A schema
+ * that declares neither yields `unknown`.
+ *
+ * @example
+ * const TodoInput = schema.object({ title: schema.string() });
+ * type T = InferAPISchemaOutput<typeof TodoInput>; // { title: string }
+ */
+export type InferAPISchemaOutput<TSchema> = TSchema extends {
+    readonly "~standard": {
+        readonly types?: infer TTypes;
+    };
+} ? NonNullable<TTypes> extends {
+    readonly output: infer TOut;
+} ? TOut : unknown : TSchema extends {
+    safeParse(...args: never[]): infer TResult;
+} ? Extract<Awaited<TResult>, {
+    readonly success: true;
+}> extends {
+    readonly data: infer TData;
+} ? TData : unknown : unknown;
+/**
+ * Options for a `defineOperation` call whose input type is inferred from
+ * its `input` schema: `handler`'s `input` parameter is the schema's
+ * output type, with no type arguments or annotations needed.
+ */
+export interface DefineOperationWithSchemaOptions<TSchema extends APIInputSchema, TOutput = unknown> {
+    readonly name: string;
+    /** The input schema; the handler's input type is inferred from it. */
+    readonly input: TSchema;
+    /** Output schema; see `APIOperation.output`. */
+    readonly output?: unknown;
+    readonly handler: APIHandler<InferAPISchemaOutput<TSchema>, TOutput>;
+    readonly metadata?: APIOperationMetadata;
+    /** Timeout in milliseconds; see `APIOperation.timeout`. */
+    readonly timeout?: number;
+}
+//# sourceMappingURL=operationSchema.type.d.ts.map

package/dist/api/operation/operationSchema.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=operationSchema.type.js.map

package/dist/index.d.ts

@@ -4,7 +4,9 @@
  * Application-facing API layer for the Zudojs framework.
  *
  * Provides transport-agnostic operation definitions, execution context,
- * interceptors, and result types.
+ * interceptors, and result types — plus bindings that expose the same
+ * operations over HTTP (a web-standard fetch handler), RPC, queues and
+ * the command line.
  *
  * @example
  * ```ts
@@ -39,11 +41,12 @@ export { apiSuccess, apiFailure, isApiSuccess, isApiFailure, } from "./api/resul
 export type { APIErrorOptions } from "./api/errors/index.js";
 export { APIError, APIValidationError, APIAuthenticationError, APIAuthorizationError, APINotFoundError, APIConflictError, APIRateLimitError, APITimeoutError, APIUnavailableError, APIInternalError, APIVersionError, APIOperationNotFoundError, APIDuplicateOperationError, APIIdempotencyError, createAPIError, isAPIError, ErrorCode, } from "./api/errors/index.js";
 export { DEFAULT_OPERATION_TIMEOUT, MAX_OPERATION_TIMEOUT, MAX_INTERCEPTORS, MAX_VALIDATION_ISSUES, MAX_VALIDATION_ISSUE_LENGTH, MAX_OPERATION_NAME_LENGTH, MAX_REQUEST_ID_LENGTH, } from "./api/constants.js";
-export type { APIContext, APIContextKey } from "./api/context/context.type.js";
-export { createAPIContext, createContextKey, isValidRequestId, normalizeRequestId, RequestIdContextKey, CorrelationIdContextKey, TenantIdContextKey, UserIdContextKey, StartTimeContextKey, } from "./api/context/context.type.js";
+export type { APIContext, APIContextKey, APITransportKind, } from "./api/context/context.type.js";
+export { createAPIContext, createContextKey, isValidRequestId, normalizeRequestId, RequestIdContextKey, CorrelationIdContextKey, TenantIdContextKey, UserIdContextKey, StartTimeContextKey, TransportContextKey, } from "./api/context/context.type.js";
 export type { APIHandler } from "./api/handler/handler.type.js";
 export type { AnyAPIOperation, APIOperation, APIOperationMetadata, DefineOperationOptions, } from "./api/operation/operation.type.js";
 export { defineOperation, resolveOperationTimeout, } from "./api/operation/operation.type.js";
+export type { APIInputSchema, DefineOperationWithSchemaOptions, InferAPISchemaOutput, } from "./api/operation/operationSchema.type.js";
 export type { APISchemaIssue, APISchemaResult } from "./api/schema/index.js";
 export { isAPISchema } from "./api/schema/index.js";
 export { APIOperationRegistry } from "./api/registry/index.js";
@@ -51,4 +54,5 @@ export type { APIInterceptor, APIExecutionContext, } from "./api/interceptors/in
 export { createNoopInterceptor } from "./api/interceptors/interceptor.type.js";
 export type { APIExecutorOptions } from "./api/executor/index.js";
 export { APIExecutor, normalizeAPIError } from "./api/executor/index.js";
+export * from "./api/bindings/index.js";
 //# sourceMappingURL=index.d.ts.map