@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/src/observability.ts

@@ -1,4 +1,5 @@
-export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-05-26";
+// Mirrors packages/provider-observability in the platform monorepo (SoT).
+export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-08-07";
 
 export const PROVIDER_ERROR_CATEGORIES = [
 	"ok",
@@ -7,6 +8,7 @@ export const PROVIDER_ERROR_CATEGORIES = [
 	"upstream_http",
 	"upstream_rate_limited",
 	"upstream_auth",
+	"upstream_rejected",
 	"upstream_schema_drift",
 	"proxy_pool",
 	"anti_bot_blocked",
@@ -16,6 +18,9 @@ export const PROVIDER_ERROR_CATEGORIES = [
 	"output_validation",
 	"provider_error",
 	"internal_error",
+	"dependency_unavailable",
+	"unsupported_transport",
+	"client_cancelled",
 	"unclassified",
 ] as const;
 
@@ -26,6 +31,9 @@ export function categoryForStatus(status: number): ProviderErrorCategory {
 	if (status === 408 || status === 504) return "timeout";
 	if (status === 429) return "upstream_rate_limited";
 	if (status === 401 || status === 403) return "upstream_auth";
+	// provider-error-contract: 409/410/422 are the deterministic
+	// upstream-rejection status class — not a retryable upstream failure.
+	if (status === 409 || status === 410 || status === 422) return "upstream_rejected";
 	if (status >= 400) return "upstream_http";
 	return "unclassified";
 }
@@ -39,3 +47,45 @@ export function isRetryableCategory(category: ProviderErrorCategory): boolean {
 		category === "proxy_pool"
 	);
 }
+
+// Who stopped the request (honest-provider-error-contract). A deliberately
+// small public projection of the internal taxonomy:
+// - client: the request itself is fixable by the caller
+// - upstream_rule: the upstream service refused it under its own business
+//   rules (deterministic) or rate limits
+// - upstream_failure: the upstream service malfunctioned — retryable
+// - apifuse: an APIFuse-side fault (provider bug, platform dependency)
+export const PROVIDER_ERROR_SOURCES = [
+	"client",
+	"upstream_rule",
+	"upstream_failure",
+	"apifuse",
+] as const;
+
+export type ProviderErrorSource = (typeof PROVIDER_ERROR_SOURCES)[number];
+
+export function sourceForCategory(category: ProviderErrorCategory): ProviderErrorSource {
+	switch (category) {
+		case "input_validation":
+		case "credential_expired":
+		case "credential_unavailable":
+		case "client_cancelled":
+			return "client";
+		case "upstream_rejected":
+		case "upstream_rate_limited":
+			return "upstream_rule";
+		case "timeout":
+		case "network":
+		case "upstream_http":
+		case "upstream_auth":
+		case "upstream_schema_drift":
+		case "anti_bot_blocked":
+			return "upstream_failure";
+		default:
+			// ok never reaches error serialization; provider_error,
+			// internal_error, output_validation, proxy_pool,
+			// dependency_unavailable, unsupported_transport, unclassified are
+			// APIFuse-side faults.
+			return "apifuse";
+	}
+}

package/src/provider.ts

@@ -1,9 +1,3 @@
-export {
-	AuthAbortError,
-	credentialsAuthChallenge,
-	createAuthFlowHelpers,
-	defineCredentialsAuth,
-} from "./auth.js";
 export type {
 	CredentialsAuthChallengeDefinition,
 	CredentialsAuthChallengeRequest,
@@ -17,46 +11,201 @@ export type {
 	DefineCredentialsAuthOptions,
 	DefinedCredentialsAuth,
 } from "./auth.js";
-export { createFormCeremony } from "./ceremonies/index.js";
 export {
-	assertFreshProviderChoiceIssuedAt,
-	createProviderChoiceToken,
-	ProviderChoiceTokenError,
-	type ProviderChoiceTokenErrorReason,
-	type ProviderChoiceTokenPayload,
-	parseProviderChoiceToken,
-} from "./choice-token.js";
+	AuthAbortError,
+	createAuthFlowHelpers,
+	credentialsAuthChallenge,
+	defineCredentialsAuth,
+} from "./auth.js";
+export { createFormCeremony } from "./ceremonies/index.js";
+export type { JsonPrimitive, JsonValue } from "./contract-json.js";
+export type {
+	OperationDefinitionFor,
+	ProviderBuilder,
+	ProviderContextOf,
+	ProviderDeclaration,
+	ProviderDefinitionFor,
+} from "./define.js";
 export {
 	centered,
-	delayed,
 	defineHealthJourney,
 	defineOperation,
 	defineProvider,
 	defineSmsOtpMatcher,
+	delayed,
 	every,
 } from "./define.js";
+export type {
+	ProviderCapabilityKey,
+	ProviderEngine,
+	ProviderEngineAttachmentInput,
+	ProviderEngineBindingCandidates,
+	ProviderEngineCapabilitySurface,
+	ProviderEngineMode,
+	ProviderEngineRequest,
+	ProviderEngineResidentSurface,
+	ProviderEngineSession,
+	ProviderEngineTransport,
+} from "./engine.js";
+export {
+	createInProcessProviderEngine,
+	createProviderEnvironment,
+	ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES,
+	ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES,
+	ENGINE_OWNED_RUNTIME_ENV_NAMES,
+	ENGINE_OWNED_TELEMETRY_ENV_NAMES,
+	isEngineOwnedEnvName,
+	isEngineOwnedProxyCredentialName,
+	isEngineOwnedResolverCredentialName,
+	isEngineOwnedRuntimeEnvName,
+	isEngineOwnedTelemetryEnvName,
+	PROVIDER_CAPABILITY_KEYS,
+	PROVIDER_ENGINE_MODE_ENV,
+	PROVIDER_ENGINE_PROTOCOL_VERSION,
+	readEngineProxyCredentials,
+} from "./engine.js";
 export {
 	AuthError,
+	HttpRedirectError,
 	isProviderError,
 	isSessionExpiredError,
 	isTransportError,
+	ProviderEgressDeniedError,
+	ProviderEngineAuthenticationError,
+	ProviderEngineProtocolVersionError,
+	ProviderEngineUnavailableError,
 	ProviderError,
+	type ProviderErrorObservability,
+	SDKError,
 	SessionExpiredError,
 	TransportError,
 	ValidationError,
 } from "./errors.js";
+export * from "./handle.js";
+export {
+	APIFUSE_HANDLE_META_KEY,
+	HANDLE_KIND_NAME_PATTERN,
+	handleFieldDescription,
+	handleFieldNameFor,
+	handleHasDirectionalFieldNames,
+	isHandleFieldMeta,
+} from "./handle-meta.js";
+export type {
+	AssertionExpression,
+	AssertionPredicate,
+	AssertResult,
+	AssertStep,
+	AttemptReference,
+	BoundedJsonPath,
+	CandidateBlock,
+	CandidatePolicy,
+	CandidateReference,
+	CredentialRefDeclaration,
+	CredentialReference,
+	EstablishedConnectionReference,
+	ExtractResult,
+	ExtractStep,
+	FindFirst,
+	GuardAttribution,
+	GuardReasonCode,
+	GuardResult,
+	GuardStep,
+	HealthScenario,
+	HealthStep,
+	JournalPolicy,
+	JsonTemplate,
+	ManualTriggerPolicy,
+	NonEmpty,
+	Operand,
+	OperationResult,
+	OperationStep,
+	Quantifier,
+	Reference,
+	ReferenceNode,
+	RelativeDateNode,
+	RetryPolicy,
+	SafeRegex,
+	ScopedAssertionExpression,
+	ScopedAssertionPredicate,
+	ScopedItemReference,
+	ScopedOperand,
+	StepBase,
+	StepReference,
+	ValueType,
+} from "./health-scenario.js";
+export {
+	AssertionExpressionSchema,
+	AssertionPredicateSchema,
+	AssertStepSchema,
+	BoundedJsonPathSchema,
+	CandidateBlockSchema,
+	CandidatePolicySchema,
+	CredentialRefDeclarationSchema,
+	defineHealthScenario,
+	ExtractStepSchema,
+	FindFirstSchema,
+	GUARD_REASON_CODES,
+	GuardStepSchema,
+	HealthScenarioSchema,
+	HealthStepSchema,
+	JournalPolicySchema,
+	JsonTemplateSchema,
+	ManualTriggerPolicySchema,
+	OperandSchema,
+	OperationStepSchema,
+	QuantifierSchema,
+	ReferenceSchema,
+	RelativeDateNodeSchema,
+	RetryPolicySchema,
+	SafeRegexSchema,
+	ScopedAssertionExpressionSchema,
+	ScopedAssertionPredicateSchema,
+	ScopedItemReferenceSchema,
+	ScopedOperandSchema,
+	StepReferenceSchema,
+	ValueTypeSchema,
+} from "./health-scenario.js";
 export {
 	getProviderLocalePath,
+	type ProviderErrorMessageParams,
 	providerLocaleKey,
 	qualifyProviderLocaleKey,
 } from "./i18n/index.js";
 export {
-	type CreateProviderChoiceContextOptions,
-	createProviderChoiceContext,
-	createTestProviderChoiceContext,
-	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-} from "./runtime/choice.js";
+	type CreateHandleContextOptions,
+	type CreateTestHandleContextOptions,
+	createHandleContext,
+	createTestHandleContext,
+	type HandleNormalizationClass,
+	type NormalizedHandle,
+	normalizeHandle,
+} from "./runtime/handle.js";
+export type {
+	NativeGatewayProxy,
+	NativeGatewayProxyResolutionInput,
+	NativeGatewayProxySkipReason,
+	NativeGatewayProxySynthesisInput,
+	NativeGatewayProxySynthesisResult,
+	NativeGatewayProxySynthesizer,
+	NativeNetworkClientOptions,
+	NativeNetworkErrorCode,
+	VendorCredentialLookup,
+	VendorCredentialResolver,
+} from "./runtime/native-network.js";
+export {
+	NativeEgressGrantExpiredError,
+	NativeEgressNotDeclaredError,
+	NativeIdleTimeoutError,
+	NativeNetworkError,
+	NativeProxyExpiredError,
+} from "./runtime/native-network-errors.js";
+export {
+	createMemoryProviderRuntimeState,
+	createUnsupportedProviderRuntimeState,
+} from "./runtime/state.js";
 export {
+	APIFUSE_CONTENT_PROVENANCE_META_KEY,
+	APIFUSE_CONTENT_TRUST_META_KEY,
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
 	APIFUSE_SENSITIVE_KIND_META_KEY,
@@ -66,11 +215,13 @@ export {
 	field,
 	fields,
 	isSensitiveSchema,
+	publicField,
 	redactPayload,
 	type SensitiveFieldKind,
 	type SensitiveFieldOptions,
 	type SensitivePath,
 	sensitive,
+	untrustedContent,
 	z,
 } from "./schema.js";
 export type {
@@ -91,31 +242,53 @@ export type {
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
 	HealthScheduleRandomization,
+	HttpAttemptContext,
+	HttpHeadersFactory,
+	HttpRedirectFailureReason,
+	HttpRedirectPolicy,
+	HttpRedirectPolicyMode,
 	HttpRetryOptions,
 	HttpRetrySummary,
 	InferSchemaOutput,
+	NativeContext,
+	NativeNetworkClient,
+	NativeNetworkCloseReason,
+	NativeNetworkConnectInput,
+	NativeNetworkConnection,
+	NativeNetworkConnectOptions,
+	NativeNetworkDynamicGrantOptions,
+	NativeNetworkEgressGrant,
+	NativeProviderConfig,
+	NativeProxyDrainHandler,
+	NativeProxyEgressInfo,
+	NativeProxyExpiringEvent,
+	NativeProxyExpiringReason,
+	NativeTcpDynamicEgressRule,
+	NativeTcpEgressGrant,
+	NativeTcpEgressRule,
+	NativeTcpPortRange,
+	NativeTcpTlsMode,
+	NativeTlsConnectOptions,
 	OperationApprovalPolicy,
 	OperationContractMetadata,
 	OperationDefinition,
-	OperationDocMeta,
 	OperationErrorCode,
-	OperationInputExample,
+	OperationExample,
 	OperationLifecycle,
 	OperationObservabilityConfig,
 	OperationObservabilitySensitiveConfig,
 	OperationRelationships,
 	OperationRiskClass,
 	OperationSensitivePath,
-	OperationToolRouterMetadata,
 	OperationTransport,
 	ProviderAccessVisibility,
-	ProviderChoiceBindingOptions,
-	ProviderChoiceContext,
-	ProviderChoiceIssueOptions,
-	ProviderChoiceParseOptions,
 	ProviderContext,
+	ProviderContextFor,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
+	ProviderErrorStatus,
+	ProviderFileRef,
+	ProviderFilesContext,
 	ProviderLocale,
 	ProviderLocaleKey,
 	ProviderLocaleKeyInput,
@@ -123,17 +296,24 @@ export type {
 	ProviderProxyPolicy,
 	ProviderPublicConnectionMode,
 	ProviderPublicProfile,
+	ProviderResolvedFile,
 	ProviderRuntimeState,
+	ProviderRuntimeTarget,
 	ProviderStateDurationString,
 	ProviderStateNamespace,
+	ProviderStealthConfig,
 	ProviderSupportLevel,
+	ProxiedOAuthConfig,
+	RedirectRunReason,
 	SchemaLike,
 	SmsOtpMatcherDefinition,
 	StandardSchemaV1,
 	StateCasResult,
 	StateNamespaceOptions,
+	StateNamespaceScope,
 	StateValue,
 	StateWriteOptions,
+	StealthChallengeClassification,
 } from "./types.js";
 export {
 	HttpRetryAfterPolicy,

package/src/runtime/auth-flow.ts

@@ -5,10 +5,15 @@ import type {
 	EnvContext,
 	FlowContext,
 	HttpClient,
+	OcrContext,
+	ProviderRuntimeState,
 	StealthClient,
 	SttContext,
 } from "../types.js";
+import { createUnsupportedOcrClient } from "./ocr.js";
+import { createUnsupportedResolverClient } from "./resolver-shared.js";
 import { createUnsupportedSttClient } from "./stt.js";
+import { createTraceContext } from "./trace.js";
 
 function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
 	return new Set(allowedKeys.filter((key) => key.trim().length > 0));
@@ -48,6 +53,7 @@ export function createScratchpad(
 }
 
 export function createFlowContext(options: {
+	flowId?: string;
 	http: HttpClient;
 	stealth: StealthClient;
 	env: EnvContext;
@@ -55,20 +61,29 @@ export function createFlowContext(options: {
 	providerId: string;
 	connectionId?: string;
 	externalRef?: string;
+	/** Host-agnostic: callers pass an already-scoped runtime state, which this helper forwards verbatim. */
+	state?: ProviderRuntimeState;
 	allowedKeys: string[];
 	initialContext?: Record<string, unknown>;
+	ocr?: OcrContext;
 	stt?: SttContext;
+	trace?: FlowContext["trace"];
 }): FlowContext {
 	return {
+		flowId: options.flowId,
 		connectionId: options.connectionId,
 		externalRef: options.externalRef,
 		tenantId: options.tenantId,
 		providerId: options.providerId,
+		trace: options.trace ?? createTraceContext(),
 		http: options.http,
+		state: options.state,
 		stealth: options.stealth,
 		env: options.env,
 		context: createScratchpad(options.allowedKeys, options.initialContext),
+		ocr: options.ocr ?? createUnsupportedOcrClient(),
 		stt: options.stt ?? createUnsupportedSttClient(),
+		resolver: createUnsupportedResolverClient("Resolver is not available in auth flow context"),
 		auth: createAuthFlowHelpers(),
 	};
 }

package/src/runtime/bounded-expiring-map.ts

@@ -0,0 +1,67 @@
+/**
+ * Map whose entries carry an expiry and whose size is capped.
+ *
+ * Expired entries are dropped when read and swept on every insert, so a
+ * process that keeps minting new keys does not retain dead values. When the
+ * cap is still exceeded after the sweep, the least recently used entry is
+ * evicted and counted in `capacityEvictions` so callers can tell the two
+ * kinds of removal apart. Callers pass `now` explicitly so a single timestamp
+ * is used across a lookup-then-store sequence.
+ */
+export class BoundedExpiringMap<K, V> {
+	readonly #entries = new Map<K, V>();
+	readonly #maxEntries: number;
+	readonly #expiresAt: (value: V) => number;
+	#capacityEvictions = 0;
+
+	constructor(maxEntries: number, expiresAt: (value: V) => number) {
+		if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+			throw new RangeError("maxEntries must be a positive integer");
+		}
+		this.#maxEntries = maxEntries;
+		this.#expiresAt = expiresAt;
+	}
+
+	get size(): number {
+		return this.#entries.size;
+	}
+
+	/** Entries removed to satisfy `maxEntries`; expiry removals are not counted. */
+	get capacityEvictions(): number {
+		return this.#capacityEvictions;
+	}
+
+	get(key: K, now: number): V | undefined {
+		if (!this.#entries.has(key)) return undefined;
+		const value = this.#entries.get(key) as V;
+		this.#entries.delete(key);
+		if (this.#expiresAt(value) <= now) return undefined;
+		// Re-insert so Map iteration order doubles as the LRU order.
+		this.#entries.set(key, value);
+		return value;
+	}
+
+	set(key: K, value: V, now: number): void {
+		for (const [existingKey, existing] of this.#entries) {
+			if (this.#expiresAt(existing) <= now) this.#entries.delete(existingKey);
+		}
+		this.#entries.delete(key);
+		if (this.#expiresAt(value) <= now) return;
+		this.#entries.set(key, value);
+		if (this.#entries.size > this.#maxEntries) {
+			const oldest = this.#entries.keys().next();
+			if (!oldest.done) {
+				this.#entries.delete(oldest.value);
+				this.#capacityEvictions += 1;
+			}
+		}
+	}
+
+	delete(key: K): boolean {
+		return this.#entries.delete(key);
+	}
+
+	clear(): void {
+		this.#entries.clear();
+	}
+}

package/src/runtime/browser-telemetry-binding.ts

@@ -0,0 +1,92 @@
+import type { BrowserClient } from "../types.js";
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
+import { observeTelemetryCallback } from "./http-telemetry-guard.js";
+
+const methods = new Set(["newPage", "rawPage", "withIsolatedContext", "solveChallenge"]);
+type State = { sink: BrowserTelemetrySink; adapter: BrowserClient };
+const adapters = new WeakMap<object, State>();
+let warned = false;
+
+export function isSupportedBrowserBinding(value: unknown): value is BrowserClient {
+	if ((typeof value !== "object" && typeof value !== "function") || value === null) return false;
+	return [...methods].some((method) => {
+		try {
+			return typeof Reflect.get(value, method) === "function";
+		} catch {
+			return false;
+		}
+	});
+}
+
+export function warnUnsupportedBrowserBinding(): void {
+	if (warned) return;
+	warned = true;
+	try {
+		console.warn("[apifuse] browser telemetry not attached; reason=unsupported_binding_shape");
+	} catch {}
+}
+
+export function bindBrowserTelemetry(
+	client: BrowserClient,
+	sink: BrowserTelemetrySink,
+): BrowserClient {
+	const existing = adapters.get(client as object);
+	if (existing) {
+		existing.sink = sink;
+		return existing.adapter;
+	}
+	const wrappers = new Map<
+		PropertyKey,
+		{ original: unknown; wrapped: (...args: unknown[]) => unknown }
+	>();
+	const adapter = new Proxy(Object.create(client) as BrowserClient, {
+		get(_target, property) {
+			const original = Reflect.get(client, property, client);
+			if (typeof property !== "string" || !methods.has(property) || typeof original !== "function")
+				return original;
+			const cached = wrappers.get(property);
+			if (cached && cached.original === original) return cached.wrapped;
+			const wrapped = function (this: unknown, ...args: unknown[]) {
+				const receiver = this === adapter ? client : this;
+				observeTelemetryCallback(state.sink, () => {
+					const declared = client.engine;
+					const engine =
+						declared === "playwright-stealth" ||
+						declared === "nodriver" ||
+						declared === "selenium-uc"
+							? declared
+							: "host";
+					return state.sink.recordEngine(engine);
+				});
+				if (property === "newPage" || property === "rawPage" || property === "withIsolatedContext")
+					observeTelemetryCallback(state.sink, () =>
+						state.sink.recordPoolAcquire("not_configured"),
+					);
+				let result: unknown;
+				try {
+					result = Reflect.apply(original, receiver, args);
+				} catch (error) {
+					observeTelemetryCallback(state.sink, () => state.sink.recordError("other"));
+					throw error;
+				}
+				try {
+					if (result instanceof Promise)
+						void Promise.prototype.then.call(result, undefined, () => {
+							observeTelemetryCallback(state.sink, () => state.sink.recordError("other"));
+						});
+				} catch (error) {
+					observeTelemetryCallback(state.sink, () => {
+						throw error;
+					});
+				}
+				return result;
+			};
+			wrappers.set(property, { original, wrapped });
+			return wrapped;
+		},
+	});
+	const state: State = { sink, adapter };
+	adapters.set(client as object, state);
+	adapters.set(adapter as object, state);
+	return adapter;
+}