@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type ms from "ms";
+import type { SerializedCookieJar } from "tough-cookie";
 import type { infer as ZodInfer, ZodType } from "zod";
 /** Minimal Standard Schema v1 shape accepted by provider operations. */
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
@@ -46,6 +47,8 @@ export interface OperationToolRouterMetadata {
     riskClass?: OperationRiskClass;
     /** OpenAI remote-MCP approval hint. Defaults from riskClass. */
     approval?: OperationApprovalPolicy;
+    /** Canonical operation-level connection requirement consumed by the registry and Gateway. */
+    connectionMode?: "none" | "optional" | "required";
     /** Override connection requirement when provider auth + openWorld inference is insufficient. */
     requiresConnection?: boolean;
     /** Public argument used to resolve the tenant-owned connection. Defaults to externalRef. */
@@ -609,9 +612,11 @@ export interface HealthMonitorProbeOverride {
     /** Optional degraded threshold override for generated registry probes. */
     degradedThresholdMs?: number;
 }
+export declare const VALID_OPERATION_ERROR_STATUSES: readonly [400, 401, 404, 409, 410, 422, 429, 500, 502, 503, 504];
+export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number];
 export interface OperationErrorCode {
     code: string;
-    status?: number;
+    status?: ProviderErrorStatus;
     description: string;
     retryable?: boolean;
 }
@@ -645,12 +650,30 @@ export interface StealthProfile {
     h2Settings?: Record<string, unknown>;
     headerOrder?: string[];
 }
-export type AuthMode = "none" | "platform-managed" | "credentials" | "oauth2";
+export type AuthMode = "none" | "platform-managed" | "credentials" | "oauth2" | "oauth2_proxied";
 export type ConnectionMode = AuthMode;
 export type ProviderReviewed = "first-party" | "community" | "staging";
 export type ProviderAccessVisibility = "public" | "early_access";
 export type ProviderProxyMode = "disabled" | "optional" | "required";
