@defjs/core 0.3.3 → 0.4.0-beta.1

package/index.d.ts

@@ -1,194 +1,1650 @@
-declare const HTTP_CONTEXT_TOKEN: unique symbol;
-export type HttpContextToken<T> = (() => T) & {
-	readonly [HTTP_CONTEXT_TOKEN]: () => T;
-};
-export declare function makeHttpContextToken<T>(defaultValue: () => T): HttpContextToken<T>;
-export declare function isHttpContextToken(value: unknown): value is HttpContextToken<unknown>;
-declare const HTTP_CONTEXT: unique symbol;
-export type HttpContext = {
-	set<T>(token: HttpContextToken<T>, value: T): HttpContext;
-	get<T>(token: HttpContextToken<T>): T;
-	del(token: HttpContextToken<unknown>): HttpContext;
-	has(token: HttpContextToken<unknown>): boolean;
-	keys(): IterableIterator<HttpContextToken<unknown>>;
-	get length(): number;
-	readonly [HTTP_CONTEXT]: Map<HttpContextToken<unknown>, unknown>;
-};
-export declare function makeHttpContext(): HttpContext;
-export declare function makeHttpContext(entries?: readonly (readonly [
-	HttpContextToken<unknown>,
-	unknown
-])[]): HttpContext;
-export declare function makeHttpContext(context?: HttpContext): HttpContext;
-export type ValidatorFn<T = unknown> = (value: T) => void;
-export type AsyncValidatorFn<T = unknown> = (value: T) => Promise<void>;
-export declare const required: ValidatorFn;
-export declare const requiredTrue: ValidatorFn;
-export declare const minLength: (min: number) => ValidatorFn;
-export declare const maxLength: (max: number) => ValidatorFn;
-export declare const min: (min: number) => ValidatorFn;
-export declare const max: (max: number) => ValidatorFn;
-export declare const pattern: (pattern: RegExp) => ValidatorFn;
-declare const FIELD: unique symbol;
-declare enum FieldType {
-	Json = 0,
-	Query = 1,
-	Param = 2,
-	Header = 3,
-	Form = 4,
-	Body = 5,
-	UrlForm = 6
-}
-export interface FieldMetadata<T = undefined> {
-	required: boolean;
-	alias: Map<FieldType, string | undefined>;
-	validators: ValidatorFn<T>[];
-	asyncValidator: AsyncValidatorFn<T>[];
-}
-export type Field<T = undefined> = (() => T) & {
-	withJson(alias?: string): Field<T>;
-	withForm(alias?: string): Field<T>;
-	withQuery(alias?: string): Field<T>;
-	withParam(alias?: string): Field<T>;
-	withHeader(alias?: string): Field<T>;
-	withUrlForm(alias?: string): Field<T>;
-	withBody(): Field<T>;
-	withValidators(...fn: ValidatorFn<T>[]): Field<T>;
-	withAsyncValidators(...fn: AsyncValidatorFn<T>[]): Field<T>;
-	readonly [FIELD]: FieldMetadata<T>;
-};
-export declare function field(): Field;
-export declare function field<T>(): Field<T | undefined>;
-export declare function field<T>(defaultValue: T): Field<T>;
-export declare function doValid<T>(validators: (ValidatorFn<T> | AsyncValidatorFn<T>)[], value: T): Promise<void>;
-export declare function isField(value: unknown): value is Field;
-export declare function isFieldGroup(value: unknown): value is Record<PropertyKey, Field>;
+//#region src/internal/http_request.d.ts
+/**
+ * How the HTTP response body should be parsed before struct validation.
+ * Chosen from the declared struct kind: string is text, blob and file are blobs,
+ * arrayBuffer is bytes, and every other kind is JSON.
+ */
+type HttpResponseType = 'arraybuffer' | 'blob' | 'json' | 'text';
+/**
+ * Progress snapshot for upload or download callbacks.
+ * Mirrors the familiar `ProgressEvent` shape (`loaded` / `total` / `lengthComputable`).
+ */
+interface HttpProgressEvent {
+  readonly lengthComputable: boolean;
+  readonly loaded: number;
+  readonly total: number;
+}
+/**
+ * Callback invoked as request bytes are uploaded or response bytes are downloaded.
+ */
+type HttpProgressFn = (event: HttpProgressEvent) => Promise<void> | void;
+/**
+ * Normalized outgoing HTTP request used by handlers, interceptors, and `fetchHandler`.
+ *
+ * After the request builder runs, `body` is already the wire value — for JSON that means a
+ * **JSON text string**. Sign HMAC / digests against that string (or other final bytes), not the
+ * original struct input.
+ */
+interface HttpRequest {
+  abort?: AbortSignal;
+  baseEndpoint?: string;
+  body?: Blob | ArrayBuffer | FormData | URLSearchParams | ReadableStream<Uint8Array> | object | string | number | boolean | null;
+  bodyContentType?: string | null;
+  /** @internal Tracks which body value produced bodyContentType so interceptors cannot leave stale metadata behind. */
+  bodyContentTypeSource?: unknown;
+  downloadProgress?: HttpProgressFn;
+  endpoint: string;
+  headers?: Headers;
+  method: string;
+  /** Static, low-cardinality endpoint identity for telemetry and diagnostics. */
+  operation?: string;
+  queryParams?: URLSearchParams;
+  queryString?: string;
+  /**
+   * Representation for a 2xx body, derived from the endpoint `output` struct kind.
+   * Set only when `output` is declared. Interceptors that short-circuit with `makeResponse`
+   * read this to match the transport. Must not be changed. `undefined` leaves the 2xx body unread.
+   */
+  readonly responseType?: HttpResponseType;
+  /**
+   * Representation for a non-2xx body, derived from the endpoint `error` struct kind.
+   * Set only when `error` is declared. Must not be changed. `undefined` leaves the non-2xx body
+   * unread and does not fall back to `responseType`.
+   */
+  readonly errorResponseType?: HttpResponseType;
+  timeout?: number;
+  uploadProgress?: HttpProgressFn;
+  withCredentials?: boolean;
+  xsrf?: {
+    cookieName: string;
+    headerName: string;
+    tokenProvider?: (context: {
+      request: HttpRequest;
+    }) => string | null | undefined;
+  };
+}
+//#endregion
+//#region src/internal/http_response.d.ts
+declare const HTTP_RESPONSE: unique symbol;
+/**
+ * Wire-shape HTTP response returned by transports and accepted by interceptors.
+ * `ok` is true for status codes in the 2xx range. A transport failure is a fault, never a response.
+ */
+type HttpResponse<R> = {
+  readonly [HTTP_RESPONSE]: true;
+  readonly url: string;
+  readonly status: number;
+  readonly statusText: string;
+  readonly headers: Headers;
+  /** Absent when no body was present. JSON `null` stays `null`. */
+  readonly body: R | null | undefined;
+  readonly ok: boolean;
+};
+/**
+ * Response metadata, available whenever a response reached the client.
+ *
+ * Carries no body: a body only exists once a declared struct decoded it.
+ */
+type HttpMeta = {
+  readonly headers: Headers;
+  readonly ok: boolean;
+  readonly status: number;
+  readonly statusText: string;
+  readonly url: string;
+};
+/**
+ * Response whose body decoded successfully against a declared struct.
+ *
+ * Reaching this type is the proof that decoding happened; a failed decode is reported
+ * as a fault carrying `HttpMeta` alone.
+ */
+type DecodedResponse<TBody> = HttpMeta & {
+  readonly body: TBody;
+};
+/**
+ * Fields accepted by `makeResponse` when building a synthetic `HttpResponse` (for example in interceptors).
+ */
+type MakeResponseOptions<R> = {
+  status?: number;
+  statusText?: string;
+  url?: string;
+  headers?: Headers;
+  body?: R | null;
+  request?: HttpRequest;
+};
+/**
+ * Build an `HttpResponse` value without performing a network call.
+ * Useful in interceptors that short-circuit `next`, and in tests.
+ *
+ * @param options - Status, headers, body, and an optional request to copy headers/url from; defaults yield status `0`.
+ * @returns An `HttpResponse` with `ok` derived from the status code.
+ */
+export declare function makeResponse<R>(options?: MakeResponseOptions<R>): HttpResponse<R>;
+//#endregion
+//#region src/error/cause.d.ts
+/** Shared cause/message sentinel for aborted requests. */
 export declare const ERR_ABORTED: Error;
+/** Shared cause/message sentinel for timed-out requests. */
 export declare const ERR_TIMEOUT: Error;
