@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.10

package/src/types.ts

@@ -331,9 +331,20 @@ export interface HealthJourneySchedule {
 	kind: "interval";
 	/** ISO 8601 duration, for example PT8H. */
 	interval: Iso8601Duration;
+	randomize?: HealthScheduleRandomization;
 	jitter?: Iso8601Duration;
 }
 
+export type HealthScheduleRandomization =
+	| {
+			mode: "centered";
+			maxOffset: Iso8601Duration;
+	  }
+	| {
+			mode: "delayed";
+			maxDelay: Iso8601Duration;
+	  };
+
 export interface HealthJourneyStep {
 	id: string;
 	description?: string;
@@ -612,6 +623,9 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
 export interface HealthCheckSuite<TInput = unknown, TOutput = unknown> {
 	/** Polling interval for the suite. All cases share this cadence. */
 	interval: ProbeInterval;
+	schedule?: {
+		randomize?: HealthScheduleRandomization;
+	};
 	/** Per-case timeout in milliseconds. Default: 30000. */
 	timeoutMs?: number;
 	/** Default degradation threshold for cases in this suite. Default: runtime threshold. */
@@ -687,6 +701,14 @@ export interface ProviderHealthMonitorConfig {
 	serviceAccount?: string;
 }
 
+/**
+ * New name for `ProviderHealthMonitorConfig` as part of the health dependency
+ * inversion (`healthMonitor` → `healthProbe`). Both provider-level fields are
+ * accepted transitionally with identical validation; declaring both is a
+ * `ValidationError`.
+ */
+export type ProviderHealthProbeConfig = ProviderHealthMonitorConfig;
+
 export interface HealthMonitorProbeOverride {
 	/** Optional runtime interval override as a positive `ms`-style duration string. */
 	interval?: ProbeInterval;
@@ -747,7 +769,25 @@ 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"
@@ -761,7 +801,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;
@@ -979,6 +1030,7 @@ export type HttpMethod =
 export interface StealthFetchOptions extends RequestOptions {
 	method?: HttpMethod;
 	body?: string | Buffer;
+	redirect?: "follow" | "manual" | "error";
 	/**
 	 * Offsets policy-managed proxy pool selection for caller-managed retries.
 	 * Use when a request receives an upstream challenge page rather than a
@@ -1005,9 +1057,20 @@ export interface CookieJar {
 	find?(predicate: (cookie: string) => boolean): string | undefined;
 }
 
+export interface StealthSessionCookies extends CookieJar {
+	has(name: string): boolean;
+	setFromCookieStrings(cookieStrings: readonly string[]): void;
+	toHeader(): string;
+	snapshot(): Record<string, string>;
+	restore(cookies: Record<string, string>): void;
+	clear(): void;
+}
+
 export interface DeclarativeStealthResponse {
 	status: number;
 	ok: boolean;
+	url?: string;
+	redirected?: boolean;
 	headers: Record<string, string>;
 	rawHeaders: [string, string][];
 	body: string;
@@ -1026,8 +1089,34 @@ export type RequestWithMethodOptions = RequestOptions & {
 	body?: unknown;
 };
 
+export interface StealthRedirectHop {
+	url: string;
+	status: number;
+	method: string;
+	location?: string;
+	nextUrl?: string;
+}
+
+export interface StealthRedirectRunOptions
+	extends Omit<StealthFetchOptions, "redirect"> {
+	url: string;
+	maxHops?: number;
+	stopWhen?: (hop: StealthRedirectHop) => boolean | Promise<boolean>;
+}
+
+export interface StealthRedirectRunResult {
+	final: StealthResponse;
+	hops: StealthRedirectHop[];
+	reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+	cookies: Record<string, string>;
+}
+
 export interface StealthSession {
 	fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
+	cookies: StealthSessionCookies;
+	redirects: {
+		run(options: StealthRedirectRunOptions): Promise<StealthRedirectRunResult>;
+	};
 	close(): void;
 }
 
@@ -1050,6 +1139,8 @@ export interface HttpResponse<T = unknown> {
 	data: T;
 	json<U = T>(): Promise<U>;
 	text(): Promise<string>;
+	arrayBuffer(): Promise<ArrayBuffer>;
+	bytes(): Promise<Uint8Array>;
 }
 
 export interface HttpStreamResponse {
@@ -1206,6 +1297,45 @@ export interface BrowserFrame {
 	locator(selector: string): BrowserLocator;
 }
 
+export type BrowserResourceMethod = "GET" | "HEAD";
+
+export type BrowserResourceRequest = {
+	readonly url: string;
+	readonly method: BrowserResourceMethod;
+	readonly resourceType?: string;
+	readonly headers: Readonly<Record<string, string>>;
+};
+
+export type BrowserResourceBody = Buffer | Uint8Array | ArrayBuffer | string;
+
+export type BrowserResourceDecision =
+	| {
+			readonly action: "fulfill";
+			readonly status?: number;
+			readonly headers?: Readonly<Record<string, string>>;
+			readonly body?: BrowserResourceBody;
+	  }
+	| {
+			readonly action: "block";
+			readonly reason?: string;
+	  };
+
+export type BrowserResourceRoute = {
+	readonly match:
+		| string
+		| RegExp
+		| ((request: BrowserResourceRequest) => boolean);
+	readonly handle: (
+		request: BrowserResourceRequest,
+	) => Promise<BrowserResourceDecision> | BrowserResourceDecision;
+};
+
+export type BrowserResourcePolicy = {
+	readonly defaultAction?: "block";
+	readonly allowedMethods?: readonly BrowserResourceMethod[];
+	readonly routes: readonly BrowserResourceRoute[];
+};
+
 export interface BrowserPage extends BrowserFrame {
 	close(): Promise<void>;
 	fill(selector: string, text: string): Promise<void>;
@@ -1219,6 +1349,10 @@ export interface BrowserPage extends BrowserFrame {
 		options?: { timeout?: number },
 	): Promise<void>;
 	frames(): Promise<BrowserFrame[]>;
+	withResourcePolicy<T>(
+		policy: BrowserResourcePolicy,
+		run: () => Promise<T>,
+	): Promise<T>;
 }
 
 export type BrowserChallengeRequest = {
@@ -1397,6 +1531,84 @@ export interface ContextScratchpad {
 
 export type FlowContextStore = ContextScratchpad;
 
+export type AuthSafeJson =
+	| string
+	| number
+	| boolean
+	| null
+	| readonly AuthSafeJson[]
+	| { readonly [key: string]: AuthSafeJson };
+
+export type AuthSafeData = { readonly [key: string]: AuthSafeJson };
+
+export type AuthAbortRetry = "never" | "retry" | "after_user_action";
+
+export type AuthAbortData = Record<string, unknown> & {
+	readonly code: string;
+	readonly message?: string;
+	readonly retry?: AuthAbortRetry;
+	readonly actionHint?: AuthSafeJson;
+	readonly fieldErrors?: { readonly [field: string]: string };
+	readonly details?: AuthSafeData;
+};
+
+export interface AuthFlowTerminalContext {
+	readonly signal?: AbortSignal;
+	readonly deadline?: string;
+	complete<TCredential extends Record<string, string>>(options: {
+		readonly credential: TCredential;
+		readonly metadata?: AuthSafeData;
+		readonly data?: AuthSafeData;
+		readonly turnId?: string;
+		readonly expiresAt?: string;
+	}): AuthTurn;
+	abort(options: {
+		readonly code: string;
+		readonly message?: string;
+		readonly retry?: AuthAbortRetry;
+		readonly actionHint?: AuthSafeJson;
+		readonly fieldErrors?: { readonly [field: string]: string };
+		readonly data?: AuthSafeData;
+		readonly turnId?: string;
+		readonly expiresAt?: string;
+	}): AuthTurn;
+	nextForm(
+		options: {
+			readonly hintKey?: ProviderLocaleKeyInput;
+			readonly data?: AuthSafeData;
+			readonly turnId?: string;
+			readonly expiresAt?: string;
+			readonly timing?: AuthTurn["timing"];
+		} & (
+			| {
+					readonly fields: Record<
+						string,
+						{
+							readonly type?: "string" | "email" | "password" | "otp";
+							readonly labelKey?: ProviderLocaleKeyInput;
+							readonly descriptionKey?: ProviderLocaleKeyInput;
+							readonly placeholderKey?: ProviderLocaleKeyInput;
+							readonly required?: boolean;
+							readonly sensitive?: boolean;
+						}
+					>;
+					readonly expectedInput?: never;
+			  }
+			| {
+					readonly expectedInput: Record<string, unknown>;
+					readonly fields?: never;
+			  }
+		),
+	): AuthTurn;
+	nextPoll(options?: {
+		readonly hintKey?: ProviderLocaleKeyInput;
+		readonly data?: AuthSafeData;
+		readonly turnId?: string;
+		readonly expiresAt?: string;
+		readonly timing?: AuthTurn["timing"];
+	}): AuthTurn;
+}
+
 export interface FlowContext {
 	connectionId?: string;
 	externalRef?: string;
@@ -1408,6 +1620,7 @@ export interface FlowContext {
 	credential?: CredentialContext;
 	context: ContextScratchpad;
 	stt: SttContext;
+	auth: AuthFlowTerminalContext;
 }
 
 export interface AuthTurn {
@@ -1575,6 +1788,19 @@ 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[];
@@ -1613,10 +1839,55 @@ export interface OperationDefinition<
 	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[];
 	stealth?: {
 		profile: string;
@@ -1636,5 +1907,7 @@ export interface ProviderDefinition {
 	meta: ProviderMeta;
 	operations: Record<string, OperationDefinition<SchemaLike, SchemaLike>>;
 	healthMonitor?: ProviderHealthMonitorConfig;
+	/** Transitional alias for `healthMonitor`; `defineProvider` mirrors both. */
+	healthProbe?: ProviderHealthProbeConfig;
 	healthJourneys?: readonly HealthJourneyDefinition[];
 }

package/src/user-input.ts

@@ -0,0 +1,118 @@
+// 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" as const;
+
+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;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isSelectionOption(value: unknown): value is ProviderSelectionOption {
+	return (
+		isRecord(value) &&
+		typeof value.selection_value === "string" &&
+		typeof value.label === "string"
+	);
+}
+
+function isRequiredSelection(
+	value: unknown,
+): value is ProviderRequiredSelection {
+	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: unknown): value is ProviderSelectedOption {
+	return (
+		isRecord(value) &&
+		typeof value.selection_key === "string" &&
+		typeof value.selection_value === "string"
+	);
+}
+
+export function isProviderNeedsInputPayload(
+	value: unknown,
+): value is ProviderNeedsInputPayload {
+	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)
+	);
+}