@apifuse/provider-sdk 2.2.0-beta.36 → 2.2.0-beta.37

package/src/runtime/resolver.ts

@@ -35,6 +35,7 @@ import {
 	type ResolverVendorTransport,
 	ResolverVendorUnavailableError,
 	type ResolverVendorUnavailableReason,
+	resolveProviderResolverVendors,
 	resolverVendorSupports,
 } from "./resolver-vendors/types.js";
 import {
@@ -64,6 +65,10 @@ export {
 	APIFUSE__RESOLVER__TIMEOUT_MS,
 	DEFAULT_RESOLVER_TIMEOUT_MS,
 } from "./resolver-config.js";
+export {
+	DEFAULT_RESOLVER_VENDOR_PREFERENCE,
+	resolveProviderResolverVendors,
+} from "./resolver-vendors/types.js";
 
 type EnvLike = Record<string, string | undefined>;
 
@@ -340,10 +345,12 @@ function assertKnownResolverVendor(vendor: string): asserts vendor is ProviderRe
 	throw new Error(`Unknown resolver vendor "${vendor}" in resolver configuration`);
 }
 
-function throwUnsupportedKind(kind: ProviderChallengeKind): never {
+function throwUnsupportedKind(kind: ProviderChallengeKind, usingDefaultVendors: boolean): never {
 	throw new ProviderError(`Resolver vendor chain does not support kind "${kind}"`, {
 		code: "RESOLVER_KIND_UNSUPPORTED_BY_CHAIN",
-		fix: `Add a resolver vendor that supports "${kind}" to the provider's resolver.vendors declaration.`,
+		fix: usingDefaultVendors
+			? `No SDK default resolver vendor supports "${kind}". Declare an explicit resolver.vendors override with a supporting vendor.`
+			: `Add a resolver vendor that supports "${kind}" to the provider's resolver.vendors declaration.`,
 	});
 }
 
@@ -814,6 +821,7 @@ function createResolverChainClient(options: {
 	readonly kinds: readonly ProviderChallengeKind[];
 	readonly entries: readonly ResolverChainEntry[];
 	readonly unavailableReason?: string;
+	readonly usingDefaultVendors?: boolean;
 	readonly cache?: ProviderCache;
 	readonly identity?: ResolverIdentity;
 	readonly proxyIntent?: ResolverRuntimeOptions["proxyIntent"];
@@ -839,7 +847,9 @@ function createResolverChainClient(options: {
 			}
 
 			const supportingEntries = options.entries.filter((entry) => entry.supports(challenge.kind));
-			if (supportingEntries.length === 0) throwUnsupportedKind(challenge.kind);
+			if (supportingEntries.length === 0) {
+				throwUnsupportedKind(challenge.kind, options.usingDefaultVendors ?? false);
+			}
 			signal.throwIfAborted();
 			const identityResolution = options.proxyIntent
 				? await resolveResolverIdentity(options.proxyIntent)
@@ -1033,7 +1043,8 @@ function createResolverClientFromEnvInternal(
 	}
 	assertClientProfileTransportContract(config.clientProfile, options.transport);
 
-	if (config.vendors.length === 0) {
+	const vendors = resolveProviderResolverVendors(config);
+	if (config.vendors !== undefined && config.vendors.length === 0) {
 		return createResolverChainClient({
 			kinds: config.kinds,
 			entries: [],
@@ -1047,7 +1058,7 @@ function createResolverClientFromEnvInternal(
 
 	return createResolverChainClient({
 		kinds: config.kinds,
-		entries: config.vendors.map((configuredVendor) => {
+		entries: vendors.map((configuredVendor) => {
 			assertKnownResolverVendor(configuredVendor);
 			const vendor = configuredVendor;
 			return {
@@ -1062,6 +1073,7 @@ function createResolverClientFromEnvInternal(
 					),
 			};
 		}),
+		usingDefaultVendors: config.vendors === undefined,
 		cache: options.cache,
 		proxyIntent: options.proxyIntent,
 		identityScope: options.identityScope,

package/src/server/serve-implementation.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
@@ -745,7 +746,7 @@ function createProviderContext(
 					...event,
 				}),
 		}),
-	});
+	} as ProviderContext);
 	wrappedContext = context;
 	return context;
 }
@@ -1441,6 +1442,41 @@ function extractRequestId(raw: unknown): string | undefined {
 	return typeof value === "string" ? value : undefined;
 }
 
+type ProviderErrorCauseFrame = {
+	errorClass: string;
+	code?: string;
+	messageLength: number;
+	messageFingerprint: string;
+};
+
+const MAX_PROVIDER_ERROR_CAUSE_FRAMES = 5;
+
+function providerErrorCauseChain(error: unknown): ProviderErrorCauseFrame[] | undefined {
+	if (!(error instanceof Error) && !isProviderError(error)) return undefined;
+
+	const seen = new Set<object>([error]);
+	const frames: ProviderErrorCauseFrame[] = [];
+	let cause = error.cause;
+
+	while (
+		frames.length < MAX_PROVIDER_ERROR_CAUSE_FRAMES &&
+		(cause instanceof Error || isProviderError(cause)) &&
+		!seen.has(cause)
+	) {
+		seen.add(cause);
+		const message = cause.message;
+		frames.push({
+			errorClass: cause.name,
+			...(isProviderError(cause) && typeof cause.code === "string" ? { code: cause.code } : {}),
+			messageLength: message.length,
+			messageFingerprint: createHash("sha256").update(message).digest("hex").slice(0, 12),
+		});
+		cause = cause.cause;
+	}
+
+	return frames.length > 0 ? frames : undefined;
+}
+
 function logProviderError(
 	logger: ProviderServerLogger | unknown,
 	provider: ProviderDefinition,
@@ -1461,6 +1497,7 @@ function logProviderError(
 				: "internal_error";
 	const errorClass = error instanceof Error ? error.name : typeof error;
 	const message = error instanceof Error ? error.message : String(error);
+	const causeChain = providerErrorCauseChain(error);
 	const details = errorObservabilityDetails(error, declaredErrorCode);
 	const isUnregisteredProviderErrorCode =
 		status === 500 &&
@@ -1482,6 +1519,7 @@ function logProviderError(
 		code,
 		errorClass,
 		message,
+		...(causeChain ? { causeChain } : {}),
 		...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
 		errorCategory: details.category,
 		taxonomyVersion: details.taxonomyVersion,

package/src/testing/run.ts

@@ -525,7 +525,7 @@ function createUpstreamContext(
 		...(provider.native
 			? {
 					native: {
-					network: {
+						network: {
 							connectTcp: async (options) => {
 								const request = snapshotNativeConnectInput(options);
 								requireNativeEgress().assertConnect(request, "disabled");
@@ -578,7 +578,7 @@ function createUpstreamContext(
 			credential,
 			state,
 		}),
-	};
+	} as ProviderContext;
 }
 
 function createNativeConnection(
@@ -709,7 +709,7 @@ export function createSnapshotContext(rawFixture: unknown): ProviderContext {
 			credential,
 			state,
 		}),
-	};
+	} satisfies Omit<ProviderContext, "native"> as unknown as ProviderContext;
 	snapshotCaptureStates.set(context, {
 		assertConsumed() {
 			if (streamCaptureGroup && nextCaptureItem !== streamCaptureGroup.items.length) {

package/src/types.ts

@@ -308,16 +308,16 @@ export interface ProviderSttConfig {
 }
 
 /**
- * `browser` is the in-house CDP pool (`apps/cdp-pool`, reached through
- * `createBrowserClient`) and is a first-class vendor rather than an escape hatch:
- * for fingerprint-family kinds, it was measured faster than a paid vendor
- * (4.5 s vs 17.5 s) at zero marginal cost.
+ * Union order is documentation only.
  *
- * `2captcha` is the vendor already carrying production traffic in
- * `apifuse-provider-tabelog`.
+ * The SDK owns the default hosted-vendor fallback policy and derives the chain
+ * from each provider's declared challenge kinds. Hosted solvers are preferred
+ * with `capsolver` ahead of `2captcha` in that policy.
  *
- * Union order is documentation only; the effective fallback order is whatever
- * `ProviderResolverConfig.vendors` declares.
+ * `browser` is the in-house CDP pool and remains opt-in; it is excluded from the
+ * default chain. `custom` is likewise reserved for provider-specific configuration.
+ *
+ * `ProviderResolverConfig.vendors` overrides the SDK policy when declared.
  */
 export type ProviderResolverVendor =
 	| "browser"
@@ -411,8 +411,8 @@ export type ChallengeSolution =
 		};
 
 export interface ProviderResolverConfig {
-	/** Ordered vendor fallback chain, tried first to last. */
-	readonly vendors: readonly ProviderResolverVendor[];
+	/** Optional ordered override for the SDK-owned vendor fallback chain. */
+	readonly vendors?: readonly ProviderResolverVendor[];
 	/** Challenge kinds this provider is permitted to request. */
 	readonly kinds: readonly ProviderChallengeKind[];
 	/**
@@ -1636,9 +1636,6 @@ 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[];
@@ -1816,6 +1813,10 @@ export interface BrowserPage extends BrowserFrame {
 	cookies(): Promise<readonly BrowserCookie[]>;
 	fill(selector: string, text: string): Promise<void>;
 	goto(url: string): Promise<void>;
+	goto(
+		url: string,
+		options?: { readonly timeout?: number; readonly waitUntil?: "load" | "domcontentloaded" },
+	): Promise<void>;
 	pageId?: string;
 	screenshot(options?: { fullPage?: boolean }): Promise<Buffer>;
 	click(selector: string): Promise<void>;
@@ -2139,7 +2140,7 @@ export interface FlowContext {
 	 * un-keyed entries would be shared across all connectionless ceremonies. */
 	readonly state?: ProviderRuntimeState;
 	/** Present when the selected runtime supplies native network capabilities. */
-	readonly native?: NativeProviderContext;
+	readonly native?: NativeContext;
 	stealth: StealthClient;
 	env: EnvContext;
 	credential?: CredentialContext;
@@ -2275,8 +2276,8 @@ export interface ProviderContext {
 	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;
+	/** Native network capability selected by declaration-derived contexts. */
+	readonly native: NativeContext;
 	cache: ProviderCache;
 	state: ProviderRuntimeState;
 	stealth: StealthClient;
@@ -2289,6 +2290,28 @@ export interface ProviderContext {
 	choice: ProviderChoiceContext;
 }
 
+/**
+ * The operation context exposed for one provider declaration. Capability
+ * bindings are present only when their corresponding declaration is present;
+ * trace and request remain ambient runtime bindings.
+ */
+export type ProviderContextFor<TConfig> =
+	Pick<ProviderContext, "trace" | "request">
+	& ("env" extends keyof TConfig ? Pick<ProviderContext, "env"> : Record<never, never>)
+	& ("credential" extends keyof TConfig ? Pick<ProviderContext, "credential"> : Record<never, never>)
+	& ("http" extends keyof TConfig ? Pick<ProviderContext, "http"> : Record<never, never>)
+	& ("files" extends keyof TConfig ? Pick<ProviderContext, "files"> : Record<never, never>)
+	& ("native" extends keyof TConfig ? Pick<ProviderContext, "native"> : Record<never, never>)
+	& ("cache" extends keyof TConfig ? Pick<ProviderContext, "cache"> : Record<never, never>)
+	& ("state" extends keyof TConfig ? Pick<ProviderContext, "state"> : Record<never, never>)
+	& ("stealth" extends keyof TConfig ? Pick<ProviderContext, "stealth"> : Record<never, never>)
+	& ("browser" extends keyof TConfig ? Pick<ProviderContext, "browser"> : Record<never, never>)
+	& ("auth" extends keyof TConfig ? Pick<ProviderContext, "auth"> : Record<never, never>)
+	& ("ocr" extends keyof TConfig ? Pick<ProviderContext, "ocr"> : Record<never, never>)
+	& ("stt" extends keyof TConfig ? Pick<ProviderContext, "stt"> : Record<never, never>)
+	& ("resolver" extends keyof TConfig ? Pick<ProviderContext, "resolver"> : Record<never, never>)
+	& ("choice" extends keyof TConfig ? Pick<ProviderContext, "choice"> : Record<never, never>);
+
 export interface ProxiedOAuthConfig {
 	authorizeUrl: string;
 	tokenUrl: string;
@@ -2345,6 +2368,7 @@ export interface OperationContractMetadata {
 export interface OperationDefinition<
 	TInput extends SchemaLike = SchemaLike,
 	TOutput extends SchemaLike = SchemaLike,
+	TContext = ProviderContext,
 > {
 	/**
 	 * Short English display title for the operation. The SDK passes it through
@@ -2376,7 +2400,7 @@ export interface OperationDefinition<
 	input: TInput;
 	output: TOutput;
 	handler(
-		ctx: ProviderContext,
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	):
 		| OperationHandlerResult<InferSchemaOutput<TOutput>>