-export declare const ERR_NETWORK: Error;
-export declare const ERR_NOT_FOUND_HANDLER: Error;
-export declare const ERR_OBSERVE: Error;
-export declare const ERR_NOT_SET_ALIAS: Error;
-export declare const ERR_UNSUPPORTED_FIELD_TYPE: Error;
-export declare const ERR_INVALID_CLIENT: Error;
-export declare const ERR_NOT_FOUND_GLOBAL_CLIENT: Error;
-export declare const ERR_INVALID_HTTP_CONTEXT_TOKEN: Error;
-export declare const ERR_UNKNOWN: Error;
-export type HttpResponseBody = string | ArrayBuffer | Blob | object | null;
-export type HttpResponse<R> = {
-	readonly url: string;
-	readonly status: number;
-	readonly statusText: string;
-	readonly headers: Headers;
-	readonly body: R | null;
-	readonly error?: Error | string | unknown;
-};
-export type MakeResponseOptions<R> = {
-	status?: number;
-	statusText?: string;
-	url?: string;
-	headers?: Headers;
-	body?: R | null;
-	error?: Error | string | unknown;
-};
-export type InterceptorFn = (req: HttpRequest, next: HttpHandler) => Promise<HttpResponse<unknown>>;
-export type BasicCredential = {
-	username: string;
-	password: string;
-};
-export type BasicAuthInterceptorOptions = {
-	encode?: (credential: BasicCredential) => string;
-};
-export declare function basicAuthInterceptor(fn: () => BasicCredential, options?: BasicAuthInterceptorOptions): InterceptorFn;
-export type HttpResponseType = "arraybuffer" | "blob" | "json" | "text";
-export interface HttpProgressEvent {
-	/**
-	 * Indicates whether the resources associated with Progress have a computable length.
-	 * Otherwise, the Progress.total attribute will be a meaningless value.
-	 */
-	readonly lengthComputable: boolean;
-	/** Indicates the workload of the underlying process. */
-	readonly loaded: number;
-	/**
-	 * The total size of the data being processed or transmitted.
-	 * If the Progress.lengthComputable attribute is false, this value is meaningless and should be ignored.
-	 */
-	readonly total: number;
-}
-export type HttpProgressFn = (event: HttpProgressEvent) => void;
-export type TransformResponseFn<Output = unknown> = (response: HttpResponse<unknown>) => Output;
-export interface HttpRequest {
-	host?: string;
-	method: string;
-	endpoint: string;
-	body?: Blob | ArrayBuffer | FormData | URLSearchParams | object | string | number | boolean | null;
-	headers?: Headers;
-	queryParams?: URLSearchParams;
-	/** default：json */
-	responseType?: HttpResponseType;
-	context?: HttpContext;
-	timeout?: number;
-	withCredentials?: boolean;
-	/** when use fetch handler, no upload progress */
-	uploadProgress?: HttpProgressFn;
-	downloadProgress?: HttpProgressFn;
-	abort?: AbortSignal;
-}
-export type RequestInputValue<T> = T extends {
-	[K in keyof T]: Field<any>;
-} ? {
-	[K in keyof T]: T[K] extends Field<infer V> ? V : never;
+//#endregion
+//#region src/struct/errors.d.ts
+/**
+ * Optional callback that rewrites a `StructIssue` message before it is stored.
+ *
+ * Return a string to replace the default message, or `undefined` to keep it.
+ *
+ * @param issue - Issue about to be recorded.
+ * @returns Replacement message, or `undefined` to keep the default.
+ */
+type ErrorMap = (issue: StructIssue) => string | undefined;
+/**
+ * Aggregate of one or more `StructIssue`s from a failed parse.
+ *
+ * Use `format()`, `flatten()`, or `prettify()` to present issues to callers.
+ */
+export declare class StructError extends Error {
+  /** Issues collected for this failure, in encounter order. */
+  readonly issues: StructIssue[];
+  /**
+   * @param issues - Non-empty list of parse issues (empty lists still produce a generic message).
+   */
+  constructor(issues: StructIssue[]);
+  /**
+   * Build a nested error tree keyed by path segments.
+   *
+   * @returns A `FormattedStructError` with `_errors` arrays at each node.
+   */
+  format(): FormattedStructError;
+  /**
+   * Split issues into root `formErrors` and first-segment `fieldErrors`.
+   *
+   * @returns Flat bags suitable for form libraries.
+   */
+  flatten(): FlattenedStructError;
+  /**
+   * Render a multi-line, human-readable summary of all issues.
+   *
+   * @returns One `× path: message` line per issue.
+   */
+  prettify(): string;
+}
+//#endregion
+//#region src/struct/symbols.d.ts
+/**
+ * Enumerable tag on objects produced while parsing endpoint input.
+ * Response decoding and `struct.parse` leave it unset. Internal to the outbound encoder.
+ *
+ * @internal
+ */
+declare const STRUCT: unique symbol;
+//#endregion
+//#region src/struct/types.d.ts
+type Path = Array<number | string>;
+/**
+ * Error-first parse tuple from `struct.parse`.
+ *
+ * On success the error is `null` and `value` is the parsed output. On failure
+ * the error is a `StructError` and `value` is always `undefined`.
+ */
+type ParseResult<O> = [error: null, value: O] | [error: StructError, value: undefined];
+type LiteralValue = boolean | null | number | string;
+interface StructTypes<Input = unknown, Output = unknown, OptionalOut extends boolean = false> {
+  input: Input;
+  optionalOut: OptionalOut extends true ? true : undefined;
+  output: Output;
+}
+/**
+ * Minimal structural brand carried by every struct instance.
+ *
+ * `_struct` holds input/output phantom types used by `Infer` and `StructInput`.
+ */
+interface StructLike<I = unknown, O = unknown, OO extends boolean = boolean> {
+  readonly _struct: StructTypes<I, O, OO>;
+}
+type OptionalOutputStruct = {
+  readonly _struct: {
+    readonly optionalOut: true;
+  };
+};
+/**
+ * A single validation failure produced while parsing a struct.
+ */
+interface StructIssue {
+  /** Machine-readable failure category. */
+  code: 'custom' | 'invalid_enum' | 'invalid_intersection' | 'invalid_literal' | 'invalid_type' | 'invalid_union' | 'missing_key';
+  /** Human-readable description of the expected type or value. */
+  expected: string;
+  /** Final message after optional `ErrorMap` rewriting. */
+  message: string;
+  /** Path from the parse root to the failing location. */
+  path: Path;
+  /** Value that failed validation at `path`. */
+  received: unknown;
+}
+/**
+ * Nested error tree returned by `StructError.format()`.
+ *
+ * Leaf messages live under `_errors`; nested keys mirror the failing path.
+ */
+interface FormattedStructError {
+  _errors: string[];
+  [key: string]: FormattedStructError | string[];
+}
+/**
+ * Flat field/form error bags returned by `StructError.flatten()`.
+ */
+interface FlattenedStructError {
+  /** Messages whose path is empty (root-level issues). */
+  formErrors: string[];
+  /** Messages keyed by the first path segment. */
+  fieldErrors: {
+    [key: string]: string[];
+  };
+}
+/**
+ * Chainable modifiers available on every `Struct` instance.
+ */
+interface StructMethods<I, O, OO extends boolean> {
+  /**
+   * Override the external wire name for this field without changing the TypeScript property name.
+   *
+   * @param name - Wire / protocol field name.
+   * @returns The same struct branded with the alias.
+   */
+  alias(name: string): this;
+  /**
+   * Allow `null` in addition to the current input and output types.
+   *
+   * @returns A struct that accepts and emits `null`.
+   */
+  null(): Struct<I | null, O | null, OO>;
+  /**
+   * Alias for {@link StructMethods.null}.
+   *
+   * @returns A struct that accepts and emits `null`.
+   */
+  nullable(): Struct<I | null, O | null, OO>;
+  /**
+   * Allow `null` or `undefined`, marking the field optional in object output.
+   *
+   * @returns A struct that accepts `null`/`undefined` and treats the field as optional.
+   */
+  nullish(): Struct<I | null | undefined, O | null | undefined, true>;
+  /**
+   * Allow `undefined`, marking the field optional in object shapes.
+   *
+   * @returns A struct that accepts `undefined` and treats the field as optional.
+   */
+  optional(): Struct<I | undefined, O | undefined, true>;
+}
+/**
+ * Public struct contract: modifiers plus the `_struct` type brand.
+ *
+ * Built via the `struct` facade (`struct.string()`, `struct.object()`, …).
+ */
+type Struct<Input = unknown, Output = Input, OptionalOut extends boolean = false> = StructMethods<Input, Output, OptionalOut> & StructLike<Input, Output, OptionalOut>;
+type PresentValue = NonNullable<unknown>;
+declare const carriedStruct: unique symbol;
+/** Keeps the struct that a nullish modifier wrapped, so builders still see its fields. */
+type CarriedStruct<T> = {
+  readonly [carriedStruct]: T;
+};
+declare const unionStructOptions: unique symbol;
+declare const intersectionStructOptions: unique symbol;
+declare const discriminatedUnionOptions: unique symbol;
+interface PreservedStruct<T, I, O, OO extends boolean> extends Struct<I, O, OO>, CarriedStruct<T> {
+  null(): PreservedStruct<T, I | null, O | null, OO>;
+  nullable(): PreservedStruct<T, I | null, O | null, OO>;
+  nullish(): PreservedStruct<T, I | null | undefined, O | null | undefined, true>;
+  optional(): PreservedStruct<T, I | undefined, O | undefined, true>;
+}
+/**
+ * Broad struct constraint for endpoint and client generics.
+ *
+ * Prefer a concrete `Struct<…>` when you need precise input/output inference.
+ */
+type AnyStruct = Struct<any, any, boolean>;
+/**
+ * Infer the accepted input type of a struct.
+ *
+ * @typeParam T - A struct-like value with a `_struct.input` brand.
+ */
+type StructInput<T> = T extends {
+  readonly _struct: {
+    readonly input: unknown;
+  };
+} ? T['_struct']['input'] : never;
+type StructOutput<T> = T extends {
+  readonly _struct: {
+    readonly output: unknown;
+  };
+} ? T['_struct']['output'] : never;
+/**
+ * Infer the parsed output type of a struct (alias of the internal output brand).
+ *
+ * @typeParam T - A struct-like value with a `_struct.output` brand.
+ */
+type Infer<T> = StructOutput<T>;
+type FieldOutput<S> = S extends StructLike<unknown, unknown, boolean> ? S extends OptionalOutputStruct ? Exclude<S['_struct']['output'], undefined> : S['_struct']['output'] : never;
+type Simplify<T> = { [K in keyof T]: T[K]; } & {};
+type ObjectShape = {
+  [key: string]: any;
+};
+type ObjectInput<T extends ObjectShape> = Simplify<{ -readonly [K in keyof T as T[K] extends OptionalOutputStruct ? never : K]: T[K]['_struct']['input']; } & { -readonly [K in keyof T as T[K] extends OptionalOutputStruct ? K : never]?: Exclude<T[K]['_struct']['input'], undefined>; }>;
+type ObjectOutput<T extends ObjectShape> = Simplify<{ -readonly [K in keyof T as T[K] extends OptionalOutputStruct ? never : K]: FieldOutput<T[K]>; } & { -readonly [K in keyof T as T[K] extends OptionalOutputStruct ? K : never]?: FieldOutput<T[K]>; }>;
+type TupleInput<T extends readonly StructLike<unknown, unknown, boolean>[]> = { -readonly [K in keyof T]: StructInput<T[K]>; };
+type TupleOutput<T extends readonly StructLike<unknown, unknown, boolean>[]> = { -readonly [K in keyof T]: StructOutput<T[K]>; };
+type UnionOutput<T extends readonly StructLike<unknown, unknown, boolean>[]> = Exclude<StructOutput<T[number]>, undefined>;
+type UnionInput<T extends readonly StructLike<unknown, unknown, boolean>[]> = Exclude<StructInput<T[number]>, undefined>;
+type IntersectionInputValue<T extends readonly StructLike<unknown, unknown, boolean>[]> = T extends readonly [infer Head extends StructLike<unknown, unknown, boolean>, ...infer Tail extends StructLike<unknown, unknown, boolean>[]] ? StructInput<Head> & IntersectionInputValue<Tail> : unknown;
+type IntersectionInput<T extends readonly StructLike<unknown, unknown, boolean>[]> = Exclude<IntersectionInputValue<T>, undefined>;
+type IntersectionOutputValue<T extends readonly StructLike<unknown, unknown, boolean>[]> = T extends readonly [infer Head extends StructLike<unknown, unknown, boolean>, ...infer Tail extends StructLike<unknown, unknown, boolean>[]] ? StructOutput<Head> & IntersectionOutputValue<Tail> : unknown;
+type IntersectionOutput<T extends readonly StructLike<unknown, unknown, boolean>[]> = Exclude<IntersectionOutputValue<T>, undefined>;
+type StringStruct = Struct<string, string>;
+type NumberStruct = Struct<number, number>;
+type UnknownStruct = Struct<PresentValue, unknown>;
+type ArrayInput<S extends StructLike<unknown, unknown, boolean>> = StructInput<S>[];
+type ArrayOutput<S extends StructLike<unknown, unknown, boolean>> = StructOutput<S>[];
+interface ArrayStructTypes<S extends StructLike<unknown, unknown, boolean>> extends StructTypes<ArrayInput<S>, ArrayOutput<S>, false> {
+  input: ArrayInput<S>;
+  optionalOut: undefined;
+  output: ArrayOutput<S>;
+}
+interface ArrayStruct<S extends StructLike<unknown, unknown, boolean>> extends StructMethods<ArrayInput<S>, ArrayOutput<S>, false>, StructLike<ArrayInput<S>, ArrayOutput<S>, false> {
+  readonly _struct: ArrayStructTypes<S>;
+  null(): PreservedStruct<ArrayStruct<S>, ArrayInput<S> | null, ArrayOutput<S> | null, false>;
+  nullable(): PreservedStruct<ArrayStruct<S>, ArrayInput<S> | null, ArrayOutput<S> | null, false>;
+  nullish(): PreservedStruct<ArrayStruct<S>, ArrayInput<S> | null | undefined, ArrayOutput<S> | null | undefined, true>;
+  optional(): PreservedStruct<ArrayStruct<S>, ArrayInput<S> | undefined, ArrayOutput<S> | undefined, true>;
+}
+interface ObjectStructTypes<T extends ObjectShape> extends StructTypes<ObjectInput<T>, ObjectOutput<T>, false> {
+  input: ObjectInput<T>;
+  optionalOut: undefined;
+  output: ObjectOutput<T>;
+}
+/**
+ * Object-shaped struct produced by `struct.object(shape)`.
+ *
+ * Field presence follows each field's optional/nullish modifiers; wire names
+ * can differ from TypeScript keys via `.alias()`.
+ */
+interface ObjectStruct<T extends ObjectShape> extends StructMethods<ObjectInput<T>, ObjectOutput<T>, false>, StructLike<ObjectInput<T>, ObjectOutput<T>, false> {
+  readonly _struct: ObjectStructTypes<T>;
+  null(): PreservedStruct<ObjectStruct<T>, ObjectInput<T> | null, ObjectOutput<T> | null, false>;
+  nullable(): PreservedStruct<ObjectStruct<T>, ObjectInput<T> | null, ObjectOutput<T> | null, false>;
+  nullish(): PreservedStruct<ObjectStruct<T>, ObjectInput<T> | null | undefined, ObjectOutput<T> | null | undefined, true>;
+  optional(): PreservedStruct<ObjectStruct<T>, ObjectInput<T> | undefined, ObjectOutput<T> | undefined, true>;
+}
+declare const recordValueStruct: unique symbol;
+declare const tupleItemStructs: unique symbol;
+type RecordInput<S extends StructLike<unknown, unknown, boolean>> = {
+  [key: string]: StructInput<S>;
+};
+type RecordOutput<S extends StructLike<unknown, unknown, boolean>> = {
+  [key: string]: FieldOutput<S>;
+};
+/**
+ * Value struct carried by `struct.record`.
+ * Tagged parsing stores this struct on the record object itself. `null` and `undefined` are not tagged.
+ */
+interface RecordStruct<S extends StructLike<unknown, unknown, boolean>> extends Struct<RecordInput<S>, RecordOutput<S>> {
+  readonly [recordValueStruct]: S;
+  null(): PreservedStruct<RecordStruct<S>, RecordInput<S> | null, RecordOutput<S> | null, false>;
+  nullable(): PreservedStruct<RecordStruct<S>, RecordInput<S> | null, RecordOutput<S> | null, false>;
+  nullish(): PreservedStruct<RecordStruct<S>, RecordInput<S> | null | undefined, RecordOutput<S> | null | undefined, true>;
+  optional(): PreservedStruct<RecordStruct<S>, RecordInput<S> | undefined, RecordOutput<S> | undefined, true>;
+}
+/** Item structs carried by `struct.tuple`, so builders tag each position. The tuple itself is not tagged. */
+interface TupleStruct<T extends readonly StructLike<unknown, unknown, boolean>[]> extends Struct<TupleInput<T>, TupleOutput<T>> {
+  readonly [tupleItemStructs]: T;
+  null(): PreservedStruct<TupleStruct<T>, TupleInput<T> | null, TupleOutput<T> | null, false>;
+  nullable(): PreservedStruct<TupleStruct<T>, TupleInput<T> | null, TupleOutput<T> | null, false>;
+  nullish(): PreservedStruct<TupleStruct<T>, TupleInput<T> | null | undefined, TupleOutput<T> | null | undefined, true>;
+  optional(): PreservedStruct<TupleStruct<T>, TupleInput<T> | undefined, TupleOutput<T> | undefined, true>;
+}
+interface UnionStruct<T extends readonly StructLike<unknown, unknown, boolean>[]> extends Struct<UnionInput<T>, UnionOutput<T>> {
+  readonly [unionStructOptions]: T;
+  null(): PreservedStruct<UnionStruct<T>, UnionInput<T> | null, UnionOutput<T> | null, false>;
+  nullable(): PreservedStruct<UnionStruct<T>, UnionInput<T> | null, UnionOutput<T> | null, false>;
+  nullish(): PreservedStruct<UnionStruct<T>, UnionInput<T> | null | undefined, UnionOutput<T> | null | undefined, true>;
+  optional(): PreservedStruct<UnionStruct<T>, UnionInput<T> | undefined, UnionOutput<T> | undefined, true>;
+}
+interface DiscriminatedUnionStruct<TOptions extends readonly ObjectStruct<ObjectShape>[]> extends Struct<StructInput<TOptions[number]>, StructOutput<TOptions[number]>> {
+  readonly [discriminatedUnionOptions]: TOptions;
+  null(): PreservedStruct<DiscriminatedUnionStruct<TOptions>, StructInput<TOptions[number]> | null, StructOutput<TOptions[number]> | null, false>;
+  nullable(): PreservedStruct<DiscriminatedUnionStruct<TOptions>, StructInput<TOptions[number]> | null, StructOutput<TOptions[number]> | null, false>;
+  nullish(): PreservedStruct<DiscriminatedUnionStruct<TOptions>, StructInput<TOptions[number]> | null | undefined, StructOutput<TOptions[number]> | null | undefined, true>;
+  optional(): PreservedStruct<DiscriminatedUnionStruct<TOptions>, StructInput<TOptions[number]> | undefined, StructOutput<TOptions[number]> | undefined, true>;
+}
+interface IntersectionStruct<T extends readonly StructLike<unknown, unknown, boolean>[]> extends Struct<IntersectionInput<T>, IntersectionOutput<T>> {
+  readonly [intersectionStructOptions]: T;
+  null(): PreservedStruct<IntersectionStruct<T>, IntersectionInput<T> | null, IntersectionOutput<T> | null, false>;
+  nullable(): PreservedStruct<IntersectionStruct<T>, IntersectionInput<T> | null, IntersectionOutput<T> | null, false>;
+  nullish(): PreservedStruct<IntersectionStruct<T>, IntersectionInput<T> | null | undefined, IntersectionOutput<T> | null | undefined, true>;
+  optional(): PreservedStruct<IntersectionStruct<T>, IntersectionInput<T> | undefined, IntersectionOutput<T> | undefined, true>;
+}
+//#endregion
+//#region src/error/types.d.ts
+/**
+ * Every failure Defjs reports, as one closed set of codes.
+ *
+ * The prefix before the first `_` is the class; there is no separate `kind` field.
+ * Read the prefix for coarse triage and the whole code for an exact case:
+ *
+ * | Class  | Meaning                                                        |
+ * | ------ | -------------------------------------------------------------- |
+ * | `HTTP` | The peer answered with a non-2xx status.                        |
+ * | `REQ`  | The request never left: input, execute options, or build.       |
+ * | `NET`  | No usable response: cancel, timeout, connect, truncated body.   |
+ * | `RES`  | A response arrived but could not be read as declared.           |
+ * | `EXT`  | Code you attached to the pipeline threw.                        |
+ * | `CAP`  | A declared buffer or queue limit was exceeded.                  |
+ * | `ENV`  | The host runtime lacks a required capability.                   |
+ *
+ * The set is closed on purpose: it keeps `switch (fault.code)` exhaustive. Extensions
+ * report their own detail through `cause`, not through a new code.
+ */
+export type FaultCode = 'CAP_BUFFER_EXCEEDED' | 'CAP_QUEUE_OVERFLOW' | 'ENV_UNSUPPORTED' | 'EXT_HOOK_FAILED' | 'EXT_INTERCEPTOR_FAILED' | 'EXT_OBSERVER_FAILED' | 'HTTP_STATUS' | 'NET_ABORTED' | 'NET_BODY_INCOMPLETE' | 'NET_TIMEOUT' | 'NET_UNREACHABLE' | 'REQ_BUILD_FAILED' | 'REQ_INPUT_INVALID' | 'REQ_OPTIONS_INVALID' | 'RES_DECODE_FAILED' | 'RES_MEDIA_TYPE_INVALID' | 'RES_STRUCT_MISMATCH';
+/**
+ * The class of a fault code: the segment before its first `_`.
+ *
+ * @typeParam C - A `FaultCode`, or a union of them.
+ */
+export type FaultClass<C extends string> = C extends `${infer TClass}_${string}` ? TClass : never;
+/** Codes whose fault carries response metadata but no body. */
+export type DecodeFaultCode = 'RES_DECODE_FAILED' | 'RES_MEDIA_TYPE_INVALID' | 'RES_STRUCT_MISMATCH';
+/** Codes whose fault may never have reached a response. */
+export type PreflightFaultCode = Exclude<FaultCode, DecodeFaultCode | 'HTTP_STATUS'>;
+type ErrorBody<TErr> = [TErr] extends [undefined] ? undefined : Infer<TErr>;
+/**
+ * `HttpStatusFault` expressed by its decoded body type instead of the struct that produced it.
+ *
+ * Factories work in decoded values, so they use this form; endpoint types use
+ * `HttpStatusFault` and let `Infer` bridge the two.
+ */
+export type HttpStatusFaultOf<TData> = Error & {
+  code: 'HTTP_STATUS';
+  data: TData;
+  response: [TData] extends [undefined] ? HttpMeta : DecodedResponse<TData>;
+  status: number;
+};
+/**
+ * The peer answered with a non-2xx status and the declared `error` struct decoded its body.
+ *
+ * Omitting `error` skips decoding, which leaves `data` as `undefined` and `response`
+ * without a `body` field.
+ */
+export type HttpStatusFault<TErr extends AnyStruct | undefined = undefined> = HttpStatusFaultOf<ErrorBody<TErr>>;
+/**
+ * A response arrived but could not be read as declared.
+ *
+ * `response` is metadata only: a body is a decoded value, and decoding is what failed.
+ * The offending detail lives on `cause` (a `StructError` for a struct mismatch, the
+ * parser failure for an unreadable representation).
+ */
+export type DecodeFault = Error & {
+  cause: unknown;
+  code: DecodeFaultCode;
+  response: HttpMeta;
+  status: number;
+};
+/**
+ * A failure that may have happened before any response existed.
+ *
+ * `response` is present only where the transport already had metadata to report,
+ * such as a body that truncated mid-download.
+ */
+export type PreflightFault = Error & {
+  cause?: unknown;
+  code: PreflightFaultCode;
+  response?: HttpMeta;
+};
+/**
+ * Any failure returned by `client.execute`, expressed by its decoded error-body type.
+ *
+ * @typeParam TData - The decoded `error` body, or `undefined` when no error struct was declared.
+ */
+export type FaultOf<TData = undefined> = DecodeFault | HttpStatusFaultOf<TData> | PreflightFault;
+/**
+ * Any failure returned by `client.execute`, discriminated by `code`.
+ *
+ * @typeParam TErr - The endpoint's declared `error` struct, or `undefined` when it declares none.
+ */
+export type Fault<TErr extends AnyStruct | undefined = undefined> = FaultOf<ErrorBody<TErr>>;
+/**
+ * Any fault at all, whatever its decoded error-body type.
+ *
+ * Use it for handlers that classify faults without caring which endpoint produced them.
+ * Prefer `Fault<typeof yourErrorStruct>` where the body type matters.
+ */
+export type AnyFault = DecodeFault | HttpStatusFaultOf<undefined> | HttpStatusFaultOf<unknown> | PreflightFault;
+//#endregion
+//#region src/error/factory.d.ts
+/**
+ * Build the fault for a non-2xx response whose body decoded against the declared `error` struct.
+ *
+ * @param response - The response, carrying the decoded body.
+ * @returns An `HTTP_STATUS` fault whose `data` is that body.
+ */
+export declare function createHttpStatusFault<TData>(response: DecodedResponse<TData>): HttpStatusFaultOf<TData>;
+/**
+ * Build the fault for a non-2xx response that was never decoded, because the endpoint
+ * declared no `error` struct.
+ *
+ * @param response - Metadata of the response; no body was read.
+ * @returns An `HTTP_STATUS` fault whose `data` is `undefined`.
+ */
+export declare function createUndecodedHttpStatusFault(response: HttpMeta): HttpStatusFaultOf<undefined>;
+/**
+ * Build the fault for a response that arrived but could not be read as declared.
+ *
+ * Carries metadata only: a body is a decoded value, and decoding is what failed.
+ *
+ * @param code - Which read step failed.
+ * @param cause - Underlying parser or struct failure.
+ * @param response - Metadata of the response that could not be read.
+ * @returns A decode fault with no body.
+ */
+export declare function createDecodeFault(code: DecodeFaultCode, cause: unknown, response: HttpMeta): DecodeFault;
+/**
+ * Build a fault for a failure that may have happened before any response existed.
+ *
+ * @param code - The specific failure.
+ * @param cause - Underlying value, when there is one; the code becomes the message otherwise.
+ * @param response - Metadata, only where the transport already had some to report.
+ * @returns A preflight fault.
+ */
+export declare function createPreflightFault(code: PreflightFaultCode, cause?: unknown, response?: HttpMeta): PreflightFault;
+/**
+ * Build a `NET_*` fault, choosing the code from the shape of `cause`.
+ *
+ * Recognizes the shared abort/timeout sentinels and the platform's `AbortError`/`TimeoutError`;
+ * anything else is reported as unreachable.
+ *
+ * @param cause - Underlying cancellation, timeout, or transport failure.
+ * @param response - Metadata, only where the transport already had some to report.
+ * @returns A `NET_ABORTED`, `NET_TIMEOUT`, or `NET_UNREACHABLE` fault.
+ */
+export declare function createNetworkFault(cause: unknown, response?: HttpMeta): PreflightFault;
+//#endregion
+//#region src/struct/constructors.d.ts
+declare function createStringStruct(): StringStruct;
+declare function createNumberStruct(): NumberStruct;
+declare function createBooleanStruct(): Struct<boolean, boolean>;
+declare function createNullStruct(): Struct<null, null>;
+declare function createAnyStruct(): Struct<PresentValue, any>;
+declare function createUnknownStruct(): UnknownStruct;
+declare function createLiteralStruct<const T extends LiteralValue>(value: T): Struct<T, T>;
+declare function createArrayStruct<S extends StructLike<unknown, unknown, boolean>>(item: S): ArrayStruct<S>;
+declare function createObjectStruct<T extends ObjectShape>(shape: T): ObjectStruct<T>;
+declare function createUrlencodedBodyStruct<T extends ObjectShape>(shape: T): ObjectStruct<T>;
+declare function createFormDataBodyStruct<T extends ObjectShape>(shape: T): ObjectStruct<T>;
+declare function createRecordStruct<S extends StructLike<unknown, unknown, boolean>>(value: S): RecordStruct<S>;
+declare function createTupleStruct<const T extends readonly [StructLike<unknown, unknown, boolean>, ...StructLike<unknown, unknown, boolean>[]]>(items: T): TupleStruct<T>;
+type RequiredDiscriminatorOption<TDiscriminator extends string, TOption extends ObjectStruct<ObjectShape>> = TOption extends ObjectStruct<infer TShape> ? TDiscriminator extends keyof TShape ? TShape[TDiscriminator] extends StructLike<infer TInput, unknown, false> ? undefined extends TInput ? never : null extends TInput ? [TInput] extends [null] ? TOption : never : TOption : never : never : never;
+type RequiredDiscriminatorOptions<TDiscriminator extends string, TOptions extends readonly ObjectStruct<ObjectShape>[]> = { [K in keyof TOptions]: TOptions[K] extends ObjectStruct<ObjectShape> ? RequiredDiscriminatorOption<TDiscriminator, TOptions[K]> : never; };
+declare function createDiscriminatedUnionStruct<const TDiscriminator extends string, const TOptions extends readonly [ObjectStruct<ObjectShape>, ...ObjectStruct<ObjectShape>[]]>(discriminator: TDiscriminator, options: TOptions & RequiredDiscriminatorOptions<TDiscriminator, TOptions>): DiscriminatedUnionStruct<TOptions>;
+declare function createBlobStruct(): Struct<Blob, Blob>;
+declare function createBigIntStruct(): Struct<bigint | string, bigint>;
+declare function createDateStruct(): Struct<Date | number | string, Date>;
+declare function createIntersectionStruct<const T extends readonly [StructLike<unknown, unknown, boolean>, ...StructLike<unknown, unknown, boolean>[]]>(...structs: T): IntersectionStruct<T>;
+declare function createFileStruct(): Struct<File, File>;
+declare function createArrayBufferStruct(): Struct<ArrayBuffer, ArrayBuffer>;
+//#endregion
+//#region src/struct/introspection.d.ts
+declare function parseStructTuple<S extends StructLike<unknown, unknown, boolean>>(struct: S, value: unknown, options?: {
+  aliases?: boolean;
+  errorMap?: ErrorMap;
+}): ParseResult<S['_struct']['output']>;
+//#endregion
+//#region src/struct/facade.d.ts
+type EnumValue<T> = T extends readonly (infer U extends string)[] ? U : T extends {
+  [key: string]: infer U extends number | string;
+} ? U : never;
+declare function structEnum<const T extends readonly [string, ...string[]]>(value: T): Struct<EnumValue<T>, EnumValue<T>>;
+declare function structEnum<const T extends {
+  [key: string]: number | string;
+}>(value: T): Struct<EnumValue<T>, EnumValue<T>>;
+declare function structOr<const T extends readonly [StructLike, ...StructLike[]]>(...options: T): UnionStruct<T>;
+/**
+ * Facade for building protocol-boundary structs and parsing values.
+ *
+ * Prefer this entry point over internal constructors. Compose shapes with
+ * `struct.object`, then parse with `struct.parse` or let HTTP/SSE/WebSocket
+ * endpoints apply the same contracts at the wire boundary.
+ *
+ * @example
+ * ```ts
+ * const User = struct.object({
+ *   id: struct.number(),
+ *   displayName: struct.string().alias('display_name'),
+ * })
+ *
+ * const getUser = defineRequest({
+ *   method: 'GET',
+ *   path: '/users/:id',
+ *   input: struct.object({ id: struct.number() }),
+ *   builder: (input) => ({ path: input }),
+ *   output: User,
+ * })
+ *
+ * const [error, user] = struct.parse(User, { id: 1, displayName: 'Ada' })
+ * ```
+ */
+export declare const struct: {
+  readonly any: typeof createAnyStruct;
+  readonly array: typeof createArrayStruct;
+  readonly arrayBuffer: typeof createArrayBufferStruct;
+  readonly bigint: typeof createBigIntStruct;
+  readonly blob: typeof createBlobStruct;
+  readonly boolean: typeof createBooleanStruct;
+  readonly date: typeof createDateStruct;
+  readonly discriminatedUnion: typeof createDiscriminatedUnionStruct;
+  readonly enum: typeof structEnum;
+  readonly file: typeof createFileStruct;
+  readonly formData: typeof createFormDataBodyStruct;
+  readonly intersection: typeof createIntersectionStruct;
+  readonly literal: typeof createLiteralStruct;
+  readonly null: typeof createNullStruct;
+  readonly number: typeof createNumberStruct;
+  readonly object: typeof createObjectStruct;
+  readonly or: typeof structOr;
+  readonly parse: typeof parseStructTuple;
+  readonly record: typeof createRecordStruct;
+  readonly string: typeof createStringStruct;
+  readonly tuple: typeof createTupleStruct;
+  readonly unknown: typeof createUnknownStruct;
+  readonly urlencoded: typeof createUrlencodedBodyStruct;
+};
+//#endregion
+//#region src/sse/transport/parser.d.ts
+/**
+ * Portions of this file are adapted from Azure/fetch-event-source.
+ * See packages/core/THIRD_PARTY_NOTICES.md for the license text.
+ */
+interface EventStreamMessage {
+  id: string;
+  event: string;
+  data: string;
+}
+//#endregion
+//#region src/sse/transport/event_stream.d.ts
+/** Metadata available after an SSE response opens successfully. */
+interface EventStreamOpenInfo {
+  response: HttpResponse<unknown>;
+  url: string;
+}
+/**
+ * Fault codes an event stream can end with, drawn from the one shared `FaultCode` namespace.
+ *
+ * SSE used to carry a parallel set with no mapping to the request error model.
+ */
+type EventStreamFaultCode = Extract<FaultCode, 'CAP_BUFFER_EXCEEDED' | 'CAP_QUEUE_OVERFLOW' | 'EXT_HOOK_FAILED' | 'EXT_OBSERVER_FAILED' | 'NET_TIMEOUT' | 'NET_UNREACHABLE' | 'RES_DECODE_FAILED' | 'RES_MEDIA_TYPE_INVALID'>;
+interface EventStreamCloseInfoBase {
+  reason?: string;
+  cause?: unknown;
+}
+/**
+ * How an SSE stream ended: clean EOF, abort, or an error carrying its fault `code`.
+ *
+ * The discriminant is `kind` so that `code` can mean the same thing it means on a fault.
+ */
+type EventStreamCloseInfo = (EventStreamCloseInfoBase & {
+  kind: 'eof';
+}) | (EventStreamCloseInfoBase & {
+  kind: 'aborted';
+}) | (EventStreamCloseInfoBase & {
+  code: EventStreamFaultCode;
+  kind: 'error';
+});
+/** Open SSE stream: iterate events, inspect open metadata, and close early. */
+interface EventStreamHandle<TEvent = EventStreamMessage> extends AsyncIterable<TEvent>, AsyncDisposable {
+  readonly open: EventStreamOpenInfo;
+  readonly closed: Promise<EventStreamCloseInfo>;
+  close(reason?: unknown): void;
+  [Symbol.asyncDispose](): PromiseLike<void>;
+}
+//#endregion
+//#region src/internal/abort.d.ts
+type UseCancellationConfig = {
+  abort?: AbortSignal;
+  timeout?: never;
+} | {
+  abort?: never;
+  timeout?: number;
+};
+//#endregion
+//#region src/internal/endpoint_input.d.ts
+type EndpointInput<TInput extends AnyStruct | undefined> = TInput extends AnyStruct ? StructInput<TInput> : unknown;
+//#endregion
+//#region src/internal/endpoint_command.d.ts
+type IsEndpointInputOptional<TInput extends AnyStruct | undefined> = [TInput] extends [undefined] ? true : undefined extends EndpointInput<TInput> ? true : false;
+type EndpointCallable<TInput extends AnyStruct | undefined, TCommand> = [TInput] extends [undefined] ? () => TCommand : IsEndpointInputOptional<TInput> extends true ? (input?: EndpointInput<TInput>) => TCommand : (input: EndpointInput<TInput>) => TCommand;
+//#endregion
+//#region src/internal/builder_types.d.ts
+/** Object produced by endpoint input parsing. The symbol points at the struct that produced the node. */
+type Typed = {
+  readonly [STRUCT]: AnyStruct;
+};
+type Scalar = string | number | bigint | boolean | Date;
+type FlatValue = Scalar | readonly Scalar[] | undefined;
+type FlatRecord = {
+  readonly [key: string]: FlatValue;
+};
+type QueryValue = Scalar | readonly QueryValue[] | {
+  readonly [key: string]: QueryValue;
+} | undefined;
+type QueryRecord = {
+  readonly [key: string]: QueryValue;
+};
+type PathParams<P extends string> = P extends `${string}:${infer Name}/${infer Rest}` ? Name | PathParams<`/${Rest}`> : P extends `${string}:${infer Name}` ? Name : never;
+type PathValue<P extends string> = [PathParams<P>] extends [never] ? never : ({ readonly [K in PathParams<P>]: Scalar; } & {
+  readonly [STRUCT]?: never;
+}) | (Typed & {
+  readonly [key: string]: Scalar;
+});
+type HttpRequestShape<P extends string, M extends string> = {
+  body?: Uppercase<M> extends 'GET' | 'HEAD' ? never : unknown;
+  headers?: HeadersInit | FlatRecord;
+  path?: PathValue<P>;
+  query?: URLSearchParams | QueryRecord;
+};
+type WebSocketRequestShape<P extends string> = {
+  body?: never;
+  headers?: never;
+  path?: PathValue<P>;
+  query?: URLSearchParams | QueryRecord;
+};
+type EventStreamRequestShape<P extends string, M extends string> = HttpRequestShape<P, M>;
+type NullishBuilderInput<S, Inner> = null extends Infer<S> ? undefined extends Infer<S> ? BuilderInput<Inner> | null | undefined : BuilderInput<Inner> | null : undefined extends Infer<S> ? BuilderInput<Inner> | undefined : BuilderInput<Inner>;
+type IntersectBuilderInputs<T extends readonly StructLike<unknown, unknown, boolean>[]> = T extends readonly [infer Head extends StructLike<unknown, unknown, boolean>, ...infer Tail extends readonly StructLike<unknown, unknown, boolean>[]] ? BuilderInput<Head> & (Tail['length'] extends 0 ? unknown : IntersectBuilderInputs<Tail>) : unknown;
+/**
+ * Parsed endpoint input seen by a builder.
+ *
+ * Object nodes are intersected with {@link Typed}. Record entries and tuple items are too.
+ * At runtime a record container is also tagged when the parsed value is an object, whether or not it
+ * was merged. Array and tuple containers are not. `null` and `undefined` are never tagged.
+ * Modifiers recover the struct they wrapped. Union options are distributed; intersection options are combined.
+ */
+type BuilderInput<S> = S extends CarriedStruct<infer Inner> ? NullishBuilderInput<S, Inner> : S extends UnionStruct<infer Options> ? BuilderInput<Options[number]> : S extends DiscriminatedUnionStruct<infer Options> ? BuilderInput<Options[number]> : S extends IntersectionStruct<infer Options> ? IntersectBuilderInputs<Options> : S extends RecordStruct<infer Value> ? {
+  [key: string]: BuilderInput<Value>;
+} : S extends TupleStruct<infer Items> ? { [K in keyof Items]: Items[K] extends StructLike<unknown, unknown, boolean> ? BuilderInput<Items[K]> : Items[K]; } : S extends ArrayStruct<infer Item> ? BuilderInput<Item>[] : S extends ObjectStruct<infer Shape> ? { [K in keyof Shape]: BuilderInput<Shape[K]>; } & Typed : Infer<S>;
+type BuilderField<TInput, TShape> = [TInput] extends [undefined] ? {
+  builder?: () => TShape;
+} : BuilderInput<TInput> extends TShape ? {
+  builder?: (input: BuilderInput<TInput>) => TShape;
+} : {
+  builder: (input: BuilderInput<TInput>) => TShape;
+};
+//#endregion
+//#region src/internal/outbound_request.d.ts
+/** Accepts any concrete builder. `never` keeps the parameter contravariant. */
+type OutboundBuilder = (input: never) => unknown;
+//#endregion
+//#region src/http/http.d.ts
+/**
+ * Per-request options for HTTP execution: progress callbacks and cancellation.
+ * Cancellation is either `abort` or `timeout` (not both).
+ */
+export type UseRequestConfig = {
+  onDownloadProgress?: HttpProgressFn;
+  onUploadProgress?: HttpProgressFn;
+} & UseCancellationConfig;
+/**
+ * Executable HTTP command produced by a `defineRequest` endpoint.
+ * Carries the request definition and optional typed input for `client.execute`.
+ */
+export interface HttpCommand<TInput extends AnyStruct | undefined, TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined = undefined> extends BaseCommand<typeof HTTP_COMMAND> {
+  readonly definition: RequestDefinition<TInput, TOutput, TError>;
+  readonly input: EndpointInput<TInput> | undefined;
+}
+/**
+ * Options passed to `client.execute` / `executeHttpCommand` for a single HTTP call.
+ * `signal` combines with `abort` or `timeout`; it is not an alias for `abort`.
+ * `abort` and `timeout` are mutually exclusive (`abort` XOR `timeout`).
+ */
+export type HttpExecuteOptions = UseRequestConfig & {
+  signal?: AbortSignal;
+};
+/**
+ * Endpoint returned by `defineRequest`; call with input to create an `HttpCommand`.
+ */
+export type RequestEndpoint<TInput extends AnyStruct | undefined, TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined = undefined> = EndpointCallable<TInput, HttpCommand<TInput, TOutput, TError>>;
+type DeclaredBody<TStruct> = [TStruct] extends [undefined] ? undefined : Infer<TStruct>;
+type DeclaredResponse<TStruct> = [TStruct] extends [undefined] ? HttpMeta : DecodedResponse<Infer<TStruct>>;
+/** Inferred success body for the declared `output` struct, or `undefined` when none is declared. */
+export type RequestSuccessData<TOutput extends AnyStruct | undefined> = DeclaredBody<TOutput>;
+/** Inferred error body for the declared `error` struct, or `undefined` when none is declared. */
+export type RequestErrorData<TError extends AnyStruct | undefined> = DeclaredBody<TError>;
+type ResponseDeclaration<TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined> = ([TOutput] extends [undefined] ? {
+  output?: never;
+} : {
+  output: TOutput;
+}) & ([TError] extends [undefined] ? {
+  error?: never;
+} : {
+  error: TError;
+});
+/**
+ * Contract for an HTTP endpoint: method, path, optional input struct, and the structs that
+ * decode its bodies.
+ *
+ * `output` declares the body for a 2xx response, `error` the body for anything else. Only one
+ * of the two ever runs, and omitting one means that body is never read. Pass to `defineRequest`
+ * to get a typed endpoint.
+ */
+export type RequestDefinition<TInput extends AnyStruct | undefined = undefined, TOutput extends AnyStruct | undefined = undefined, TError extends AnyStruct | undefined = undefined> = ResponseDeclaration<TOutput, TError> & {
+  builder?: OutboundBuilder;
+  input?: TInput;
+  method: string;
+  operation?: string;
+  path: string;
+};
+/**
+ * Await-result tuple for an HTTP call.
+ *
+ * Success is `[null, data, response]`; failure is `[fault, undefined, undefined]` because the
+ * fault carries whatever response metadata existed.
+ */
+export type HttpAwaitResult<TData = undefined, TErrorData = undefined> = [error: null, result: TData, response: [TData] extends [undefined] ? HttpMeta : DecodedResponse<TData>] | [error: FaultOf<TErrorData>, result: undefined, response: undefined];
+type HttpExecuteAwaitResult<TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined> = [error: null, result: RequestSuccessData<TOutput>, response: DeclaredResponse<TOutput>] | [error: Fault<TError>, result: undefined, response: undefined];
+/**
+ * Declare a typed HTTP request endpoint.
+ *
+ * Pass method, path, an optional input struct, and the single `output` and `error` structs.
+ * Call the returned endpoint with input to get an `HttpCommand` for `client.execute`.
+ *
+ * @param definition - Request contract (method, path, input, builder, output).
+ * @returns An endpoint that creates `HttpCommand` values from input.
+ *
+ * @example
+ * ```ts
+ * const getUser = defineRequest({
+ *   method: 'GET',
+ *   path: '/users/:id',
+ *   input: struct.object({ id: struct.number() }),
+ *   builder: (input) => ({ path: { id: input.id } }),
+ *   output: struct.object({ id: struct.number(), name: struct.string() }),
+ *   error: struct.object({ message: struct.string() }),
+ * })
+ * ```
+ */
+export declare function defineRequest<const M extends string, const P extends string, TInput extends AnyStruct | undefined = undefined, TOutput extends AnyStruct | undefined = undefined, TError extends AnyStruct | undefined = undefined>(definition: ResponseDeclaration<TOutput, TError> & {
+  input?: TInput;
+  method: M;
+  operation?: string;
+  path: P;
+} & BuilderField<NoInfer<TInput>, HttpRequestShape<NoInfer<P>, NoInfer<M>>>): RequestEndpoint<TInput, TOutput, TError>;
+/**
+ * Run an `HttpCommand` against client config: validate input, send the request, parse the response.
+ * Prefer `client.execute(command)` in application code; this is the underlying implementation.
+ *
+ * @param clientConfig - Resolved HTTP client configuration (endpoint, interceptors, handler).
+ * @param command - Command from a `defineRequest` endpoint.
+ * @param options - Per-request progress and cancellation options.
+ * @returns An await-result tuple of success body or typed request error.
+ */
+export declare function executeHttpCommand<TInput extends AnyStruct | undefined, TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined>(clientConfig: HttpClientConfig, command: HttpCommand<TInput, TOutput, TError>, options?: HttpExecuteOptions): Promise<HttpExecuteAwaitResult<TOutput, TError>>;
+//#endregion
+//#region src/sse/sse.d.ts
+/** Map of SSE event names to payload structs. Declare `__proto__` with a computed own key. */
+export type EventStructs = {
+  [key: string]: AnyStruct;
+};
+type EventName<TKey extends string | number> = `${TKey}`;
+type KnownEventUnion<TEvents extends EventStructs> = { [K in keyof TEvents & (number | string)]: EventName<K> extends 'default' ? never : {
+  data: Infer<TEvents[K]>;
+  event: EventName<K>;
+  id?: string;
+}; }[keyof TEvents & (number | string)];
+type DefaultEventUnion<TEvents extends EventStructs> = 'default' extends keyof TEvents ? {
+  data: Infer<TEvents['default']>;
+  event: string;
+  id?: string;
 } : never;
-export type UseRequestOptions = {
-	abort?: AbortSignal;
-	handler?: HttpHandler;
-	client?: Client;
-	timeout?: number;
-};
-export type UseRequestFn<Input, Output> = {
-	doRequest: undefined extends RequestInputValue<Input> ? (input?: RequestInputValue<Input>) => Promise<HttpResponse<Output>> : (input: RequestInputValue<Input>) => Promise<HttpResponse<Output>>;
-	cancel: () => void;
-	getInitValue: () => RequestInputValue<Input>;
-	setUploadProgress: (fn: HttpProgressFn) => void;
-	setDownloadProgress: (fn: HttpProgressFn) => void;
-};
-export interface DefineRequest<Input extends Record<PropertyKey, Field<any>> | undefined = undefined, Output = unknown> {
-	(options?: UseRequestOptions): UseRequestFn<Input, Output>;
-	withField<I extends Record<PropertyKey, Field<any>>>(value: I): DefineRequest<I, Output>;
-	withInterceptors(value: InterceptorFn[]): DefineRequest<Input, Output>;
-	withContext(value: HttpContext): DefineRequest<Input, Output>;
-	withCredentials(value: boolean): DefineRequest<Input, Output>;
-	withValidators(...fn: (ValidatorFn<RequestInputValue<Input>> | AsyncValidatorFn<RequestInputValue<Input>>)[]): DefineRequest<Input, Output>;
-	withTransformResponse<O>(fn: TransformResponseFn<O>): DefineRequest<Input, O>;
-	withResponseType(value: "json"): DefineRequest<Input, Output>;
-	withResponseType(value: "text"): DefineRequest<Input, string>;
-	withResponseType(value: "blob"): DefineRequest<Input, Blob>;
-	withResponseType(value: "arraybuffer"): DefineRequest<Input, ArrayBuffer>;
-}
-export declare function defineRequest<Output>(endpoint: string): DefineRequest<undefined, Output>;
-export declare function defineRequest<Output>(method: string, endpoint: string): DefineRequest<undefined, Output>;
-export type HttpHandler = (req: HttpRequest) => Promise<HttpResponse<unknown>>;
-export declare function fetchHandler(httpRequest: HttpRequest): Promise<HttpResponse<unknown>>;
-export interface ClientOptions {
-	host: string;
-	interceptors?: InterceptorFn[];
-	handler?: HttpHandler;
-}
-export type ClientConfig = {
-	host: string;
-	handler: HttpHandler;
-	interceptors: InterceptorFn[];
+/** Parsed SSE event payload inferred from an `EventStructs` map. */
+export type EventStreamData<TEvents extends EventStructs> = TEvents extends EventStructs ? KnownEventUnion<TEvents> | DefaultEventUnion<TEvents> : never;
+interface EventStreamDefinitionBase<TEvents extends EventStructs = EventStructs> {
+  events: TEvents;
+  maxBufferSize: number;
+  maxQueueSize: number;
+  method?: string;
+  operation?: string;
+  path: string;
+}
+/** Makes `error` required only when an error struct is declared, so omission stays `Fault<undefined>`. */
+type EventStreamErrorField<TError extends AnyStruct | undefined> = [TError] extends [undefined] ? {
+  error?: never;
+} : {
+  error: TError;
+};
+/** Contract describing an SSE endpoint: path, events, and buffer/queue limits. */
+export type EventStreamDefinition<TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs, TError extends AnyStruct | undefined = undefined> = EventStreamDefinitionBase<TEvents> & EventStreamErrorField<TError> & {
+  builder?: OutboundBuilder;
+  input?: TInput;
+};
+/** Await-result tuple from opening an SSE stream via `client.execute`. */
+export type StreamAwaitResult<TEvent, TError extends AnyStruct | undefined = undefined> = [error: null, stream: EventStreamHandle<TEvent>, open: EventStreamOpenInfo] | [error: Fault<TError>, stream: undefined, open: EventStreamOpenInfo | undefined];
+/** Executable SSE command produced by an `EventStreamEndpoint`. */
+export interface EventStreamCommand<TInput extends AnyStruct | undefined, TEvents extends EventStructs, TError extends AnyStruct | undefined = undefined> extends BaseCommand<typeof EVENT_STREAM_COMMAND> {
+  readonly endpoint: ResolvedEventStreamDefinition<TInput, TEvents, TError>;
+  readonly input: EndpointInput<TInput> | undefined;
+}
+/** Per-execute options for SSE commands (abort, timeout). */
+export type EventStreamExecuteOptions = UseCancellationConfig & {
+  signal?: AbortSignal;
+};
+/** Endpoint returned by `defineEventStream`; call it to create an `EventStreamCommand`. */
+export type EventStreamEndpoint<TInput extends AnyStruct | undefined, TEvents extends EventStructs, TError extends AnyStruct | undefined = undefined> = EndpointCallable<TInput, EventStreamCommand<TInput, TEvents, TError>>;
+type ResolvedEventStreamDefinition<TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs, TError extends AnyStruct | undefined = undefined> = EventStreamDefinition<TInput, TEvents, TError> & {
+  readonly method: string;
+};
+/**
+ * Declare a typed Server-Sent Events endpoint.
+ *
+ * Pass path, event structs, and buffer/queue limits. Call the returned endpoint
+ * with input to get an `EventStreamCommand` for `client.execute`.
+ *
+ * @param definition - SSE contract (path, events, buffer limits, optional input).
+ * @returns An endpoint that creates `EventStreamCommand` values from input.
+ *
+ * @example
+ * ```ts
+ * const useEvents = defineEventStream({
+ *   maxBufferSize: 1024,
+ *   maxQueueSize: 16,
+ *   path: '/events',
+ *   events: { message: struct.object({ text: struct.string() }) },
+ * })
+ * ```
+ */
+export declare function defineEventStream<const P extends string, const M extends string = 'GET', TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs, TError extends AnyStruct | undefined = undefined>(definition: Omit<EventStreamDefinitionBase<TEvents>, 'method' | 'path'> & EventStreamErrorField<TError> & {
+  input?: TInput;
+  method?: M;
+  path: P;
+} & BuilderField<NoInfer<TInput>, EventStreamRequestShape<NoInfer<P>, NoInfer<M>>>): EventStreamEndpoint<TInput, TEvents, TError>;
+/**
+ * Open an SSE command against the given client config.
+ *
+ * Prefer `client.execute(command)` in application code; this is the low-level entry used by the client.
+ *
+ * @param clientConfig - Resolved client configuration.
+ * @param command - SSE command from an `EventStreamEndpoint`.
+ * @param options - Optional execute options (abort, timeout).
+ * @returns Await-result tuple of `[error, stream, open]`.
+ */
+export declare function executeEventStreamCommand<TInput extends AnyStruct | undefined, TEvents extends EventStructs, TError extends AnyStruct | undefined = undefined>(clientConfig: ClientConfig, command: EventStreamCommand<TInput, TEvents, TError>, options?: EventStreamExecuteOptions): Promise<StreamAwaitResult<EventStreamData<TEvents>, TError>>;
+//#endregion
+//#region src/client/command.d.ts
+declare const COMMAND_TYPE: unique symbol;
+declare const HTTP_COMMAND: unique symbol;
+declare const EVENT_STREAM_COMMAND: unique symbol;
+declare const WEB_SOCKET_COMMAND: unique symbol;
+/** The command's own runner, so `client.execute` never imports a transport the app does not use. */
+declare const COMMAND_EXECUTE: unique symbol;
+type CommandExecutor = (config: ClientConfig, command: never, options?: never) => Promise<unknown>;
+type CommandType = typeof HTTP_COMMAND | typeof EVENT_STREAM_COMMAND | typeof WEB_SOCKET_COMMAND;
+interface BaseCommand<TCommandType extends CommandType> {
+  readonly [COMMAND_EXECUTE]: CommandExecutor;
+  readonly [COMMAND_TYPE]: TCommandType;
+}
+//#endregion
+//#region src/web_socket/codec.d.ts
+interface WebSocketCloseSnapshot {
+  cause?: unknown;
+  code?: number;
+  reason?: string;
+  wasClean?: boolean;
+}
+//#endregion
+//#region src/web_socket/web_socket.d.ts
+/** Lifecycle state of a managed WebSocket session. */
+export type WebSocketState = 'aborted' | 'closed' | 'closing' | 'connecting' | 'error' | 'idle' | 'open' | 'reconnecting';
+/** Decoded incoming frame. Alias fields use their logical names. */
+export type WebSocketIncomingData<TIncoming extends AnyStruct> = Infer<TIncoming>;
+/** Value accepted by `session.send`. `never` when the endpoint declares no outgoing struct. */
+export type WebSocketOutgoingData<TOutgoing extends AnyStruct | undefined> = TOutgoing extends AnyStruct ? StructInput<TOutgoing> : never;
+interface WebSocketDefinitionBase<TIncoming extends AnyStruct = AnyStruct, TOutgoing extends AnyStruct | undefined = undefined> {
+  incoming: TIncoming;
+  maxIncomingQueueSize: number;
+  maxOutgoingQueueSize?: number;
+  operation?: string;
+  outgoing?: TOutgoing;
+  path: string;
+  protocols?: readonly string[];
+}
+/** Contract describing a WebSocket endpoint: path, message structs, and queue limits. */
+export type WebSocketDefinition<TInput extends AnyStruct | undefined = undefined, TIncoming extends AnyStruct = AnyStruct, TOutgoing extends AnyStruct | undefined = undefined> = WebSocketDefinitionBase<TIncoming, TOutgoing> & {
+  builder?: OutboundBuilder;
+  input?: TInput;
+};
+/** Connection metadata for the current WebSocket generation. */
+export interface WebSocketConnectionInfo {
+  extensions?: string;
+  generation: number;
+  protocol?: string;
+  url?: string;
+}
+/** How a WebSocket session ended: closed, aborted, or error. */
+export type WebSocketCloseInfo = {
+  kind: 'closed';
+  code?: number;
+  reason?: string;
+  wasClean?: boolean;
+} | {
+  kind: 'aborted';
+  cause?: unknown;
+  code?: number;
+  reason?: string;
+  wasClean?: boolean;
+} | {
+  kind: 'error';
+  cause: unknown;
+  code?: number;
+  reason?: string;
+  wasClean?: boolean;
+};
+/** Typed WebSocket session: send/receive messages, observe state, and close. */
+export interface WebSocketSession<TIncoming = unknown, TOutgoing = never> extends AsyncDisposable {
+  readonly bufferedAmount: number;
+  readonly connection: WebSocketConnectionInfo;
+  readonly closed: Promise<WebSocketCloseInfo>;
+  readonly receive: AsyncIterable<TIncoming>;
+  readonly state: WebSocketState;
+  close(code?: number, reason?: string): void;
+  [Symbol.asyncDispose](): PromiseLike<void>;
+  onRuntimeError(listener: (error: unknown) => void): () => void;
+  onStateChange(listener: (state: WebSocketState) => void): () => void;
+  send(message: TOutgoing): void;
+}
+/** Await-result tuple from opening a WebSocket via `client.execute`. */
+export type SocketAwaitResult<TIncoming, TOutgoing = never> = [error: null, socket: WebSocketSession<TIncoming, TOutgoing>, connection: WebSocketConnectionInfo] | [error: Fault<undefined>, socket: undefined, connection: WebSocketConnectionInfo | undefined];
+interface UseWebSocketBaseConfig<TIncoming = unknown, TOutgoing = unknown> {
+  beforeConnect?: ClientWebSocketOptions['beforeConnect'];
+  heartbeat?: WebSocketHeartbeatConfig<TIncoming, TOutgoing>;
+  protocols?: readonly string[];
+  reconnect?: ClientWebSocketOptions['reconnect'];
+}
+/** Client configuration for WebSocket execute (heartbeat, reconnect, abort). */
+export type UseWebSocketConfig<TIncoming = unknown, TOutgoing = unknown> = UseWebSocketBaseConfig<TIncoming, TOutgoing> & UseCancellationConfig;
+/** Per-execute options for WebSocket commands, including an optional `AbortSignal`. */
+export type WebSocketExecuteOptions<TIncoming = unknown, TOutgoing = unknown> = UseWebSocketConfig<TIncoming, TOutgoing> & {
+  signal?: AbortSignal;
+};
+/** Executable WebSocket command produced by a `WebSocketEndpoint`. */
+export interface WebSocketCommand<TInput extends AnyStruct | undefined, TIncoming extends AnyStruct, TOutgoing extends AnyStruct | undefined> extends BaseCommand<typeof WEB_SOCKET_COMMAND> {
+  readonly endpoint: WebSocketDefinition<TInput, TIncoming, TOutgoing>;
+  readonly input: EndpointInput<TInput> | undefined;
+}
+/** Endpoint returned by `defineWebSocket`; call it to create a `WebSocketCommand`. */
+export type WebSocketEndpoint<TInput extends AnyStruct | undefined, TIncoming extends AnyStruct, TOutgoing extends AnyStruct | undefined> = EndpointCallable<TInput, WebSocketCommand<TInput, TIncoming, TOutgoing>>;
+/** Reason recorded when the session is closed via `session.close()`. */
+export type ManualSocketCloseReason = {
+  code?: number;
+  kind: 'manual-web-socket-close';
+  reason?: string;
+};
+/** Heartbeat ping/ack configuration for a live WebSocket session. */
+export interface WebSocketHeartbeatConfig<TIncoming = unknown, TOutgoing = unknown> {
+  intervalMs: number;
+  isAck?: (message: TIncoming) => boolean;
+  message?: () => TOutgoing;
+  timeoutMs?: number;
+}
+/**
+ * Declare a typed WebSocket endpoint.
+ *
+ * Pass path, incoming (and optional outgoing) message structs, and queue limits.
+ * Call the returned endpoint with input to get a `WebSocketCommand` for `client.execute`.
+ *
+ * @param definition - WebSocket contract (path, structs, queue limits, optional input).
+ * @returns An endpoint that creates `WebSocketCommand` values from input.
+ *
+ * @example
+ * ```ts
+ * const useChat = defineWebSocket({
+ *   maxIncomingQueueSize: 16,
+ *   path: '/ws/chat',
+ *   incoming: struct.object({ text: struct.string(), type: struct.literal('message') }),
+ *   outgoing: struct.object({ text: struct.string(), type: struct.literal('message') }),
+ * })
+ * ```
+ */
+export declare function defineWebSocket<const P extends string, TInput extends AnyStruct | undefined = undefined, TIncoming extends AnyStruct = AnyStruct, TOutgoing extends AnyStruct | undefined = undefined>(definition: Omit<WebSocketDefinitionBase<TIncoming, TOutgoing>, 'path'> & {
+  input?: TInput;
+  path: P;
+} & BuilderField<NoInfer<TInput>, WebSocketRequestShape<NoInfer<P>>>): WebSocketEndpoint<TInput, TIncoming, TOutgoing>;
+/**
+ * Open a WebSocket command against the given client config.
+ *
+ * Prefer `client.execute(command)` in application code; this is the low-level entry used by the client.
+ *
+ * @param clientConfig - Resolved client configuration.
+ * @param command - WebSocket command from a `WebSocketEndpoint`.
+ * @param options - Optional execute options (heartbeat, reconnect, abort).
+ * @returns Await-result tuple of `[error, socket, connection]`.
+ */
+export declare function executeWebSocketCommand<TInput extends AnyStruct | undefined, TIncoming extends AnyStruct, TOutgoing extends AnyStruct | undefined>(clientConfig: ClientConfig, command: WebSocketCommand<TInput, TIncoming, TOutgoing>, options?: WebSocketExecuteOptions<WebSocketIncomingData<TIncoming>, WebSocketOutgoingData<TOutgoing>>): Promise<SocketAwaitResult<WebSocketIncomingData<TIncoming>, WebSocketOutgoingData<TOutgoing>>>;
+/** Outcome of a single WebSocket connect attempt used by reconnect logic. */
+export type SocketLifecycleOutcome = {
+  closeInfo: WebSocketCloseSnapshot;
+  connection?: WebSocketConnectionInfo;
+  cause?: unknown;
+  opened: boolean;
+};
+//#endregion
+//#region src/interceptor/interceptor.d.ts
+/**
+ * Continuation that runs the rest of the HTTP interceptor chain (or the handler).
+ *
+ * `next(req)` only goes **inward** — remaining interceptors registered after this one,
+ * then the Fetch handler. It is not a re-dispatch of `client.execute` / `axios(config)`
+ * from the outside of the onion. Call `next` again for a safe replay (for example one
+ * 401 refresh) from the same interceptor; outer layers do not run a second time.
+ */
+type HttpInterceptorNext = (req: HttpRequest) => Promise<HttpResponse<unknown>>;
+/**
+ * HTTP interceptor function: may inspect/modify the request, then call `next`.
+ */
+type InterceptorFn = (req: HttpRequest, next: HttpInterceptorNext) => Promise<HttpResponse<unknown>>;
+/**
+ * Tagged HTTP interceptor for client option lists.
+ */
+interface HttpInterceptor {
+  kind: 'http';
+  fn: InterceptorFn;
+}
+/**
+ * Wrap an `InterceptorFn` as a tagged `HttpInterceptor`.
+ *
+ * @param fn - HTTP interceptor function.
+ * @returns An `HttpInterceptor` with `kind: 'http'`.
+ */
+export declare function createHttpInterceptor(fn: InterceptorFn): HttpInterceptor;
+/**
+ * Terminal SSE handler that opens an event stream for the given request.
+ */
+type SSEHandler = (req: HttpRequest) => Promise<EventStreamHandle<unknown>>;
+/**
+ * SSE interceptor function: may inspect/modify the request, then call `next`.
+ */
+type SSEInterceptorFn = (req: HttpRequest, next: SSEHandler) => Promise<EventStreamHandle<unknown>>;
+/**
+ * Tagged SSE interceptor for client option lists.
+ */
+interface SSEInterceptor {
+  kind: 'sse';
+  fn: SSEInterceptorFn;
+}
+/**
+ * Wrap an `SSEInterceptorFn` as a tagged `SSEInterceptor`.
+ *
+ * @param fn - SSE interceptor function.
+ * @returns An `SSEInterceptor` with `kind: 'sse'`.
+ */
+export declare function createSSEInterceptor(fn: SSEInterceptorFn): SSEInterceptor;
+/**
+ * Minimal WebSocket session surface used by interceptors.
+ *
+ * Structurally compatible with `WebSocketSession` without importing that type
+ * (avoids a circular dependency between interceptors and WebSocket).
+ */
+interface WebSocketSessionLike extends AsyncDisposable {
+  readonly bufferedAmount: number;
+  readonly connection: {
+    extensions?: string;
+    generation: number;
+    protocol?: string;
+    url?: string;
+  };
+  readonly closed: Promise<WebSocketCloseInfo>;
+  readonly receive: AsyncIterable<unknown>;
+  readonly state: WebSocketState;
+  close(code?: number, reason?: string): void;
+  [Symbol.asyncDispose](): PromiseLike<void>;
+  onRuntimeError(listener: (error: unknown) => void): () => void;
+  onStateChange(listener: (state: WebSocketState) => void): () => void;
+  send(message: unknown): void;
+}
+/**
+ * Terminal WebSocket handler that opens a session for the given request.
+ */
+type WebSocketHandler = (req: HttpRequest) => Promise<WebSocketSessionLike>;
+/**
+ * WebSocket interceptor function: may inspect/modify the request, then call `next`.
+ */
+type WebSocketInterceptorFn = (req: HttpRequest, next: WebSocketHandler) => Promise<WebSocketSessionLike>;
+/**
+ * Tagged WebSocket interceptor for client option lists.
+ */
+interface WebSocketInterceptor {
+  kind: 'web-socket';
+  fn: WebSocketInterceptorFn;
+}
+/**
+ * Wrap a `WebSocketInterceptorFn` as a tagged `WebSocketInterceptor`.
+ *
+ * @param fn - WebSocket interceptor function.
+ * @returns A `WebSocketInterceptor` with `kind: 'web-socket'`.
+ */
+export declare function createWebSocketInterceptor(fn: WebSocketInterceptorFn): WebSocketInterceptor;
+/**
+ * Any tagged interceptor accepted by client interceptor options.
+ */
+type Interceptor = HttpInterceptor | SSEInterceptor | WebSocketInterceptor;
+//#endregion
+//#region src/client/config.d.ts
+/**
+ * Serializes an encoded query object into a query string.
+ *
+ * `query` is the wire object: aliases already applied, `Date` values already ISO
+ * strings, `bigint` values already strings. Nested objects and arrays are preserved.
+ * The returned string is used verbatim and is not passed through `URLSearchParams`.
+ *
+ * @param query - Encoded query object.
+ * @returns The query string without a leading `?`.
+ */
+type QuerySerializer = (query: {
+  [key: string]: unknown;
+}) => string;
+/**
+ * Fetch-compatible function used as an HTTP or SSE handle.
+ *
+ * This is the `(input, init?) => Promise<Response>` call signature Defjs invokes,
+ * not `typeof fetch`, so mocks do not need host extras such as `preconnect`.
+ */
+type FetchHandle = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+/**
+ * Minimal WebSocket-like handle used by the client transport.
+ *
+ * Omits browser event-handler properties so custom implementations only need
+ * the send/close/state surface Defjs relies on.
+ */
+type WebSocketHandle = Omit<WebSocket, 'binaryType' | 'CLOSED' | 'CLOSING' | 'CONNECTING' | 'dispatchEvent' | 'onclose' | 'onerror' | 'onmessage' | 'onopen' | 'OPEN' | 'readyState'> & {
+  readonly readyState: number;
 };
+/** Constructor for a `WebSocketHandle`, including the `OPEN` ready-state constant. */
+type WebSocketHandleConstructor = {
+  readonly OPEN: number;
+} & (new (...args: never[]) => WebSocketHandle);
+/** Optional WebSocket settings applied when creating a client. */
+interface ClientWebSocketOptions {
+  /** WebSocket constructor; defaults to `globalThis.WebSocket`. */
+  handle?: WebSocketHandleConstructor;
+  /** Hook before each connect/reconnect attempt. */
+  beforeConnect?: (context: {
+    attempt: number;
+    signal: AbortSignal;
+  }) => void | Promise<void>;
+  /** Periodic heartbeat ping and optional ACK matching. */
+  heartbeat?: {
+    /** Delay between heartbeat messages. */
+    intervalMs: number;
+    /** Returns whether an incoming message acknowledges the heartbeat. */
+    isAck?: (message: unknown) => boolean;
+    /** Builds the outbound heartbeat payload. */
+    message?: <T = unknown>() => T | unknown;
+    /** Time to wait for an ACK before treating the connection as unhealthy. */
+    timeoutMs?: number;
+  };
+  /** Subprotocols passed to the WebSocket constructor. */
+  protocols?: readonly string[];
+  /** Automatic reconnect policy after unexpected closes. */
+  reconnect?: {
+    /** Retry budget after the first connect. Defaults to 3 when `reconnect` is set. `0` disables. Omitting this field is not unlimited. */
+    attempts?: number;
+    /** Initial backoff delay in milliseconds. */
+    delayMs?: number;
+    /** Multiplier applied to the delay after each failed attempt. */
+    factor?: number;
+    /** Random jitter factor applied to the delay (0–1). */
+    jitter?: number;
+    /** Upper bound for computed backoff delay. */
+    maxDelayMs?: number;
+    /** Return `false` to skip reconnecting for this close. */
+    shouldReconnect?: (context: {
+      attempt: number;
+      cause?: unknown;
+      code?: number;
+      reason?: string;
+      wasClean?: boolean;
+    }) => boolean;
+  };
+}
+/** Optional SSE settings applied when creating a client. */
+interface ClientSSEOptions {
+  /** Fetch implementation used to open the event stream. */
+  handle?: FetchHandle;
+  /** Called when an event has no matching struct or fails validation. */
+  onInvalidEvent?: (context: {
+    reason: 'missing-struct' | 'validation-failed';
+    message: {
+      id: string;
+      event: string;
+      data: string;
+    };
+    cause?: unknown;
+    signal: AbortSignal;
+  }) => unknown;
+  /** Automatic reconnect policy after stream failures. */
+  reconnect?: {
+    /** Retry budget after the first attempt. Defaults to 3 when `reconnect` is set. `0` disables. Omitting this field is not unlimited. */
+    attempts?: number;
+    /** Initial backoff delay in milliseconds. */
+    delayMs?: number;
+    /** Multiplier applied to the delay after each failed attempt. */
+    factor?: number;
+    /** Random jitter factor applied to the delay (0–1). */
+    jitter?: number;
+    /** Upper bound for computed backoff delay. */
+    maxDelayMs?: number;
+    /** Return `false` to skip reconnecting for this failure. */
+    shouldReconnect?: (context: {
+      attempt: number;
+      cause?: unknown;
+      lastEventId: string;
+      open?: {
+        response: {
+          status: number;
+          statusText: string;
+          url: string;
+        };
+        url: string;
+      };
+    }) => boolean | Promise<boolean>;
+  };
+}
+/** Resolved SSE config with a required `handle`. */
+interface ClientSSEConfig extends ClientSSEOptions {
+  /** Fetch implementation used to open the event stream. */
+  handle: FetchHandle;
+}
+/** User-facing HTTP client options before defaults are applied. */
+interface HttpClientOptions {
+  /** Base URL prepended to relative request paths. */
+  endpoint: string;
+  /** Static default headers merged under command headers for HTTP/SSE. */
+  headers?: Headers;
+  /** HTTP transport overrides. */
+  http?: {
+    handle?: FetchHandle;
+  };
+  /** Interceptors applied in registration order. */
+  interceptors?: Interceptor[];
+  /** Serializes encoded query objects. Omit to use `URLSearchParams`. */
+  querySerializer?: QuerySerializer;
+  /** Default HTTP execute timeout in milliseconds (SSE/WebSocket ignore this). */
+  timeout?: number;
+  /** XSRF cookie/header mapping and optional token provider. */
+  xsrf?: {
+    /** Cookie name that stores the XSRF token. */
+    cookieName?: string;
+    /** Request header name that receives the token. */
+    headerName?: string;
+    /** Supplies a token instead of reading the cookie. */
+    tokenProvider?: (context: {
+      request: HttpRequest;
+    }) => string | null | undefined;
+  };
+  /** When `true`, credentials are included with requests. */
+  withCredentials?: boolean;
+}
+/** User-facing options for `createClient`, including SSE and WebSocket. */
+interface ClientOptions extends HttpClientOptions {
+  /** SSE transport and reconnect options. */
+  sse?: ClientSSEOptions;
+  /** WebSocket transport, heartbeat, and reconnect options. */
+  webSocket?: ClientWebSocketOptions;
+}
+/** Resolved HTTP client config after defaults and options are applied. */
+interface HttpClientConfig {
+  /** Base URL prepended to relative request paths. */
+  endpoint: string;
+  /** Static default headers merged under command headers for HTTP/SSE. */
+  headers?: Headers;
+  /** HTTP transport with a required fetch handle. */
+  http: {
+    handle: FetchHandle;
+  };
+  /** Interceptors applied in registration order. */
+  interceptors: Interceptor[];
+  /** Serializes encoded query objects. Omit to use `URLSearchParams`. */
+  querySerializer?: QuerySerializer;
+  /** Default HTTP execute timeout in milliseconds (SSE/WebSocket ignore this). */
+  timeout?: number;
+  /** Resolved XSRF settings when enabled. */
+  xsrf?: {
+    /** Cookie name that stores the XSRF token. */
+    cookieName: string;
+    /** Request header name that receives the token. */
+    headerName: string;
+    /** Supplies a token instead of reading the cookie. */
+    tokenProvider?: (context: {
+      request: HttpRequest;
+    }) => string | null | undefined;
+  };
+  /** When `true`, credentials are included with requests. */
+  withCredentials?: boolean;
+}
+/** Resolved client config held by instances from `createClient`. */
+interface ClientConfig extends HttpClientConfig {
+  /** Resolved SSE configuration. */
+  sse: ClientSSEConfig;
+  /** Resolved WebSocket configuration. */
+  webSocket: ClientWebSocketOptions;
+}
+//#endregion
+//#region src/client/option.d.ts
+/** Mutates `ClientConfig` when applied by `createClient`. */
+type ClientOption = (config: ClientConfig) => void;
+/**
+ * Sets the base URL prepended to relative request paths.
+ *
+ * @param endpoint - Absolute or relative base endpoint.
+ * @returns An option that writes `config.endpoint`.
+ */
+export declare function withEndpoint(endpoint: string): ClientOption;
+/**
+ * Sets static default headers for HTTP/SSE requests built by this client.
+ *
+ * Builder `headers` override the same names. HMAC and
+ * dynamic Bearer tokens still belong in interceptors (they need the serialized body
+ * or a refreshed credential).
+ *
+ * @param headers - `HeadersInit` bag cloned onto the client config.
+ * @returns An option that writes `config.headers`.
+ */
+export declare function withHeaders(headers: HeadersInit): ClientOption;
+/**
+ * Sets the default timeout for HTTP `execute` only.
+ *
+ * Timeout is applied before the interceptor chain (`mergeAbortSignals`). Execute
+ * `{ timeout }` overrides this default. Execute `{ abort }` combines with the
+ * default (abort → `ABORTED`, timer → `TIMEOUT`). SSE and WebSocket ignore this
+ * option. XOR still rejects execute options that pass both `abort` and `timeout`.
+ *
+ * @param ms - Positive safe integer timeout in milliseconds.
+ * @returns An option that writes `config.timeout`.
+ */
+export declare function withTimeout(ms: number): ClientOption;
+/**
+ * Appends interceptors to the client interceptor chain.
+ *
+ * @param interceptors - Interceptors applied in registration order.
+ * @returns An option that pushes onto `config.interceptors`.
+ */
+export declare function withInterceptors(...interceptors: Interceptor[]): ClientOption;
+/**
+ * Sets the query serializer for HTTP, SSE, and WebSocket requests.
+ *
+ * The function receives the encoded wire object and its string is used verbatim.
+ * Without this option, queries use `URLSearchParams`: arrays repeat keys and a nested
+ * object fails. A builder that returns `URLSearchParams` skips this serializer.
+ *
+ * @param serializer - Function that turns an encoded query object into a string.
+ * @returns An option that sets `config.querySerializer`.
+ */
+export declare function withQuerySerializer(serializer: QuerySerializer): ClientOption;
+/**
+ * Overrides the Fetch-compatible function used for HTTP requests.
+ *
+ * @param fetchImpl - `(input, init?) => Promise<Response>`. Not `typeof fetch`, so
+ *   a mock does not need host extras such as `preconnect`.
+ * @returns An option that sets `config.http.handle`.
+ */
+export declare function withHTTPHandle(fetchImpl: FetchHandle): ClientOption;
+/**
+ * Overrides the Fetch-compatible function used for SSE connections.
+ *
+ * @param fetchImpl - `(input, init?) => Promise<Response>`. Not `typeof fetch`, so
+ *   a mock does not need host extras such as `preconnect`.
+ * @returns An option that sets `config.sse.handle`.
+ */
+export declare function withSSEHandle(fetchImpl: FetchHandle): ClientOption;
+/**
+ * Overrides the WebSocket constructor used for socket connections.
+ *
+ * @param WebSocketImpl - Constructor that returns a `WebSocketHandle`.
+ * @returns An option that sets `config.webSocket.handle`.
+ */
+export declare function withWebSocketHandle(WebSocketImpl: WebSocketHandleConstructor): ClientOption;
+/**
+ * Runs logic before each WebSocket connect or reconnect attempt.
+ *
+ * @param beforeConnect - Hook receiving attempt index and abort signal.
+ * @returns An option that sets `config.webSocket.beforeConnect`.
+ */
+export declare function withWebSocketBeforeConnect(beforeConnect: ClientWebSocketOptions['beforeConnect']): ClientOption;
+/**
+ * Configure WebSocket subprotocols for the connection handshake.
+ *
+ * `protocols` are passed as the second argument to the `WebSocket` constructor
+ * and participate in the RFC 6455 subprotocol negotiation. They are only
+ * meaningful when the server requires a specific protocol (for example,
+ * `['json']` or `['v1']` to select a message encoding version).
+ *
+ * @param protocols - Subprotocol list for the WebSocket constructor.
+ * @returns An option that sets `config.webSocket.protocols`.
+ */
+export declare function withWebSocketProtocols(protocols: readonly string[]): ClientOption;
+/**
+ * Enables WebSocket heartbeat pings and optional ACK detection.
+ *
+ * @param options - Heartbeat interval, payload, timeout, and ACK predicate.
+ * @returns An option that sets `config.webSocket.heartbeat`.
+ */
+export declare function withWebSocketHeartbeat(options: ClientWebSocketOptions['heartbeat']): ClientOption;
+/**
+ * Configures automatic WebSocket reconnection after unexpected closes.
+ *
+ * @param options - Retry budget, backoff, and `shouldReconnect` gate.
+ * @returns An option that sets `config.webSocket.reconnect`.
+ */
+export declare function withWebSocketReconnect(options: ClientWebSocketOptions['reconnect']): ClientOption;
+/**
+ * Handles SSE events that lack a matching struct or fail validation.
+ *
+ * @param handler - Callback for invalid events; may throw or return a value.
+ * @returns An option that sets `config.sse.onInvalidEvent`.
+ */
+export declare function withSSEOnInvalidEvent(handler: ClientSSEOptions['onInvalidEvent']): ClientOption;
+/**
+ * Configures automatic SSE reconnection after stream failures.
+ *
+ * @param options - Retry budget, backoff, and `shouldReconnect` gate.
+ * @returns An option that sets `config.sse.reconnect`.
+ */
+export declare function withSSEReconnect(options: ClientSSEOptions['reconnect']): ClientOption;
+/**
+ * Enables XSRF cookie-to-header token forwarding for HTTP requests.
+ *
+ * Defaults to cookie `XSRF-TOKEN` and header `X-XSRF-TOKEN` when names are omitted.
+ *
+ * @param options - Cookie/header names and optional token provider.
+ * @returns An option that sets `config.xsrf`.
+ */
+export declare function withXSRF(options?: HttpClientOptions['xsrf']): ClientOption;
+/**
+ * Sets whether HTTP/SSE requests should include credentials (cookies).
+ *
+ * @param value - When `true`, credentials are sent with cross-origin requests.
+ * @returns An option that sets `config.withCredentials`.
+ */
+export declare function withCredentials(value: boolean): ClientOption;
+//#endregion
+//#region src/client/client.d.ts
 declare const CLIENT: unique symbol;
-export type Client = {
-	readonly [CLIENT]: ClientConfig;
-};
-export declare function isClient(value: unknown): value is Client;
-export declare function createClient(options: ClientOptions): Client;
-export declare function cloneClient(client: Client, options: Partial<ClientOptions>): Client;
-export declare function getGlobalClient(): Client;
-export declare function setGlobalClient(client: Client): void;
-export declare function restGlobalClient(): void;
-export declare function createGlobalClient(options: ClientOptions): void;
-
-export {};
+/**
+ * Defjs client: holds config and `execute`s HTTP, SSE, and WebSocket commands.
+ */
+type Client = {
+  readonly [CLIENT]: ClientConfig;
+  /** Open an SSE command and return stream open/await results. */
+  execute<TInput extends AnyStruct | undefined, TEvents extends EventStructs, TError extends AnyStruct | undefined = undefined>(command: EventStreamCommand<TInput, TEvents, TError>, options?: EventStreamExecuteOptions): Promise<StreamAwaitResult<EventStreamData<TEvents>, TError>>;
+  /** Open a WebSocket command and return session await results. */
+  execute<TInput extends AnyStruct | undefined, TIncoming extends AnyStruct, TOutgoing extends AnyStruct | undefined>(command: WebSocketCommand<TInput, TIncoming, TOutgoing>, options?: WebSocketExecuteOptions<WebSocketIncomingData<TIncoming>, WebSocketOutgoingData<TOutgoing>>): Promise<SocketAwaitResult<WebSocketIncomingData<TIncoming>, WebSocketOutgoingData<TOutgoing>>>;
+  /** Run an HTTP command and return an await-result tuple. */
+  execute<TInput extends AnyStruct | undefined, TOutput extends AnyStruct | undefined, TError extends AnyStruct | undefined>(command: HttpCommand<TInput, TOutput, TError>, options?: HttpExecuteOptions): ReturnType<typeof executeHttpCommand<TInput, TOutput, TError>>;
+};
+/**
+ * Create a Defjs client from option helpers.
+ *
+ * Options are applied in order. Prefer creating the client inside the
+ * request boundary when interceptors close over auth or tenants.
+ *
+ * @param options - Client option helpers such as `withEndpoint`.
+ * @returns A client that can `execute` HTTP, SSE, and WebSocket commands.
+ *
+ * @example
+ * ```ts
+ * const client = createClient(withEndpoint('https://api.example.com'))
+ * ```
+ */
+export declare function createClient(...options: ClientOption[]): Client;
+//#endregion
+//#region src/http/transport/fetch.d.ts
+/**
+ * Default HTTP transport: perform `httpRequest` with `fetch` and return an `HttpResponse`.
+ * Used by the client unless `withHTTPHandle` replaces it; also usable in tests and custom handlers.
+ *
+ * @param httpRequest - Normalized request (URL, headers, body, abort, progress hooks).
+ * @param fetchImpl - Fetch implementation; defaults to global `fetch`. The library default handle is called as
+ *   `(url, init)` and its body is read in one piece unless download progress is observed. Any other handle receives a
+ *   `Request` and its body is read chunk by chunk.
+ * @returns Parsed `HttpResponse`. Rejects when no response reached the client, or when reading the
+ *   body failed — a transport failure is a fault, never a response.
+ */
+export declare function fetchHandler(httpRequest: HttpRequest, fetchImpl?: FetchHandle): Promise<HttpResponse<unknown>>;
+//#endregion
+//#region src/internal/url.d.ts
+export declare function createResolvedRequestUrl(baseEndpoint: string, path: string, queryString?: string): URL;
+//#endregion
+//#region src/interceptor/basic_auth.d.ts
+type BasicCredential = {
+  username: string;
+  password: string;
+};
+/**
+ * Options for basic-auth interceptors, including a custom credential encoder.
+ */
+type BasicAuthInterceptorOptions = {
+  encode?: (credential: BasicCredential) => string;
+};
+/**
+ * HTTP interceptor that sets an `Authorization: Basic …` header from credentials.
+ *
+ * @param fn - Factory returning username/password for each request.
+ * @param options - Optional custom encoder (defaults to `btoa`).
+ * @returns An `HttpInterceptor` that injects basic auth.
+ */
+export declare function basicAuthHttpInterceptor(fn: () => BasicCredential, options?: BasicAuthInterceptorOptions): HttpInterceptor;
+/**
+ * SSE interceptor that sets an `Authorization: Basic …` header from credentials.
+ *
+ * @param fn - Factory returning username/password for each request.
+ * @param options - Optional custom encoder (defaults to `btoa`).
+ * @returns An `SSEInterceptor` that injects basic auth.
+ */
+export declare function basicAuthSSEInterceptor(fn: () => BasicCredential, options?: BasicAuthInterceptorOptions): SSEInterceptor;
+//#endregion
+export type { AnyStruct, BasicAuthInterceptorOptions, BuilderInput, Client, ClientConfig, ClientOption, ClientOptions, ClientSSEConfig, ClientSSEOptions, ClientWebSocketOptions, DecodedResponse, ErrorMap, EventStreamCloseInfo, EventStreamFaultCode, EventStreamHandle, EventStreamOpenInfo, EventStreamRequestShape, FetchHandle, FlattenedStructError, FormattedStructError, HttpInterceptor, HttpInterceptorNext, HttpMeta, HttpProgressEvent, HttpProgressFn, HttpRequest, HttpRequestShape, HttpResponse, HttpResponseType, Infer, Interceptor, InterceptorFn, MakeResponseOptions, ObjectStruct, ParseResult, QuerySerializer, SSEHandler, SSEInterceptor, SSEInterceptorFn, STRUCT, Struct, StructInput, StructIssue, StructLike, StructMethods, WebSocketHandle, WebSocketHandleConstructor, WebSocketHandler, WebSocketInterceptor, WebSocketInterceptorFn, WebSocketRequestShape, WebSocketSessionLike };