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

package/src/index.ts

@@ -1,5 +1,6 @@
 // @apifuse/provider-sdk
 
+export * from "./auth";
 export * from "./ceremonies";
 export * from "./choice-token";
 export type {
@@ -20,6 +21,8 @@ export {
 	type ProviderContractSnapshot,
 } from "./contract";
 export {
+	centered,
+	delayed,
 	defineHealthJourney,
 	defineOperation,
 	defineProvider,
@@ -122,8 +125,15 @@ export type {
 	Bcp47Locale,
 	BrowserEngine,
 	BrowserOptions,
+	BrowserResourceBody,
+	BrowserResourceDecision,
+	BrowserResourceMethod,
+	BrowserResourcePolicy,
+	BrowserResourceRequest,
+	BrowserResourceRoute,
 	ConnectionMode,
 	ContextDeclaration,
+	CookieJar,
 	ContextScratchpad,
 	CredentialContext,
 	CredentialDeclaration,
@@ -144,6 +154,7 @@ export type {
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
 	HealthJourneySchedule,
+	HealthScheduleRandomization,
 	HealthJourneySmsContext,
 	HealthJourneyStep,
 	HttpClient,
@@ -191,6 +202,7 @@ export type {
 	ProviderContext,
 	ProviderDefinition,
 	ProviderHealthMonitorConfig,
+	ProviderHealthProbeConfig,
 	ProviderLocale,
 	ProviderLocaleKey,
 	ProviderLocaleKeyInput,
@@ -229,8 +241,12 @@ export type {
 	StealthFetchOptions,
 	StealthPlatform,
 	StealthProfile,
+	StealthRedirectHop,
+	StealthRedirectRunOptions,
+	StealthRedirectRunResult,
 	StealthResponse,
 	StealthSession,
+	StealthSessionCookies,
 	SttAudioInput,
 	SttContext,
 	SttPromptPolicy,

package/src/lint.ts

@@ -22,8 +22,12 @@ type ProviderAuthLike = {
 		abort?: unknown;
 		refresh?: unknown;
 	};
+	exchange?: unknown;
 };
 
+const AUTH_OPERATION_ID_PATTERN =
+	/^(?:auth[-_])?(?:login|exchange|continue|refresh|callback)(?:[-_]|$)/i;
+
 type ProviderContractMetaLike = {
 	publicSchemaFieldNames?: "normalized";
 };
@@ -127,6 +131,10 @@ function lintReviewed(
 	];
 }
 
+function isProviderAuthLike(value: unknown): value is ProviderAuthLike {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
 function hasReusableSecretKeys(keys: readonly string[] | undefined): boolean {
 	if (!keys) {
 		return false;
@@ -215,6 +223,15 @@ function lintAuthModel(provider: {
 		});
 	}
 
+	if (isProviderAuthLike(provider.auth) && "exchange" in provider.auth) {
+		diagnostics.push({
+			rule: "auth-exchange-unsupported",
+			level: "error",
+			field: "auth.exchange",
+			message: `${providerLabel} must not define auth.exchange. The Provider SDK has one auth interface: auth.flow. Gateway only calls auth.flow.start/continue/poll/abort/refresh and persists complete turn data.credential as-is; put login/token/session exchange inside auth.flow.continue.`,
+		});
+	}
+
 	if (authMode === "credentials" && credentialKeys.length === 0) {
 		diagnostics.push({
 			rule: "credential-keys-required-when-credentials-mode",
@@ -1006,6 +1023,22 @@ export function lintProvider(
 		...lintSelfHostedBrowserPatterns(provider, options),
 	];
 
+	if (provider.operations) {
+		const authMode = provider.auth?.mode;
+		if (authMode === "credentials" || authMode === "oauth2") {
+			for (const operationKey of Object.keys(provider.operations)) {
+				if (AUTH_OPERATION_ID_PATTERN.test(operationKey)) {
+					diagnostics.push({
+						rule: "auth-operation-unsupported",
+						level: "error",
+						field: `operations.${operationKey}`,
+						message: `Provider "${provider.id ?? "unknown"}" operation "${operationKey}" looks like a login/token/session exchange endpoint. Authenticated providers must expose login through the single auth.flow interface because Gateway persists only auth.flow complete turn data.credential as the connection credential. Move this logic into auth.flow.continue instead of a provider operation.`,
+					});
+				}
+			}
+		}
+	}
+
 	if (!provider.operations) {
 		return diagnostics;
 	}

package/src/provider.ts

@@ -1,3 +1,22 @@
+export {
+	AuthAbortError,
+	credentialsAuthChallenge,
+	createAuthFlowHelpers,
+	defineCredentialsAuth,
+} from "./auth";
+export type {
+	CredentialsAuthChallengeDefinition,
+	CredentialsAuthChallengeRequest,
+	CredentialsAuthCompleteResult,
+	CredentialsAuthCredential,
+	CredentialsAuthField,
+	CredentialsAuthFields,
+	CredentialsAuthFieldType,
+	CredentialsAuthInput,
+	CredentialsAuthLoginResult,
+	DefineCredentialsAuthOptions,
+	DefinedCredentialsAuth,
+} from "./auth";
 export { createFormCeremony } from "./ceremonies";
 export {
 	assertFreshProviderChoiceIssuedAt,
@@ -8,6 +27,8 @@ export {
 	parseProviderChoiceToken,
 } from "./choice-token";
 export {
+	centered,
+	delayed,
 	defineHealthJourney,
 	defineOperation,
 	defineProvider,
@@ -50,7 +71,12 @@ export {
 	z,
 } from "./schema";
 export type {
+	AuthAbortData,
+	AuthAbortRetry,
+	AuthFlowTerminalContext,
 	AuthMode,
+	AuthSafeData,
+	AuthSafeJson,
 	FlowContext,
 	HealthCheckAssertionContext,
 	HealthCheckCase,
@@ -61,6 +87,7 @@ export type {
 	HealthJourneyManualTriggerPolicy,
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
+	HealthScheduleRandomization,
 	HttpRetryOptions,
 	HttpRetrySummary,
 	InferSchemaOutput,

package/src/runtime/auth-flow.ts

@@ -1,4 +1,5 @@
 import { ContextAccessError } from "../errors";
+import { createAuthFlowHelpers } from "../auth";
 import type {
 	ContextScratchpad,
 	EnvContext,
@@ -70,5 +71,6 @@ export function createFlowContext(options: {
 		env: options.env,
 		context: createScratchpad(options.allowedKeys, options.initialContext),
 		stt: options.stt ?? createUnsupportedSttClient(),
+		auth: createAuthFlowHelpers(),
 	};
 }

package/src/runtime/browser.ts

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import type { Frame, LaunchOptions, Locator, Page } from "playwright";
+import type { Frame, LaunchOptions, Locator, Page, Request, Route } from "playwright";
 
 import { ProviderError } from "../errors";
 import type {
@@ -11,11 +11,18 @@ import type {
 	BrowserLocator,
 	BrowserOptions,
 	BrowserPage,
+	BrowserResourceBody,
+	BrowserResourceDecision,
+	BrowserResourceMethod,
+	BrowserResourcePolicy,
+	BrowserResourceRequest,
 } from "../types";
 
 const require = createRequire(import.meta.url);
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 const SELECTOR_POLL_INTERVAL_MS = 100;
+const RESOURCE_POLICY_ROUTE_PATTERN = "**/*";
+const DEFAULT_RESOURCE_METHODS = ["GET", "HEAD"] as const;
 
 type PlaywrightModule = typeof import("playwright");
 type PlaywrightExtraModule = {
@@ -62,8 +69,153 @@ type CdpFrameTreeNode = {
 	};
 };
 
+type CdpFetchFulfillParams = {
+	readonly requestId: string;
+	readonly responseCode: number;
+	readonly responseHeaders?: readonly {
+		readonly name: string;
+		readonly value: string;
+	}[];
+	readonly body?: string;
+};
+
 type BrowserPageContract = BrowserPage;
 
+function toResourceBody(
+	body: BrowserResourceBody | undefined,
+): Buffer | string | undefined {
+	if (body === undefined || typeof body === "string" || Buffer.isBuffer(body)) {
+		return body;
+	}
+
+	if (body instanceof ArrayBuffer) {
+		return Buffer.from(new Uint8Array(body));
+	}
+
+	return Buffer.from(body);
+}
+
+function isResourceMethod(method: string): method is BrowserResourceMethod {
+	return method === "GET" || method === "HEAD";
+}
+
+async function toResourceRequest(
+	request: Request,
+): Promise<BrowserResourceRequest | null> {
+	const method = request.method().toUpperCase();
+	if (!isResourceMethod(method)) {
+		return null;
+	}
+
+	return {
+		headers: await request.allHeaders(),
+		method,
+		resourceType: request.resourceType(),
+		url: request.url(),
+	};
+}
+
+function toCdpResourceRequest(
+	params: unknown,
+): { requestId: string; request: BrowserResourceRequest } | null {
+	if (!isRecord(params)) {
+		return null;
+	}
+
+	const requestId = params.requestId;
+	const rawRequest = params.request;
+	if (typeof requestId !== "string" || !isRecord(rawRequest)) {
+		return null;
+	}
+
+	const url = rawRequest.url;
+	const method = String(rawRequest.method ?? "").toUpperCase();
+	if (typeof url !== "string" || !isResourceMethod(method)) {
+		return null;
+	}
+
+	return {
+		requestId,
+		request: {
+			headers: toCdpResourceHeaders(rawRequest.headers),
+			method,
+			resourceType:
+				typeof params.resourceType === "string" ? params.resourceType : undefined,
+			url,
+		},
+	};
+}
+
+function getCdpPausedRequestId(params: unknown): string | null {
+	if (!isRecord(params) || typeof params.requestId !== "string") {
+		return null;
+	}
+
+	return params.requestId;
+}
+
+function toCdpResourceHeaders(value: unknown): Record<string, string> {
+	if (!isRecord(value)) {
+		return {};
+	}
+
+	const headers: Record<string, string> = {};
+	for (const [name, headerValue] of Object.entries(value)) {
+		if (typeof headerValue === "string") {
+			headers[name] = headerValue;
+		}
+	}
+
+	return headers;
+}
+
+function matchesResourceRoute(
+	match: BrowserResourcePolicy["routes"][number]["match"],
+	request: BrowserResourceRequest,
+): boolean {
+	if (typeof match === "string") {
+		return request.url === match;
+	}
+	if (match instanceof RegExp) {
+		return match.test(request.url);
+	}
+
+	return match(request);
+}
+
+function toCdpFulfillParams(
+	requestId: string,
+	decision: Extract<BrowserResourceDecision, { readonly action: "fulfill" }>,
+): CdpFetchFulfillParams {
+	const body = toResourceBody(decision.body);
+	return {
+		...(body === undefined
+			? {}
+			: { body: Buffer.from(body).toString("base64") }),
+		...(decision.headers === undefined
+			? {}
+			: {
+					responseHeaders: Object.entries(decision.headers).map(
+						([name, value]) => ({ name, value }),
+					),
+				}),
+		requestId,
+		responseCode: decision.status ?? 200,
+	};
+}
+
+async function fulfillResourceRoute(
+	route: Route,
+	decision: Extract<BrowserResourceDecision, { readonly action: "fulfill" }>,
+): Promise<void> {
+	const body = toResourceBody(decision.body);
+	await route.fulfill({
+		...(body === undefined ? {} : { body }),
+		...(decision.headers === undefined ? {} : { headers: decision.headers }),
+		status: decision.status ?? 200,
+	});
+}
+
 export type BrowserClientOptions = BrowserOptions & {
 	allowedHosts?: string[];
 	cdpUrl?: string;
@@ -398,6 +550,47 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 	async close(): Promise<void> {
 		await this.page.close();
 	}
+
+	async withResourcePolicy<T>(
+		policy: BrowserResourcePolicy,
+		run: () => Promise<T>,
+	): Promise<T> {
+		const allowedMethods = new Set(
+			policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS,
+		);
+		const handler = async (route: Route): Promise<void> => {
+			const request = await toResourceRequest(route.request());
+			if (!request || !allowedMethods.has(request.method)) {
+				await route.abort("blockedbyclient");
+				return;
+			}
+
+			for (const resourceRoute of policy.routes) {
+				if (!matchesResourceRoute(resourceRoute.match, request)) {
+					continue;
+				}
+
+				const decision = await resourceRoute.handle(request);
+				switch (decision.action) {
+					case "fulfill":
+						await fulfillResourceRoute(route, decision);
+						return;
+					case "block":
+						await route.abort("blockedbyclient");
+						return;
+				}
+			}
+
+			await route.abort("blockedbyclient");
+		};
+
+		await this.page.route(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+		try {
+			return await run();
+		} finally {
+			await this.page.unroute(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+		}
+	}
 }
 
 class PlaywrightBrowserClient implements SupportedBrowserClient {
@@ -1055,6 +1248,105 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		}
 	}
 
+	async withResourcePolicy<T>(
+		policy: BrowserResourcePolicy,
+		run: () => Promise<T>,
+	): Promise<T> {
+		const allowedMethods = new Set(
+			policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS,
+		);
+		const handlePausedRequest = (params: unknown): void => {
+			void this.handleResourcePolicyPausedRequest(
+				params,
+				policy,
+				allowedMethods,
+			);
+		};
+
+		const unsubscribe = this.pageClient.on(
+			"Fetch.requestPaused",
+			handlePausedRequest,
+		);
+
+		try {
+			await this.pageClient.send("Fetch.enable", {
+				patterns: [{ requestStage: "Request", urlPattern: "*" }],
+			});
+		} catch (error) {
+			unsubscribe();
+			throw new ProviderError(
+				"CDP browser target does not support BrowserPage.withResourcePolicy()",
+				{
+					cause: error instanceof Error ? error : undefined,
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+					fix: "Use a Chromium CDP target with the Fetch domain enabled, or use the local Playwright browser runtime.",
+				},
+			);
+		}
+
+		try {
+			return await run();
+		} finally {
+			unsubscribe();
+			await this.pageClient.send("Fetch.disable");
+		}
+	}
+
+	private async handleResourcePolicyPausedRequest(
+		params: unknown,
+		policy: BrowserResourcePolicy,
+		allowedMethods: ReadonlySet<BrowserResourceMethod>,
+	): Promise<void> {
+		const requestId = getCdpPausedRequestId(params);
+		if (requestId === null) {
+			return;
+		}
+
+		try {
+			const parsed = toCdpResourceRequest(params);
+			if (!parsed || !allowedMethods.has(parsed.request.method)) {
+				await this.failCdpResourceRequest(requestId);
+				return;
+			}
+
+			for (const resourceRoute of policy.routes) {
+				if (!matchesResourceRoute(resourceRoute.match, parsed.request)) {
+					continue;
+				}
+
+				const decision = await resourceRoute.handle(parsed.request);
+				switch (decision.action) {
+					case "fulfill":
+						await this.pageClient.send(
+							"Fetch.fulfillRequest",
+							toCdpFulfillParams(parsed.requestId, decision),
+						);
+						return;
+					case "block":
+						await this.failCdpResourceRequest(parsed.requestId);
+						return;
+				}
+			}
+
+			await this.failCdpResourceRequest(parsed.requestId);
+		} catch {
+			await this.failCdpResourceRequest(requestId);
+		}
+	}
+
+	private async failCdpResourceRequest(requestId: string): Promise<void> {
+		try {
+			await this.pageClient.send("Fetch.failRequest", {
+				errorReason: "BlockedByClient",
+				requestId,
+			});
+		} catch (error) {
+			if (error instanceof Error) {
+				return;
+			}
+		}
+	}
+
 	private async initialize(): Promise<void> {
 		if (this.initialized) {
 			return;

package/src/runtime/http.ts

@@ -58,8 +58,13 @@ type HttpStatusOutcome = {
 	status: number;
 	headers: Record<string, string>;
 	retryable: boolean;
+	proxyUsed: boolean;
 };
 
+type NativeHttpAttemptOutcome = HttpResponse | HttpStatusOutcome;
+
+type NativeHttpAttemptError = TransportError & { proxyUsed?: boolean };
+
 function isHttpStatusOutcome(
 	outcome: HttpResponse | HttpStatusOutcome,
 ): outcome is HttpStatusOutcome {
@@ -582,7 +587,8 @@ function toHttpTransportError(error: unknown): TransportError {
 
 async function toNativeHttpResponse(response: Response): Promise<HttpResponse> {
 	const headers = Object.fromEntries(response.headers.entries());
-	const rawText = await response.text();
+	const bodyBytes = new Uint8Array(await response.arrayBuffer());
+	const rawText = new TextDecoder().decode(bodyBytes);
 	const data = parseHttpData(rawText, headers);
 
 	return {
@@ -602,6 +608,12 @@ async function toNativeHttpResponse(response: Response): Promise<HttpResponse> {
 		ok: response.status >= 200 && response.status < 300,
 		status: response.status,
 		text: async () => rawText,
+		arrayBuffer: async () =>
+			bodyBytes.buffer.slice(
+				bodyBytes.byteOffset,
+				bodyBytes.byteOffset + bodyBytes.byteLength,
+			),
+		bytes: async () => bodyBytes.slice(0),
 	};
 }
 
@@ -678,12 +690,20 @@ async function resolveNativeProxy(
 	options: RequestOptions,
 	clientOptions: HttpClientOptions,
 	warn: (message: string) => void,
+	proxyAttemptOffset = 0,
 ): Promise<string | undefined> {
+	const baseProxyAttempt =
+		clientOptions.proxyAttempt === undefined ||
+		!Number.isFinite(clientOptions.proxyAttempt)
+			? 0
+			: Math.max(0, Math.floor(clientOptions.proxyAttempt));
 	const resolvedProxy = await resolveProxyConfigAsync({
 		proxy: options.proxy ?? clientOptions.proxy,
 		upstream: clientOptions.upstream,
 		apifuseConfig: clientOptions.apifuseConfig,
+		proxyPolicy: clientOptions.proxyPolicy,
 		affinityKey: clientOptions.affinityKey,
+		proxyAttempt: baseProxyAttempt + proxyAttemptOffset,
 		telemetry: clientOptions.telemetry,
 	});
 	if (resolvedProxy.shouldWarn) {
@@ -723,7 +743,8 @@ async function fetchNativeHttp(
 	clientOptions: HttpClientOptions,
 	warn: (message: string) => void,
 	statusRetryCodes?: readonly number[],
-): Promise<HttpResponse | HttpStatusOutcome> {
+	proxyAttemptOffset = 0,
+): Promise<NativeHttpAttemptOutcome> {
 	const requestUrl = appendQueryParams(
 		resolveHttpUrl(baseUrl, url),
 		options.params,
@@ -733,8 +754,14 @@ async function fetchNativeHttp(
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
 
+	let proxy: string | undefined;
 	try {
-		const proxy = await resolveNativeProxy(options, clientOptions, warn);
+		proxy = await resolveNativeProxy(
+			options,
+			clientOptions,
+			warn,
+			proxyAttemptOffset,
+		);
 		const requestInit: NativeFetchInit = {
 			headers: options.headers,
 			method,
@@ -756,6 +783,7 @@ async function fetchNativeHttp(
 				status: response.status,
 				headers,
 				retryable: statusRetryCodes.includes(response.status),
+				proxyUsed: Boolean(proxy),
 			};
 		}
 
@@ -775,7 +803,9 @@ async function fetchNativeHttp(
 		if (error instanceof SyntaxError) {
 			throw error;
 		}
-		throw toHttpTransportError(error);
+		const transportError = toHttpTransportError(error) as NativeHttpAttemptError;
+		transportError.proxyUsed = Boolean(proxy);
+		throw transportError;
 	} finally {
 		if (timeoutHandle) clearTimeout(timeoutHandle);
 	}
@@ -867,7 +897,12 @@ export function createHttpClient(
 			options.body,
 		);
 		const methodName = normalizeHttpMethod(method);
-		const retryOptions = normalizeRetryOptions(headersOptions.retry);
+		const explicitRetry = headersOptions.retry !== undefined;
+		const retryOptions =
+			normalizeRetryOptions(headersOptions.retry) ??
+			(explicitRetry
+				? undefined
+				: createRetryOptions(HttpRetryPreset.TransportTransient));
 		if (retryOptions) validateUnsafeRetryMethods(retryOptions);
 		const retryEnabled = Boolean(
 			retryOptions &&
@@ -876,6 +911,7 @@ export function createHttpClient(
 		);
 		const statusRetryEnabled = Boolean(
 			retryEnabled &&
+				explicitRetry &&
 				retryOptions &&
 				retryOptions.statusCodes.length > 0 &&
 				headersOptions.throwOnHttpError !== false,
@@ -885,7 +921,9 @@ export function createHttpClient(
 				? { ...headersOptions, throwOnHttpError: false }
 				: headersOptions;
 
-		const executeOnce = (): Promise<HttpResponse | HttpStatusOutcome> =>
+		const executeOnce = (
+			proxyAttemptOffset = 0,
+		): Promise<NativeHttpAttemptOutcome> =>
 			fetchNativeHttp(
 				baseUrl,
 				url,
@@ -894,6 +932,7 @@ export function createHttpClient(
 				clientOptions,
 				warnOnce,
 				statusRetryEnabled ? retryOptions?.statusCodes : undefined,
+				proxyAttemptOffset,
 			);
 
 		if (!retryEnabled || !retryOptions) {
@@ -908,7 +947,7 @@ export function createHttpClient(
 		let lastStatus: number | undefined;
 		for (let attempt = 1; attempt <= retryOptions.attempts; attempt += 1) {
 			try {
-				const outcome = await executeOnce();
+				const outcome = await executeOnce(attempt - 1);
 				if (isHttpStatusOutcome(outcome)) {
 					lastStatus = outcome.status;
 					if (outcome.retryable && attempt < retryOptions.attempts) {
@@ -943,8 +982,10 @@ export function createHttpClient(
 			} catch (error) {
 				lastErrorCode = retryErrorCode(error);
 				lastStatus = retryErrorStatus(error);
+				const proxyUsed = Boolean((error as NativeHttpAttemptError).proxyUsed);
 				if (
 					attempt < retryOptions.attempts &&
+					(explicitRetry || proxyUsed) &&
 					shouldRetryTransportError(error, retryOptions)
 				) {
 					await sleep(computeRetryDelayMs(retryOptions, attempt));