@defjs/core 0.3.2 → 0.4.0-beta.0

package/index.d.ts

@@ -1,194 +1,1598 @@
-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.
+ * Defaults to `'json'` when an output shape is declared.
+ */
+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 `struct.json(...)` (or another body codec) runs during command build, `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 object.
+ */
+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;
+  responseType?: 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;
+/**
+ * Parsed HTTP response wrapper returned by handlers and `executeHttpCommand`.
+ * `ok` is true for status codes in the 2xx range; `error` may hold transport or parse failures.
+ */
+type HttpResponse<R> = {
+  readonly [HTTP_RESPONSE]: true;
+  readonly url: string;
+  readonly status: number;
+  readonly statusText: string;
+  readonly headers: Headers;
+  readonly body: R | null;
+  readonly error?: unknown;
+  readonly ok: boolean;
+};
+/**
+ * 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;
+  error?: unknown;
+  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, optional request to copy headers/url from, and optional error; 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/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/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_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): Struct<I, O, OO>;
+  /**
+   * 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>;
+/**
+ * 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>;
+}
+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>;
+}
+type RequestBodyCodec = 'arrayBuffer' | 'blob' | 'formData' | 'json' | 'text' | 'urlencoded';
+interface RequestBodyStructTypes<C extends RequestBodyCodec, S extends StructLike<unknown, unknown, boolean>> extends StructTypes<Exclude<StructInput<S>, undefined>, Exclude<StructOutput<S>, undefined>, false> {
+  codec: C;
+  input: Exclude<StructInput<S>, undefined>;
+  optionalOut: undefined;
+  output: Exclude<StructOutput<S>, undefined>;
+}
+interface RequestBodyStruct<C extends RequestBodyCodec, S extends StructLike<unknown, unknown, boolean>> extends StructMethods<Exclude<StructInput<S>, undefined>, Exclude<StructOutput<S>, undefined>, false>, StructLike<Exclude<StructInput<S>, undefined>, Exclude<StructOutput<S>, undefined>, false> {
+  readonly _struct: RequestBodyStructTypes<C, S>;
+}
+type RequestBinaryBodyStruct = Struct<ArrayBuffer, ArrayBuffer> | Struct<Blob, Blob>;
+type RequestBodyShapeStruct = RequestBinaryBodyStruct | RequestBodyStruct<RequestBodyCodec, StructLike<unknown, unknown, boolean>>;
+type RequestShape = {
+  body?: RequestBodyShapeStruct;
+  headers?: ObjectStruct<ObjectShape>;
+  path?: ObjectStruct<ObjectShape>;
+  query?: ObjectStruct<ObjectShape>;
+};
+type RequestObjectSectionInput<TKey extends 'headers' | 'path' | 'query', TSection> = TSection extends ObjectStruct<ObjectShape> ? {} extends StructInput<TSection> ? { [K in TKey]?: StructInput<TSection>; } : { [K in TKey]: StructInput<TSection>; } : {};
+type RequestInput<T extends RequestShape> = Simplify<RequestObjectSectionInput<'path', T['path']> & RequestObjectSectionInput<'query', T['query']> & RequestObjectSectionInput<'headers', T['headers']> & (T['body'] extends StructLike<unknown, unknown, boolean> ? {
+  body: StructInput<T['body']>;
+} : {})>;
+type RequestOutput<T extends RequestShape> = Simplify<(T['path'] extends ObjectStruct<ObjectShape> ? {
+  path: StructOutput<T['path']>;
+} : {}) & (T['query'] extends ObjectStruct<ObjectShape> ? {
+  query: StructOutput<T['query']>;
+} : {}) & (T['headers'] extends ObjectStruct<ObjectShape> ? {
+  headers: StructOutput<T['headers']>;
+} : {}) & (T['body'] extends StructLike<unknown, unknown, boolean> ? {
+  body: StructOutput<T['body']>;
+} : {})>;
+interface RequestStructTypes<T extends RequestShape> extends StructTypes<RequestInput<T>, RequestOutput<T>, false> {
+  input: RequestInput<T>;
+  optionalOut: undefined;
+  output: RequestOutput<T>;
+}
+/**
+ * Request-section struct produced by `struct.request({ path, query, headers, body })`.
+ *
+ * Groups path, query, headers, and body contracts used by HTTP/SSE/WebSocket builders.
+ */
+interface RequestStruct<T extends RequestShape> extends StructMethods<RequestInput<T>, RequestOutput<T>, false>, StructLike<RequestInput<T>, RequestOutput<T>, false> {
+  readonly _struct: RequestStructTypes<T>;
+}
+type RecordStruct<S extends StructLike<unknown, unknown, boolean>> = Struct<{
+  [key: string]: StructInput<S>;
+}, {
+  [key: string]: FieldOutput<S>;
+}>;
+type TupleStruct<T extends readonly StructLike<unknown, unknown, boolean>[]> = Struct<TupleInput<T>, TupleOutput<T>>;
+type UnionStruct<T extends readonly StructLike<unknown, unknown, boolean>[]> = Struct<UnionInput<T>, UnionOutput<T>>;
+type DiscriminatedUnionStruct<TOptions extends readonly ObjectStruct<ObjectShape>[]> = Struct<StructInput<TOptions[number]>, StructOutput<TOptions[number]>>;
+//#endregion
+//#region src/internal/request_values.d.ts
+interface RequestBodyOptions {
+  readonly contentType?: string | null;
+}
+//#endregion
+//#region src/internal/request_builder.d.ts
+type RequestTransport = 'http' | 'sse' | 'webSocket';
+declare const BOUND_SOURCE: unique symbol;
+declare const ARRAY_PROJECTION: unique symbol;
+type BuildBoundRef<TOutput = unknown> = {
+  readonly [BOUND_SOURCE]: {
+    readonly output: TOutput;
+  };
+};
+type BuildArrayProjection<TItem> = {
+  readonly [ARRAY_PROJECTION]: never;
+  readonly item: TItem;
+};
+type BuildArray<TItem, TOutput extends readonly unknown[]> = BuildBoundRef<TOutput> & {
+  map<TProjection>(callback: (item: TItem) => TProjection): BuildArrayProjection<TProjection>;
+};
+type BuildInput<T> = T extends {
+  readonly _struct: {
+    readonly output: infer TOutput;
+  };
+} ? BuildOutput<TOutput> : BuildBoundRef;
+type BuildOutput<TOutput> = TOutput extends readonly (infer TItem)[] ? BuildArray<BuildOutput<TItem>, TOutput> : TOutput extends {
+  [key: string]: unknown;
+} ? BuildBoundRef & { readonly [K in keyof TOutput]: BuildOutput<TOutput[K]>; } : BuildBoundRef<TOutput>;
+type BuildFlatScalar = bigint | boolean | Date | null | number | string | undefined;
+type BuildFlatValue = BuildFlatScalar | readonly BuildFlatScalar[];
+type BuildFormDataValue = BuildFlatValue | Blob | File | readonly (Blob | BuildFlatScalar | File)[];
+type BuildJsonProjection = BuildArrayProjection<unknown> | BuildBoundRef | undefined | readonly BuildJsonProjection[] | {
+  readonly [key: string]: BuildJsonProjection;
+};
+type BuildRecordProjection = {
+  readonly [key: string]: BuildBoundRef<BuildFlatValue> | undefined;
+};
+type BuildFormDataProjection = {
+  readonly [key: string]: BuildBoundRef<BuildFormDataValue> | undefined;
+};
+interface RequestBuilder {
+  addFormData(projection: BuildFormDataProjection): void;
+  addFormUrlEncoded(projection: BuildRecordProjection, options?: RequestBodyOptions): void;
+  addHeaders(projection: BuildRecordProjection): void;
+  setArrayBuffer(value: BuildBoundRef<ArrayBuffer>, options?: RequestBodyOptions): void;
+  setBlob(value: BuildBoundRef<Blob>, options?: RequestBodyOptions): void;
+  setFormData(projection: BuildFormDataProjection): void;
+  setFormUrlEncoded(projection: BuildRecordProjection, options?: RequestBodyOptions): void;
+  setHeaders(projection: BuildRecordProjection): void;
+  setHtml(value: BuildBoundRef<string>, options?: RequestBodyOptions): void;
+  setJson(projection: BuildJsonProjection, options?: RequestBodyOptions): void;
+  setPathParams(projection: BuildRecordProjection): void;
+  setQueryParams(projection: BuildRecordProjection): void;
+  setText(value: BuildBoundRef<string>, options?: RequestBodyOptions): void;
+}
+interface WebSocketRequestBuildContext {
+  setPathParams(projection: BuildRecordProjection): void;
+  setQueryParams(projection: BuildRecordProjection): void;
+}
+type RequestBuildInput<TInput extends AnyStruct | undefined> = [TInput] extends [undefined] ? unknown : TInput extends AnyStruct ? BuildInput<TInput> : never;
+type RequestBuildContext<TTransport extends RequestTransport = 'http'> = TTransport extends 'webSocket' ? WebSocketRequestBuildContext : RequestBuilder;
+type RequestBuildHandler<TInput extends AnyStruct | undefined, TTransport extends RequestTransport = 'http'> = (request: RequestBuildContext<TTransport>, input: RequestBuildInput<TInput>) => void;
+//#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 createRequestStruct<const T extends RequestShape>(shape: T): RequestStruct<T>;
+declare function createJsonBodyStruct<S extends StructLike<unknown, unknown, boolean>>(struct: S, options?: {
+  contentType?: string | null;
+}): RequestBodyStruct<'json', S>;
+declare function createUrlencodedBodyStruct<T extends ObjectShape>(shape: T): RequestBodyStruct<'urlencoded', ObjectStruct<T>>;
+declare function createFormDataBodyStruct<T extends ObjectShape>(shape: T): RequestBodyStruct<'formData', ObjectStruct<T>>;
+declare function createTextBodyStruct(): RequestBodyStruct<'text', StringStruct>;
+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): Struct<IntersectionInput<T>, IntersectionOutput<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` / `struct.request`, 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 getUserInput = struct.request({
+ *   path: struct.object({ id: struct.number() }),
+ * })
+ *
+ * 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 json: typeof createJsonBodyStruct;
+  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 request: typeof createRequestStruct;
+  readonly string: typeof createStringStruct;
+  readonly text: typeof createTextBodyStruct;
+  readonly tuple: typeof createTupleStruct;
+  readonly unknown: typeof createUnknownStruct;
+  readonly urlencoded: typeof createUrlencodedBodyStruct;
+};
+//#endregion
+//#region src/http/request.d.ts
+/**
+ * One status-to-body mapping used in the array form of `RequestOutputShape`.
+ * `status` may be a single code or a list of codes that share the same body struct.
+ */
+type ResponseGroupItem<S extends number = number, B extends AnyStruct = AnyStruct> = {
+  body: B;
+  status: S | readonly S[];
+};
+/**
+ * Declared HTTP response shapes keyed by status code, as a map or a list of `ResponseGroupItem`s.
+ */
+type RequestOutputShape = {
+  [key: number]: AnyStruct;
+} | readonly ResponseGroupItem[];
+//#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;
+}
+/** Fatal or recoverable error codes reported when an SSE stream closes with `code: 'error'`. */
+type EventStreamErrorCode = 'INVALID_RESPONSE' | 'MESSAGE_PROCESSING_FAILED' | 'PARSER_LIMIT_EXCEEDED' | 'QUEUE_OVERFLOW' | 'TIMEOUT' | 'TRANSPORT_ERROR';
+interface EventStreamCloseInfoBase {
+  reason?: string;
+  cause?: unknown;
+}
+/** How an SSE stream ended: clean EOF, abort, or an error with `errorCode`. */
+type EventStreamCloseInfo = (EventStreamCloseInfoBase & {
+  code: 'eof';
+}) | (EventStreamCloseInfoBase & {
+  code: 'aborted';
+}) | (EventStreamCloseInfoBase & {
+  code: 'error';
+  errorCode: EventStreamErrorCode;
+});
+/** 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/error/types.d.ts
+/**
+ * Error for an HTTP response whose status is treated as failure.
+ */
+export interface HttpStatusError<TErrorData = unknown, TStatus extends number = number> extends Error {
+  code: 'HTTP_STATUS';
+  data: TErrorData;
+  kind: 'http';
+  message: string;
+  response: HttpResponse<unknown>;
+  status: TStatus;
+}
+/**
+ * Error for transport-level failures such as abort, timeout, or network issues.
+ */
+export interface TransportError extends Error {
+  cause?: unknown;
+  code: 'ABORTED' | 'NETWORK_ERROR' | 'TIMEOUT';
+  kind: 'transport';
+  message: string;
+}
+/**
+ * Error for definition-time validation or undeclared response status failures.
+ */
+export type DefinitionError = (Error & {
+  cause?: unknown;
+  code: 'REQUEST_VALIDATION_FAILED' | 'RESPONSE_VALIDATION_FAILED' | 'INTERCEPTOR_FAILED';
+  kind: 'definition';
+  response?: HttpResponse<unknown>;
+}) | (Error & {
+  cause?: unknown;
+  code: 'UNDECLARED_STATUS';
+  kind: 'definition';
+  response: HttpResponse<unknown>;
+  status: number;
+});
+/**
+ * Union of HTTP status, transport, and definition errors from request execution.
+ *
+ * @typeParam TErrorData - Declared error body type for `HttpStatusError` variants.
+ */
+export type RequestError<TErrorData = unknown> = HttpStatusError<TErrorData> | TransportError | DefinitionError;
+//#endregion
+//#region src/error/factory.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;
+/**
+ * Build a `TransportError` from an abort, timeout, or other network cause.
+ *
+ * @param cause - Underlying abort/timeout/error value.
+ * @returns A normalized `TransportError`.
+ */
+export declare function createTransportError(cause: unknown): TransportError;
+/**
+ * Build a `DefinitionError` for request/response validation or undeclared status.
+ *
+ * @param code - Definition error code.
+ * @param cause - Underlying validation or status failure.
+ * @param response - HTTP response; required for `UNDECLARED_STATUS` (status is taken from it).
+ * @returns A normalized `DefinitionError`.
+ */
+export declare function createDefinitionError(code: 'UNDECLARED_STATUS', cause: unknown, response: HttpResponse<unknown>): Extract<DefinitionError, {
+  code: 'UNDECLARED_STATUS';
+}>;
+export declare function createDefinitionError(code: Exclude<DefinitionError['code'], 'UNDECLARED_STATUS'>, cause: unknown, response?: HttpResponse<unknown>): Extract<DefinitionError, {
+  code: Exclude<DefinitionError['code'], 'UNDECLARED_STATUS'>;
+}>;
+/**
+ * Build an `HttpStatusError` for a non-success HTTP status.
+ *
+ * @param status - HTTP status code.
+ * @param message - Human-readable error message.
+ * @param response - Full HTTP response.
+ * @param data - Optional parsed error body.
+ * @returns A normalized `HttpStatusError`.
+ */
+export declare function createHttpStatusError<TErrorData = unknown, TStatus extends number = number>(status: TStatus, message: string, response: HttpResponse<unknown>, data?: TErrorData): HttpStatusError<TErrorData, TStatus>;
+//#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 EndpointCommandBuilder<TInput extends AnyStruct | undefined, TCommand> = IsEndpointInputOptional<TInput> extends true ? (input?: EndpointInput<TInput>) => TCommand : (input: EndpointInput<TInput>) => TCommand;
+//#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` builder.
+ * Carries the request definition and optional typed input for `client.execute`.
+ */
+export interface HttpCommand<TInput extends AnyStruct | undefined, TOutput extends RequestOutputShape | undefined> extends BaseCommand<typeof HTTP_COMMAND> {
+  readonly definition: RequestDefinition<TInput, TOutput>;
+  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;
+};
+/**
+ * Builder returned by `defineRequest`; call with input to create an `HttpCommand`.
+ */
+export type RequestCommandBuilder<TInput extends AnyStruct | undefined, TOutput extends RequestOutputShape | undefined> = EndpointCommandBuilder<TInput, HttpCommand<TInput, TOutput>>;
+type ResponsePairForStatus<TBody extends AnyStruct, TStatus> = TStatus extends readonly (infer U extends number)[] ? U extends number ? {
+  body: TBody;
+  status: U;
+} : never : TStatus extends number ? {
+  body: TBody;
+  status: TStatus;
 } : 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[];