-export type ProviderProxyProvider = "smartproxy" | "decodo" | "custom";
+/**
+ * Proxy egress vendors. These are FOUR DISTINCT services — do not conflate them
+ * (a common mistake because the names collide with a well-known rebrand):
+ *
+ * - `smartproxy` — **api.smartproxy.org**, a residential proxy with an IP
+ *	 *extraction/allocation* API (app_key → a pool of raw `ip:port` CONNECT
+ *	 endpoints). This is our own vendor. It is NOT the company formerly named
+ *	 "Smartproxy". Credentials: `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ * - `nodemaven` — **gate.nodemaven.com**, a *gateway* proxy with static
+ *	 credentials; geo/session encoded in the username, no allocation API.
+ * - `decodo` — **decodo.com**, the *gateway* proxy that was named "Smartproxy"
+ *	 (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
+ *	 username params. A different company from `smartproxy` above.
+ *	 **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
+ *	 or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
+ * - `custom` — **@deprecated** bring-your-own static proxy URL marker. The
+ *	 `APIFUSE__PROXY__URL` env still works without declaring this value.
+ */
+export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 export type ProviderProxySessionAffinity = "request" | "operation" | "auth-flow" | "connection";
 export interface ProviderProxyPolicy {
     /**
@@ -658,7 +681,18 @@ export interface ProviderProxyPolicy {
      * certificate verification, and vendor allocator endpoints are SDK-owned.
      */
     mode: ProviderProxyMode;
+    /**
+     * @deprecated Use `providers: [...]` to declare an ordered vendor fallback
+     * chain. A single-element `providers` list is equivalent to this field.
+     */
     provider?: ProviderProxyProvider;
+    /**
+     * Ordered proxy-vendor fallback chain. The SDK tries each vendor in order and
+     * fails over to the next when a vendor lacks credentials or its allocation /
+     * transport is exhausted. When omitted, `provider` (or the platform default)
+     * is used as a single-vendor chain.
+     */
+    providers?: ProviderProxyProvider[];
     geo?: {
         /** ISO 3166-1 alpha-2 country code, for example KR or US. */
         country?: Iso3166Alpha2CountryCode;
@@ -669,6 +703,12 @@ export interface ProviderProxyPolicy {
         affinity?: ProviderProxySessionAffinity;
         lifetimeMinutes?: number;
         poolSize?: number;
+        /**
+         * Seconds before hard sticky expiry at which native connections receive
+         * the `expiring` event so the provider can drain and reconnect cleanly.
+         * Declared by the provider; the SDK does not assume a default cut point.
+         */
+        drainLeadSeconds?: number;
     };
 }
 export type ProviderProxyConfig = boolean | ProviderProxyPolicy;
@@ -677,9 +717,9 @@ export interface ProviderAccessConfig {
      * Provider-level rollout visibility.
      *
      * - `public`: visible in public docs/catalog/OpenAPI and callable through
-     *   the existing provider policy stack.
+     *	 the existing provider policy stack.
      * - `early_access`: hidden from public discovery and callable only when the
-     *   active customer organization has a provider-level access grant.
+     *	 active customer organization has a provider-level access grant.
      *
      * This is intentionally provider-level only. It does not alter auth mode,
      * operation schemas, health-check authoring, `openWorld`, or Connection
@@ -810,6 +850,11 @@ export interface HttpRetrySummary {
 export interface RequestOptions {
     headers?: Record<string, string>;
     params?: RequestParams;
+    /**
+     * Query parameters whose values contain credentials or other secret material.
+     * They are sent like `params`, but redacted from SDK errors, traces, and recorded fixtures.
+     */
+    sensitiveParams?: Record<string, string>;
     proxy?: string;
     timeout?: number;
     /**
@@ -818,12 +863,33 @@ export interface RequestOptions {
      */
     throwOnHttpError?: boolean;
     retry?: boolean | HttpRetryPreset | HttpRetryOptions;
+    /**
+     * Opt-in redirect-hop enforcement for ctx.http. When present, redirects are
+     * evaluated before the next request is issued. Existing callers that omit
+     * this policy retain the native fetch redirect behavior.
+     */
+    redirectPolicy?: HttpRedirectPolicy;
 }
+export type RedirectRunReason = "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+export type HttpRedirectPolicyMode = "same-origin";
+export interface HttpRedirectPolicy {
+    /** Only follow redirects whose canonical scheme, host, and port match the initial URL. */
+    mode: HttpRedirectPolicyMode;
+    /** Maximum number of redirect hops that may be followed. Must be an integer from 0 to 20. */
+    maxHops: number;
+}
+export type HttpRedirectFailureReason = Exclude<RedirectRunReason, "completed">;
 export type HttpMethod = "HEAD" | "head" | "GET" | "get" | "POST" | "post" | "PUT" | "put" | "DELETE" | "delete" | "OPTIONS" | "options" | "TRACE" | "trace" | "PATCH" | "patch";
-export interface StealthFetchOptions extends RequestOptions {
+export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy"> {
     method?: HttpMethod;
     body?: string | Buffer;
     redirect?: "follow" | "manual" | "error";
+    /**
+     * Maximum decoded response-body bytes to buffer. When set, the stealth
+     * transport aborts the response and throws `response_too_large` if the
+     * declared or streamed body exceeds this limit.
+     */
+    maxBodyBytes?: number;
     /**
      * Offsets policy-managed proxy pool selection for caller-managed retries.
      * Use when a request receives an upstream challenge page rather than a
@@ -843,17 +909,42 @@ export interface StealthFetchOptions extends RequestOptions {
     };
 }
 export interface CookieJar {
-    get(name: string): string | undefined;
-    getAll(): Record<string, string>;
-    toString(): string;
-    find?(predicate: (cookie: string) => boolean): string | undefined;
+    /** URL-less reads use the jar's response URL or session base URL. */
+    get(name: string, url?: string): string | undefined;
+    getAll(url?: string): Record<string, string>;
+    toString(url?: string): string;
+    find?(predicate: (cookie: string) => boolean, url?: string): string | undefined;
 }
+/**
+ * Version 1 of the JSON-safe, attribute-preserving stealth cookie store.
+ * The nested jar is tough-cookie's serialized form and retains cookie origin,
+ * Path, Secure, expiry, host-only, and other RFC attributes.
+ */
+export interface StealthCookieStoreV1 {
+    readonly version: 1;
+    readonly jar: SerializedCookieJar;
+}
+/** Cookie persistence formats understood by this SDK version. */
+export type StealthCookieStore = StealthCookieStoreV1;
 export interface StealthSessionCookies extends CookieJar {
-    has(name: string): boolean;
-    setFromCookieStrings(cookieStrings: readonly string[]): void;
-    toHeader(): string;
+    has(name: string, url?: string): boolean;
+    /** URL-less writes are scoped to the session base URL. */
+    setFromCookieStrings(cookieStrings: readonly string[], url?: string): void;
+    toHeader(url?: string): string;
+    /**
+     * Returns every cookie as a flat name/value map, collapsing duplicate names.
+     * @deprecated Use serialize() for lossless, attribute-preserving persistence.
+     */
     snapshot(): Record<string, string>;
+    /**
+     * Restores flat values as host-only, Path=/ cookies on the session base URL.
+     * @deprecated Use deserialize() with state produced by serialize().
+     */
     restore(cookies: Record<string, string>): void;
+    /** Returns a versioned, JSON-safe, attribute-preserving representation of every cookie. */
+    serialize(): StealthCookieStoreV1;
+    /** Replaces the jar with a previously serialized, attribute-preserving cookie store. */
+    deserialize(state: StealthCookieStore): void;
     clear(): void;
 }
 export interface DeclarativeStealthResponse {
@@ -895,8 +986,14 @@ export interface StealthRedirectRunOptions extends Omit<StealthFetchOptions, "re
 export interface StealthRedirectRunResult {
     final: StealthResponse;
     hops: StealthRedirectHop[];
-    reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+    reason: RedirectRunReason;
+    /**
+     * Complete flat view across all redirect hosts. Attributes and duplicate names are lost.
+     * @deprecated Use cookieStore for lossless persistence.
+     */
     cookies: Record<string, string>;
+    /** Versioned, attribute-preserving cookie state accumulated across the redirect chain. */
+    cookieStore: StealthCookieStoreV1;
 }
 export interface StealthSession {
     fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
@@ -959,6 +1056,154 @@ export interface HttpClient {
     stream(url: string, options?: RequestWithMethodOptions): Promise<HttpStreamResponse>;
     sse(url: string, options?: RequestWithMethodOptions): Promise<AsyncIterable<SseMessage>>;
 }
+/** Request-scoped file reference accepted by provider operation inputs. */
+export interface ProviderFileRef {
+    readonly type: "request_file";
+    readonly id: string;
+    readonly filename: string;
+    readonly mime_type?: string;
+    readonly size: number;
+    readonly sha256?: string;
+}
+/** File body resolved from a request-scoped {@link ProviderFileRef}. */
+export type ProviderResolvedFile = Omit<ProviderFileRef, "mime_type"> & {
+    readonly mimeType?: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+    stream(): ReadableStream<Uint8Array>;
+};
+/** Resolver supplied by runtimes that accept request-scoped file inputs. */
+export interface ProviderFilesContext {
+    has(input: string | ProviderFileRef): boolean;
+    resolve(input: string | ProviderFileRef): Promise<ProviderResolvedFile>;
+}
+export type NativeTcpTlsMode = "required" | "allowed" | "disabled";
+export interface NativeTcpPortRange {
+    readonly start: number;
+    readonly end: number;
+}
+/** Static native TCP egress declared by a provider. */
+export interface NativeTcpEgressRule {
+    readonly host: string;
+    readonly ports: readonly number[];
+    readonly tls: NativeTcpTlsMode;
+}
+/**
+ * Bounded native TCP egress discovered through a declared bootstrap endpoint.
+ * Host suffixes are exact DNS suffixes, not wildcard patterns.
+ * Dynamic rules must declare at least one target host selector through
+ * targetHostSuffixes, targetIpv4Cidrs, and/or targetIpv6Cidrs. Literal grant
+ * sources and targets match only same-family selectors (except exact
+ * sourceHost); DNS names match only host/suffix selectors. IPv4-mapped and
+ * IPv4-compatible IPv6 literals are authorized only by IPv4 CIDRs.
+ *
+ * Dynamic rules are ordered. The first rule whose source, target, port, and TLS
+ * selectors match exclusively owns the grant; its ttlMs and maxGrants bounds
+ * apply, and an exhausted/shorter rule never falls through to a later overlap.
+ * Every rule must declare a source host selector, source port list/range, and
+ * target port list/range; omitted ttlMs/maxGrants remain unbounded.
+ */
+export interface NativeTcpDynamicEgressRule {
+    readonly sourceHost?: string;
+    readonly sourceHostSuffixes?: readonly string[];
+    readonly sourceIpv4Cidrs?: readonly string[];
+    readonly sourceIpv6Cidrs?: readonly string[];
+    readonly sourcePorts?: readonly number[];
+    readonly sourcePortRanges?: readonly NativeTcpPortRange[];
+    readonly targetHostSuffixes?: readonly string[];
+    readonly targetIpv4Cidrs?: readonly string[];
+    readonly targetIpv6Cidrs?: readonly string[];
+    readonly targetPorts?: readonly number[];
+    readonly targetPortRanges?: readonly NativeTcpPortRange[];
+    readonly tls: NativeTcpTlsMode;
+    readonly ttlMs?: number;
+    readonly maxGrants?: number;
+}
+/** Common TCP/TLS connection input supported by the native runtime. */
+export interface NativeNetworkConnectInput {
+    readonly host: string;
+    readonly port: number;
+    readonly serverName?: string;
+    readonly rejectUnauthorized?: boolean;
+    /**
+     * Maximum time without a successful socket read before the connection is
+     * closed. Opt-in; when absent, reads can remain pending indefinitely.
+     */
+    readonly idleTimeoutMs?: number;
+    /** Maximum time allowed to establish the TCP/SOCKS/TLS connection. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** Overrides the credential-derived sticky affinity key. */
+    readonly affinityKey?: string;
+}
+export type NativeNetworkConnectOptions = Omit<NativeNetworkConnectInput, "serverName" | "rejectUnauthorized">;
+export type NativeTlsConnectOptions = NativeNetworkConnectInput;
+export interface NativeNetworkDynamicGrantOptions {
+    readonly sourceHost: string;
+    readonly sourcePort: number;
+    readonly host: string;
+    readonly port: number;
+    readonly tls: NativeTcpTlsMode;
+    readonly ttlMs?: number;
+}
+export interface NativeNetworkEgressGrant {
+    revoke(): void;
+}
+/** Consumer-facing alias used by native TCP providers. */
+export type NativeTcpEgressGrant = NativeNetworkEgressGrant;
+/** Resolved egress identity for a native connection routed through a proxy. */
+export interface NativeProxyEgressInfo {
+    readonly vendor: ProviderProxyProvider;
+    readonly sticky: boolean;
+    /** Vendor sticky session id (sid). Absent for rotating sessions. */
+    readonly sessionId?: string;
+    /** Hard expiry of the sticky binding, ISO 8601. */
+    readonly expiresAt?: string;
+}
+export type NativeProxyExpiringReason = "sticky_expiry";
+export interface NativeProxyExpiringEvent {
+    readonly expiresAt: string;
+    readonly leadSeconds: number;
+    readonly reason: NativeProxyExpiringReason;
+}
+/**
+ * Cooperative drain handler. The SDK awaits this before closing a socket whose
+ * sticky proxy binding is about to expire, then force-closes at hard expiry.
+ */
+export type NativeProxyDrainHandler = (event: NativeProxyExpiringEvent) => void | Promise<void>;
+/** Typed reason recorded when the SDK closes a native connection intentionally. */
+export interface NativeNetworkCloseReason {
+    readonly code: string;
+    readonly message: string;
+}
+/** Byte-oriented connection returned by the native TCP/TLS runtime. */
+export interface NativeNetworkConnection {
+    /** Present when the connection was routed through a proxy. */
+    readonly proxy?: NativeProxyEgressInfo;
+    /** Present after an SDK-planned close, such as sticky proxy expiry. */
+    readonly closeReason?: NativeNetworkCloseReason;
+    /** Register a cooperative drain handler for sticky-expiry reconnects. */
+    onExpiring?(handler: NativeProxyDrainHandler): void;
+    read(): Promise<Uint8Array | null>;
+    write(data: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+}
+export interface NativeNetworkClient {
+    connectTcp(input: NativeNetworkConnectOptions): Promise<NativeNetworkConnection>;
+    connectTls(input: NativeTlsConnectOptions): Promise<NativeNetworkConnection>;
+    grantTcpEgress(input: NativeNetworkDynamicGrantOptions): NativeNetworkEgressGrant;
+}
+export interface NativeContext {
+    readonly network: NativeNetworkClient;
+}
+/** Consumer-facing alias for the native capability on provider contexts. */
+export type NativeProviderContext = NativeContext;
+export interface NativeProviderConfig {
+    readonly network?: {
+        readonly tcp?: readonly NativeTcpEgressRule[];
+        readonly dynamicTcp?: readonly NativeTcpDynamicEgressRule[];
+    };
+}
 export interface ProviderCacheKeyOptions {
     /**
      * Additional field names to omit from stable key material. The SDK always
@@ -1285,11 +1530,15 @@ export interface AuthFlowTerminalContext {
     }): AuthTurn;
 }
 export interface FlowContext {
+    /** Gateway auth-flow id. Required by flow-scoped auth ceremonies. */
+    flowId?: string;
     connectionId?: string;
     externalRef?: string;
     tenantId: string;
     providerId: string;
     http: HttpClient;
+    /** Present when the selected runtime supplies native network capabilities. */
+    readonly native?: NativeProviderContext;
     stealth: StealthClient;
     env: EnvContext;
     credential?: CredentialContext;
@@ -1375,6 +1624,10 @@ export interface ProviderContext {
     credential: CredentialContext;
     request?: ProviderRequestContext;
     http: HttpClient;
+    /** Present for requests carrying runtime-resolvable file references. */
+    readonly files?: ProviderFilesContext;
+    /** Present when the selected runtime supplies native network capabilities. */
+    readonly native?: NativeProviderContext;
     cache: ProviderCache;
     state: ProviderRuntimeState;
     stealth: StealthClient;
@@ -1384,8 +1637,20 @@ export interface ProviderContext {
     stt: SttContext;
     choice: ProviderChoiceContext;
 }
+export interface ProxiedOAuthConfig {
+    authorizeUrl: string;
+    tokenUrl: string;
+    customScheme: string;
+    rewriteProfile: string;
+    clientIdEnvKey: string;
+    pkce?: "S256" | "none";
+    authorizeParams?: Record<string, string>;
+    tokenParams?: Record<string, string>;
+}
 export interface AuthConfig {
     mode: AuthMode;
+    /** Browser reverse-proxy contract for providers with custom-scheme OAuth callbacks. */
+    proxied?: ProxiedOAuthConfig;
     flow?: AuthFlowDefinition;
 }
 export interface ProviderSecretDeclaration {
@@ -1418,6 +1683,19 @@ export interface OperationContractMetadata {
     deprecation?: OperationDeprecationMetadata;
 }
 export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike> {
+    /**
+     * Short English display title for the operation. The SDK passes it through
+     * verbatim; the APIFuse registry derives the operation's en locale title
+     * baseline from it (`docs.titleKey` remains available as an explicit key
+     * override).
+     */
+    title?: string;
+    /**
+     * Raw English operation description. The SDK passes it through verbatim;
+     * keyed descriptions via `descriptionKey` remain the primary flow, and
+     * provider lint rules for raw prose descriptions still apply.
+     */
+    description?: string;
     descriptionKey?: ProviderLocaleKeyInput;
     docs?: OperationDocMeta;
     whenToUseKeys?: readonly ProviderLocaleKeyInput[];
@@ -1438,6 +1716,11 @@ export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOu
     fixtures?: {
         request: InferSchemaOutput<TInput>;
         response: InferSchemaOutput<TOutput>;
+        /**
+         * KST calendar date when `response` evidence was captured. Date fields in
+         * the response align with this date, not a resolved relative request date.
+         */
+        recordedAt?: string;
     };
     upstream?: {
         baseUrl?: string;
@@ -1447,11 +1730,56 @@ export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOu
     healthCheck?: HealthCheckSuite<InferSchemaOutput<TInput>, InferSchemaOutput<TOutput>>;
     healthCheckUnsupported?: HealthCheckUnsupported;
 }
+/**
+ * Author-declared deployment overrides accepted as the optional top-level
+ * `deployment` key on `defineProvider()`.
+ *
+ * The SDK passes this object through VERBATIM onto the returned provider
+ * definition — it is typed here but deliberately not deep-validated: the
+ * APIFuse registry builder owns deployment validation and resolves omitted
+ * fields against the runtime deployment profiles. The shape mirrors the
+ * registry's `ProviderDeploymentOverrides` contract; every field is
+ * optional. Note that the deployment `runtime` axis
+ * (`shared`/`dedicated`/`browser`) is distinct from the provider execution
+ * `runtime` (`standard`/`shared`/`browser`).
+ */
+export interface ProviderDeploymentOverrides {
+    runtime?: "shared" | "dedicated" | "browser";
+    language?: "typescript" | "python";
+    replicas?: number;
+    hpa?: {
+        enabled: boolean;
+        minReplicas?: number;
+        maxReplicas?: number;
+        targetCPUUtilizationPercentage?: number;
+    };
+    resources?: {
+        cpu: string;
+        memory: string;
+    };
+    cache?: {
+        redis?: {
+            enabled: boolean;
+            url?: string;
+        };
+    };
+    network?: {
+        additionalTcpPorts?: number[];
+    };
+    buildContext?: string;
+}
 export interface ProviderDefinition {
     id: string;
     version: string;
     runtime: "standard" | "shared" | "browser";
+    /**
+     * Optional deployment overrides, passed through verbatim from
+     * `defineProvider({ deployment })`. Validation and profile resolution are
+     * owned by the APIFuse registry builder, not the SDK.
+     */
+    deployment?: ProviderDeploymentOverrides;
     allowedHosts?: string[];
+    native?: NativeProviderConfig;
     stealth?: {
         profile: string;
         platform: StealthPlatform;

package/dist/types.js

@@ -32,6 +32,7 @@ export const HEALTH_CHECK_TIMEOUT_MS_MIN = 1;
 export const HEALTH_CHECK_TIMEOUT_MS_MAX = 60_000;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN = 1;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX = 60_000;
+export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 409, 410, 422, 429, 500, 502, 503, 504];
 export const HttpRetryPreset = {
     Off: "off",
     TransportTransient: "transport_transient",

package/dist/user-input.d.ts

@@ -0,0 +1,30 @@
+export declare const NEEDS_INPUT_STATUS: "needs_input";
+export interface ProviderSelectionOption {
+    readonly selection_value: string;
+    readonly label: string;
+    readonly [extra: string]: unknown;
+}
+export interface ProviderRequiredSelection {
+    readonly selection_key: string;
+    readonly label: string;
+    readonly required: boolean;
+    readonly selection_type?: string;
+    readonly valid_options: readonly ProviderSelectionOption[];
+    readonly [extra: string]: unknown;
+}
+export interface ProviderSelectedOption {
+    readonly selection_key: string;
+    readonly selection_value: string;
+    /** Free-text answer for text-kind selections. */
+    readonly text?: string;
+    /** Quantity for quantity-kind selections. */
+    readonly quantity?: number;
+}
+export interface ProviderNeedsInputPayload {
+    readonly status: typeof NEEDS_INPUT_STATUS;
+    readonly required_selections: readonly ProviderRequiredSelection[];
+    readonly selected_options?: readonly ProviderSelectedOption[];
+    /** Provider-specific fresh state token(s), e.g. `reservation_state`. */
+    readonly [extra: string]: unknown;
+}
+export declare function isProviderNeedsInputPayload(value: unknown): value is ProviderNeedsInputPayload;

package/dist/user-input.js

@@ -0,0 +1,66 @@
+// Official cross-provider contract for user-input round-trips.
+//
+// Doctrine (born from the 2026-07-20 CatchTable reserve incident): an
+// operation MUST NOT dead-end on a problem the end user can resolve by
+// choosing among live options. Instead of throwing, the provider returns a
+// SUCCESSFUL payload with `status: "needs_input"` that carries everything a
+// consumer-side agent needs to relay the choice verbatim and retry:
+//
+// - `required_selections`: only the still-pending questions, each with
+//   human-readable `label`s and `valid_options` the agent shows the user
+//   as-is. The agent never chooses on the user's behalf.
+// - `selected_options`: selections already settled, echoed so the follow-up
+//   call keeps them without the agent reconstructing anything.
+// - a fresh provider-specific state token (e.g. `reservation_state`) minted
+//   at response time, so the retry never races an expired token.
+//
+// Keeping this success-shaped (instead of error `details`) is deliberate:
+// consumer error-shaping layers routinely strip error metadata, and a model
+// that only sees "error" narrates failure to the user. Complex recovery
+// logic belongs to the system, not the model.
+//
+// Deliberately ABSENT: retry templates, next-action routing, or any other
+// agent choreography. Provider payloads carry upstream-backed data only; how
+// to phrase the ask and shape the retry call is the consumer's contract
+// (apifuse#1030). The retry is fully determined by data: copy the echoed
+// selected_options, add the user's new answers, resend with the fresh state.
+export const NEEDS_INPUT_STATUS = "needs_input";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSelectionOption(value) {
+    return (isRecord(value) &&
+        typeof value.selection_value === "string" &&
+        typeof value.label === "string");
+}
+function isRequiredSelection(value) {
+    return (isRecord(value) &&
+        typeof value.selection_key === "string" &&
+        typeof value.label === "string" &&
+        typeof value.required === "boolean" &&
+        Array.isArray(value.valid_options) &&
+        value.valid_options.every(isSelectionOption));
+}
+function isSelectedOption(value) {
+    return (isRecord(value) &&
+        typeof value.selection_key === "string" &&
+        typeof value.selection_value === "string");
+}
+export function isProviderNeedsInputPayload(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (value.status !== NEEDS_INPUT_STATUS ||
+        !Array.isArray(value.required_selections) ||
+        !value.required_selections.every(isRequiredSelection)) {
+        return false;
+    }
+    // A needs_input with nothing to ask AND nothing settled to echo is a
+    // no-op dead end — reject it so providers cannot ship it accidentally.
+    if (value.required_selections.length > 0) {
+        return true;
+    }
+    return (Array.isArray(value.selected_options) &&
+        value.selected_options.length > 0 &&
+        value.selected_options.every(isSelectedOption));
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.2",
+	"version": "2.2.0-beta.21",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -61,6 +61,11 @@
 			"import": "./dist/server/index.js",
 			"default": "./dist/server/index.js"
 		},
+		"./stateful": {
+			"types": "./dist/stateful/index.d.ts",
+			"import": "./dist/stateful/index.js",
+			"default": "./dist/stateful/index.js"
+		},
 		"./testing": {
 			"types": "./dist/testing/index.d.ts",
 			"import": "./dist/testing/index.js",
@@ -75,24 +80,28 @@
 	"scripts": {
 		"lint": "biome lint .",
 		"lint:fix": "biome lint --write",
+		"lint:deprecated": "bun run scripts/lint-deprecated-usage.ts",
 		"format": "biome format --write",
-		"type-check": "tsgo --noEmit",
+		"type-check": "tsc --noEmit",
 		"test": "bun test",
-		"check": "bun run lint && bun run type-check && bun run build",
+		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run build",
 		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
 		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
+		"pack:types": "bun run build && bun bin/apifuse-pack-types.ts",
 		"release:guard": "bun scripts/guard-release-pr.ts",
 		"format:check": "biome format .",
-		"build": "tsgo -p tsconfig.build.json && rm -rf dist/cli/templates && cp -R src/cli/templates dist/cli/templates && rm -rf dist/auth-turn/fixtures && cp -R src/auth-turn/fixtures dist/auth-turn/fixtures && cp src/auth-turn/auth-turn.v1.schema.json dist/auth-turn/auth-turn.v1.schema.json"
+		"build": "tsc -p tsconfig.build.json && rm -rf dist/cli/templates && cp -R src/cli/templates dist/cli/templates && rm -rf dist/auth-turn/fixtures && cp -R src/auth-turn/fixtures dist/auth-turn/fixtures && cp src/auth-turn/auth-turn.v1.schema.json dist/auth-turn/auth-turn.v1.schema.json"
 	},
 	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.5",
 		"@biomejs/biome": "^2.5.0",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
-		"@typescript/native-preview": "7.0.0-dev.20260419.1"
+		"typescript": "6.0.3"
 	},
 	"dependencies": {
 		"@clack/prompts": "^1.5.1",
+		"@rgrove/parse-xml": "4.2.2",
 		"@types/ms": "^2.1.0",
 		"acorn": "^8.17.0",
 		"ajv": "^8.17",
@@ -105,6 +114,8 @@
 		"puppeteer-extra-plugin-stealth": "^2.11.2",
 		"re2-wasm": "^1.0",
 		"safe-regex": "^2.1",
+		"socks": "^2.8.9",
+		"tough-cookie": "^6.0.2",
 		"zod": "^4.4.3"
 	},
 	"repository": {

package/src/auth-turn/index.ts

@@ -1,4 +1,4 @@
-import type { AuthTurn } from "../types";
+import type { AuthTurn } from "../types.js";
 
 export type { AuthTurn };