+type ResponsePair<TOutput extends RequestOutputShape | undefined> = NonNullable<TOutput> extends readonly (infer TItem)[] ? TItem extends {
+  body: infer TBody extends AnyStruct;
+  status: infer TStatus;
+} ? ResponsePairForStatus<TBody, TStatus> : never : { [K in keyof NonNullable<TOutput>]: NonNullable<TOutput>[K] extends (infer TBody extends AnyStruct) ? K extends number ? {
+  body: TBody;
+  status: K;
+} : K extends `${infer TStatus extends number}` ? {
+  body: TBody;
+  status: TStatus;
+} : never : never; }[keyof NonNullable<TOutput>];
+type HttpStatusErrorByOutput<TOutput extends RequestOutputShape | undefined> = [TOutput] extends [undefined] ? HttpStatusError<undefined> : ResponsePair<TOutput> extends (infer TPair) ? TPair extends {
+  body: infer TBody extends AnyStruct;
+  status: infer TStatus extends number;
+} ? `${TStatus}` extends `2${string}` ? never : HttpStatusError<Infer<TBody>, TStatus> : never : never;
+type RequestErrorByOutput<TOutput extends RequestOutputShape | undefined> = HttpStatusErrorByOutput<TOutput> | TransportError | DefinitionError;
+type ResponseBodyByStatus<TOutput extends RequestOutputShape | undefined, TOk extends boolean> = ResponsePair<TOutput> extends (infer TPair) ? TPair extends {
+  body: infer TBody extends AnyStruct;
+  status: infer TStatus extends number;
+} ? `${TStatus}` extends `2${string}` ? TOk extends true ? TBody : never : TOk extends true ? never : TBody : never : never;
+type InferResponseBodyByStatus<TOutput extends RequestOutputShape | undefined, TOk extends boolean> = [TOutput] extends [undefined] ? undefined : [ResponseBodyByStatus<TOutput, TOk>] extends [never] ? unknown : Infer<ResponseBodyByStatus<TOutput, TOk>>;
+/** Inferred success body type for 2xx statuses declared in `TOutput`. */
+export type RequestSuccessData<TOutput extends RequestOutputShape | undefined> = InferResponseBodyByStatus<TOutput, true>;
+/** Inferred error-body type for non-2xx statuses declared in `TOutput`. */
+export type RequestErrorData<TOutput extends RequestOutputShape | undefined> = InferResponseBodyByStatus<TOutput, false>;
+type ResponseDeclaration<TOutput extends RequestOutputShape | undefined> = [TOutput] extends [undefined] ? {
+  output?: never;
+  responseType?: never;
+} : {
+  output: TOutput;
+  responseType?: HttpResponseType;
 };
+/**
+ * Contract for an HTTP endpoint: method, path, optional input struct, and status-keyed outputs.
+ * Pass to `defineRequest` to get a typed command builder.
+ */
+export type RequestDefinition<TInput extends AnyStruct | undefined = undefined, TOutput extends RequestOutputShape | undefined = undefined> = ResponseDeclaration<TOutput> & {
+  operation?: string;
+} & ({
+  method: string;
+  path: string;
+  build?: never;
+  input?: TInput;
+} | (TInput extends AnyStruct ? {
+  method: string;
+  path: string;
+  build: RequestBuildHandler<TInput>;
+  input: TInput;
+} : never));
+/**
+ * Await-result tuple for an HTTP call: success `[null, body, response]` or failure `[error, undefined, response?]`.
+ */
+export type HttpAwaitResult<TSuccess = unknown, TErrorData = unknown> = [error: null, result: TSuccess, response: HttpResponse<TSuccess>] | [error: RequestError<TErrorData>, result: undefined, response: HttpResponse<unknown> | undefined];
+type HttpExecuteAwaitResult<TOutput extends RequestOutputShape | undefined> = [error: null, result: RequestSuccessData<TOutput>, response: HttpResponse<RequestSuccessData<TOutput>>] | [error: RequestErrorByOutput<TOutput>, result: undefined, response: HttpResponse<unknown> | undefined];
+/**
+ * Declare a typed HTTP request command builder.
+ *
+ * Pass method, path, optional input struct, and status-keyed output structs.
+ * Call the returned builder with input to get an `HttpCommand` for `client.execute`.
+ *
+ * @param definition - Request contract (method, path, input, output).
+ * @returns A builder that creates `HttpCommand` values from input.
+ *
+ * @example
+ * ```ts
+ * const getUser = defineRequest({
+ *   method: 'GET',
+ *   path: '/users/:id',
+ *   input: struct.request({ path: struct.object({ id: struct.number() }) }),
+ *   output: [{ status: 200, body: struct.object({ id: struct.number(), name: struct.string() }) }],
+ * })
+ * ```
+ */
+export declare function defineRequest<TInput extends AnyStruct, const TOutput extends RequestOutputShape | undefined = undefined>(definition: RequestDefinition<TInput, TOutput>): RequestCommandBuilder<TInput, TOutput>;
+export declare function defineRequest<TInput extends AnyStruct | undefined = undefined, const TOutput extends RequestOutputShape | undefined = undefined>(definition: RequestDefinition<TInput, TOutput>): RequestCommandBuilder<TInput, TOutput>;
+/**
+ * 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` builder.
+ * @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 RequestOutputShape | undefined>(clientConfig: HttpClientConfig, command: HttpCommand<TInput, TOutput>, options?: HttpExecuteOptions): Promise<HttpExecuteAwaitResult<TOutput>>;
+//#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;
+/** 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;
+  /** Optional non-2xx handshake bodies; fills `error.data` when the open status is declared. */
+  output?: RequestOutputShape;
+  path: string;
+}
+type EventStreamDefinitionWithoutBuild<TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs> = EventStreamDefinitionBase<TEvents> & {
+  build?: never;
+  input?: TInput;
+};
+type EventStreamDefinitionWithBuild<TInput extends AnyStruct, TEvents extends EventStructs = EventStructs> = EventStreamDefinitionBase<TEvents> & {
+  build: RequestBuildHandler<TInput, 'sse'>;
+  input: TInput;
+};
+/** Contract describing an SSE endpoint: path, events, and buffer/queue limits. */
+export type EventStreamDefinition<TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs> = EventStreamDefinitionWithoutBuild<TInput, TEvents> | (TInput extends AnyStruct ? EventStreamDefinitionWithBuild<TInput, TEvents> : never);
+/** Await-result tuple from opening an SSE stream via `client.execute`. */
+export type StreamAwaitResult<TEvent> = [error: null, stream: EventStreamHandle<TEvent>, open: EventStreamOpenInfo] | [error: RequestError<unknown>, stream: undefined, open: EventStreamOpenInfo | undefined];
+/** Executable SSE command produced by an `EventStreamCommandBuilder`. */
+export interface EventStreamCommand<TInput extends AnyStruct | undefined, TEvents extends EventStructs> extends BaseCommand<typeof EVENT_STREAM_COMMAND> {
+  readonly endpoint: EventStreamEndpoint<TInput, TEvents>;
+  readonly input: EndpointInput<TInput> | undefined;
+}
+/** Per-execute options for SSE commands (abort, timeout). */
+export type EventStreamExecuteOptions = UseCancellationConfig & {
+  signal?: AbortSignal;
+};
+/** Builder function that creates `EventStreamCommand` values from endpoint input. */
+export type EventStreamCommandBuilder<TInput extends AnyStruct | undefined, TEvents extends EventStructs> = EndpointCommandBuilder<TInput, EventStreamCommand<TInput, TEvents>>;
+type EventStreamEndpoint<TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs> = EventStreamDefinition<TInput, TEvents> & {
+  readonly method: string;
+};
+/**
+ * Declare a typed Server-Sent Events command builder.
+ *
+ * Pass path, event structs, and buffer/queue limits. Call the returned builder
+ * with input to get an `EventStreamCommand` for `client.execute`.
+ *
+ * @param definition - SSE contract (path, events, buffer limits, optional input).
+ * @returns A builder 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<TInput extends AnyStruct, TEvents extends EventStructs = EventStructs>(definition: EventStreamDefinitionWithBuild<TInput, TEvents>): EventStreamCommandBuilder<TInput, TEvents>;
+export declare function defineEventStream<TInput extends AnyStruct | undefined = undefined, TEvents extends EventStructs = EventStructs>(definition: EventStreamDefinitionWithoutBuild<TInput, TEvents>): EventStreamCommandBuilder<TInput, TEvents>;
+/**
+ * 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 `EventStreamCommandBuilder`.
+ * @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>(clientConfig: ClientConfig, command: EventStreamCommand<TInput, TEvents>, options?: EventStreamExecuteOptions): Promise<StreamAwaitResult<EventStreamData<TEvents>>>;
+//#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;
+type CommandType = typeof HTTP_COMMAND | typeof EVENT_STREAM_COMMAND | typeof WEB_SOCKET_COMMAND;
+interface BaseCommand<TCommandType extends CommandType> {
+  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';
+/** Map of WebSocket message type names to payload structs. */
+export type SocketStructs = {
+  [key: string]: AnyStruct;
+};
+export interface NormalizedWebSocketIncoming {
+  data: unknown;
+  type: string;
+}
+export type NormalizedWebSocketOutgoing = boolean | null | number | string | readonly unknown[] | {
+  readonly [key: string]: unknown;
+};
+export type WebSocketIncomingNormalizer = (decoded: unknown) => NormalizedWebSocketIncoming | undefined;
+export type WebSocketOutgoingNormalizer = (type: string, encodedPayload: unknown) => NormalizedWebSocketOutgoing;
+type SimplifySocket<T> = { [K in keyof T]: T[K]; } & {};
+type NormalizeSocketMessage<TKey extends string, TPayload> = TPayload extends {
+  [key: string]: unknown;
+} ? SimplifySocket<{
+  type: TKey;
+} & TPayload> : {
+  data: TPayload;
+  type: TKey;
+};
+type SocketSendMessage<TKey extends string, TPayload> = TPayload extends {
+  [key: string]: unknown;
+} ? SimplifySocket<{
+  type: TKey;
+} & TPayload> | {
+  data: TPayload;
+  type: TKey;
+} : {
+  data: TPayload;
+  type: TKey;
+};
+type KnownIncomingSocketUnion<TIncoming extends SocketStructs> = { [K in keyof TIncoming & string as K extends 'default' ? never : K]: NormalizeSocketMessage<K, Infer<TIncoming[K]>>; } extends (infer O) ? O[keyof O] : never;
+type KnownOutgoingSocketUnion<TOutgoing extends SocketStructs> = { [K in keyof TOutgoing & string as K extends 'default' ? never : K]: SocketSendMessage<K, EndpointInput<TOutgoing[K]>>; } extends (infer O) ? O[keyof O] : never;
+type DefaultIncomingSocketUnion<TIncoming extends SocketStructs> = 'default' extends keyof TIncoming ? NormalizeSocketMessage<string, Infer<TIncoming['default']>> : never;
+/** Incoming message shape inferred from an incoming `SocketStructs` map. */
+export type WebSocketIncomingData<TIncoming extends SocketStructs> = [KnownIncomingSocketUnion<TIncoming> | DefaultIncomingSocketUnion<TIncoming>] extends [never] ? never : KnownIncomingSocketUnion<TIncoming> | DefaultIncomingSocketUnion<TIncoming>;
+/** Outgoing message shape inferred from an outgoing `SocketStructs` map. */
+export type WebSocketOutgoingData<TOutgoing extends SocketStructs | undefined> = TOutgoing extends SocketStructs ? [KnownOutgoingSocketUnion<TOutgoing>] extends [never] ? never : KnownOutgoingSocketUnion<TOutgoing> : never;
+interface WebSocketDefinitionBase<TIncoming extends SocketStructs = SocketStructs, TOutgoing extends SocketStructs | undefined = undefined> {
+  incoming: TIncoming;
+  maxIncomingQueueSize: number;
+  maxOutgoingQueueSize?: number;
+  normalizeIncoming?: WebSocketIncomingNormalizer;
+  normalizeOutgoing?: WebSocketOutgoingNormalizer;
+  operation?: string;
+  outgoing?: TOutgoing;
+  path: string;
+  protocols?: readonly string[];
+}
+type WebSocketDefinitionWithoutBuild<TInput extends AnyStruct | undefined = undefined, TIncoming extends SocketStructs = SocketStructs, TOutgoing extends SocketStructs | undefined = undefined> = WebSocketDefinitionBase<TIncoming, TOutgoing> & {
+  build?: never;
+  input?: TInput;
+};
+type WebSocketDefinitionWithBuild<TInput extends AnyStruct, TIncoming extends SocketStructs = SocketStructs, TOutgoing extends SocketStructs | undefined = undefined> = WebSocketDefinitionBase<TIncoming, TOutgoing> & {
+  build: RequestBuildHandler<TInput, 'webSocket'>;
+  input: TInput;
+};
+/** Contract describing a WebSocket endpoint: path, message structs, and queue limits. */
+export type WebSocketDefinition<TInput extends AnyStruct | undefined = undefined, TIncoming extends SocketStructs = SocketStructs, TOutgoing extends SocketStructs | undefined = undefined> = WebSocketDefinitionWithoutBuild<TInput, TIncoming, TOutgoing> | (TInput extends AnyStruct ? WebSocketDefinitionWithBuild<TInput, TIncoming, TOutgoing> : never);
+/** 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: RequestError<unknown>, 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 `WebSocketCommandBuilder`. */
+export interface WebSocketCommand<TInput extends AnyStruct | undefined, TIncoming extends SocketStructs, TOutgoing extends SocketStructs | undefined> extends BaseCommand<typeof WEB_SOCKET_COMMAND> {
+  readonly endpoint: WebSocketEndpoint<TInput, TIncoming, TOutgoing>;
+  readonly input: EndpointInput<TInput> | undefined;
+}
+/** Builder function that creates `WebSocketCommand` values from endpoint input. */
+export type WebSocketCommandBuilder<TInput extends AnyStruct | undefined, TIncoming extends SocketStructs, TOutgoing extends SocketStructs | undefined> = EndpointCommandBuilder<TInput, WebSocketCommand<TInput, TIncoming, TOutgoing>>;
+type WebSocketEndpoint<TInput extends AnyStruct | undefined = undefined, TIncoming extends SocketStructs = SocketStructs, TOutgoing extends SocketStructs | undefined = undefined> = WebSocketDefinition<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?: <T = TOutgoing>() => T | unknown;
+  timeoutMs?: number;
+}
+/**
+ * Declare a typed WebSocket command builder.
+ *
+ * Pass path, incoming (and optional outgoing) message structs, and queue limits.
+ * Call the returned builder with input to get a `WebSocketCommand` for `client.execute`.
+ *
+ * @param definition - WebSocket contract (path, structs, queue limits, optional input).
+ * @returns A builder that creates `WebSocketCommand` values from input.
+ *
+ * @example
+ * ```ts
+ * const useChat = defineWebSocket({
+ *   maxIncomingQueueSize: 16,
+ *   path: '/ws/chat',
+ *   incoming: { message: struct.object({ text: struct.string() }) },
+ *   outgoing: { message: struct.object({ text: struct.string() }) },
+ * })
+ * ```
+ */
+export declare function defineWebSocket<TInput extends AnyStruct, TIncoming extends SocketStructs = SocketStructs, TOutgoing extends SocketStructs | undefined = undefined>(definition: WebSocketDefinitionWithBuild<TInput, TIncoming, TOutgoing>): WebSocketCommandBuilder<TInput, TIncoming, TOutgoing>;
+export declare function defineWebSocket<TInput extends AnyStruct | undefined = undefined, TIncoming extends SocketStructs = SocketStructs, TOutgoing extends SocketStructs | undefined = undefined>(definition: WebSocketDefinitionWithoutBuild<TInput, TIncoming, TOutgoing>): WebSocketCommandBuilder<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 `WebSocketCommandBuilder`.
+ * @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 SocketStructs, TOutgoing extends SocketStructs | 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 query parameters for the request URL.
+ *
+ * @param params - Normalized `URLSearchParams` built from the request.
+ * @param rawParams - Optional original param object before normalization.
+ * @returns The query string (without a leading `?`).
+ */
+type QueryParamsSerializer = (params: URLSearchParams, rawParams?: {
+  [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;
+  };
+  /** Called when an incoming message has no matching struct (unknown `type`). Struct/JSON failures still use `onRuntimeError`. */
+  onInvalidEvent?: (context: {
+    reason: 'missing-struct';
+    message: {
+      type: string;
+      data: unknown;
+    };
+  }) => unknown;
+}
+/** 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[];
+  /** Custom query-string serializer. */
+  queryParamsSerializer?: QueryParamsSerializer;
+  /** 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[];
+  /** Query-string serializer used for requests. */
+  queryParamsSerializer: QueryParamsSerializer;
+  /** 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.
+ *
+ * Command `struct.request({ headers })` values 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;
+/**
+ * Replaces the serializer used when encoding query parameters.
+ *
+ * @param serializer - Function that turns params into a query string.
+ * @returns An option that sets `config.queryParamsSerializer`.
+ */
+export declare function withQueryParamsSerializer(serializer: QueryParamsSerializer): 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 WebSocket messages whose `type` has no matching incoming struct.
+ *
+ * JSON/Struct decode failures still go to `session.onRuntimeError`. Unknown types
+ * do not tear down the session.
+ *
+ * @param handler - Observer callback; failures are isolated.
+ * @returns An option that sets `config.webSocket.onInvalidEvent`.
+ */
+export declare function withWebSocketOnInvalidEvent(handler: ClientWebSocketOptions['onInvalidEvent']): 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>(command: EventStreamCommand<TInput, TEvents>, options?: EventStreamExecuteOptions): Promise<StreamAwaitResult<EventStreamData<TEvents>>>;
+  /** Open a WebSocket command and return session await results. */
+  execute<TInput extends AnyStruct | undefined, TIncoming extends SocketStructs, TOutgoing extends SocketStructs | 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 RequestOutputShape | undefined>(command: HttpCommand<TInput, TOutput>, options?: HttpExecuteOptions): ReturnType<typeof executeHttpCommand<TInput, TOutput>>;
+};
+/**
+ * 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`.
+ * @returns Parsed `HttpResponse`, or a status-0 response when the network/abort fails.
+ */
+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, Client, ClientConfig, ClientOption, ClientOptions, ClientSSEConfig, ClientSSEOptions, ClientWebSocketOptions, ErrorMap, EventStreamCloseInfo, EventStreamErrorCode, EventStreamHandle, EventStreamOpenInfo, FetchHandle, FlattenedStructError, FormattedStructError, HttpInterceptor, HttpInterceptorNext, HttpProgressEvent, HttpProgressFn, HttpRequest, HttpResponse, HttpResponseType, Infer, Interceptor, InterceptorFn, MakeResponseOptions, ObjectStruct, ParseResult, QueryParamsSerializer, RequestOutputShape, RequestStruct, ResponseGroupItem, SSEHandler, SSEInterceptor, SSEInterceptorFn, Struct, StructInput, StructIssue, StructLike, StructMethods, WebSocketHandle, WebSocketHandleConstructor, WebSocketHandler, WebSocketInterceptor, WebSocketInterceptorFn, WebSocketSessionLike };