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

package/src/server/serve.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 
 import { Hono } from "hono";
 import { z } from "zod";
+import { AuthAbortError, createAuthFlowHelpers } from "../auth";
 import {
 	AuthError,
 	ProviderError,
@@ -75,6 +76,12 @@ import type {
 	StealthClient,
 	SttContext,
 } from "../types";
+import {
+	createSelfTestApp,
+	createSelfTestInvoke,
+	resolveSelfTestPort,
+} from "./self-test";
+import { resolveSelfTestMasterSecrets } from "./self-test-token";
 import {
 	type AuthFlowRequest,
 	AuthFlowRequestSchema,
@@ -329,6 +336,7 @@ function createAuthFlowContext(
 	provider: ProviderDefinition,
 	request: AuthFlowRequest,
 	options: ProviderServerOptions = {},
+	signal?: AbortSignal,
 ): {
 	context: FlowContext;
 	getPatch: () => Record<string, unknown | null> | undefined;
@@ -383,6 +391,7 @@ function createAuthFlowContext(
 			credential,
 			context: flowContextStore.context,
 			stt: options.stt ?? createSttClientFromEnv(provider.stt),
+			auth: createAuthFlowHelpers({ signal }),
 		},
 		getPatch: flowContextStore.getPatch,
 	};
@@ -1291,6 +1300,7 @@ async function handleAuthFlow(
 	request: AuthFlowRequest,
 	route: AuthRoute,
 	options: ProviderServerOptions = {},
+	signal?: AbortSignal,
 ): Promise<Response | AuthFlowResponse> {
 	const flow = provider.auth?.flow;
 	if (!flow) {
@@ -1303,6 +1313,7 @@ async function handleAuthFlow(
 		provider,
 		request,
 		options,
+		signal,
 	);
 	try {
 		const result =
@@ -1336,6 +1347,11 @@ async function handleAuthFlow(
 				? materializeAuthFlowTurn(provider, request, result)
 				: result;
 		return toAuthFlowResponse(materializedResult, getPatch());
+	} catch (error) {
+		if (error instanceof AuthAbortError) {
+			return toAuthFlowResponse(error.turn, getPatch());
+		}
+		throw error;
 	} finally {
 		context.stealth.close?.();
 	}
@@ -1450,7 +1466,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "start", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"start",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1495,6 +1517,7 @@ export function createServerApp(
 				body,
 				"continue",
 				options,
+				c.req.raw.signal,
 			);
 			logProviderSuccess(
 				logger,
@@ -1535,7 +1558,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "poll", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"poll",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1575,7 +1604,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "refresh", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"refresh",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1615,7 +1650,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "abort", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"abort",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1675,6 +1716,12 @@ function getBunServeRuntime(): BunServeRuntime | undefined {
 export interface ServeOptions extends ProviderServerOptions {
 	host?: string;
 	port?: number;
+	/**
+	 * Port for the internal self-test listener (default 3001 or
+	 * APIFUSE__PROVIDER_RUNTIME__SELF_TEST_PORT). The listener only starts
+	 * when APIFUSE__PROVIDER_RUNTIME__SELF_TEST_MASTER_SECRET is present.
+	 */
+	selfTestPort?: number;
 }
 
 export async function serve(
@@ -1702,5 +1749,21 @@ export async function serve(
 		hostname: options.host ?? DEFAULT_HOST,
 		fetch: app.fetch,
 	});
+
+	// Internal self-test listener (health dependency inversion): a SEPARATE
+	// socket the tenant-facing gateway never dials. Off by default — it only
+	// starts when the shared self-test master secret env is present.
+	const selfTestSecrets = resolveSelfTestMasterSecrets();
+	if (selfTestSecrets) {
+		const selfTestApp = createSelfTestApp(provider, {
+			secrets: selfTestSecrets,
+			invoke: createSelfTestInvoke(app),
+		});
+		bunRuntime.serve({
+			port: options.selfTestPort ?? resolveSelfTestPort(),
+			hostname: options.host ?? DEFAULT_HOST,
+			fetch: selfTestApp.fetch,
+		});
+	}
 	await Promise.resolve();
 }

package/src/testing/run.ts

@@ -128,13 +128,21 @@ function inferFixtureDir(providerId: string): string {
 }
 
 function jsonResponse(data: unknown): HttpResponse {
+	const body = JSON.stringify(data);
+	const bodyBytes = new TextEncoder().encode(body);
 	return {
 		status: 200,
 		ok: true,
 		headers: {},
 		data,
 		json: async <_T = unknown>() => JSON.parse(JSON.stringify(data)),
-		text: async () => JSON.stringify(data),
+		text: async () => body,
+		arrayBuffer: async () =>
+			bodyBytes.buffer.slice(
+				bodyBytes.byteOffset,
+				bodyBytes.byteOffset + bodyBytes.byteLength,
+			),
+		bytes: async () => bodyBytes.slice(0),
 	};
 }
 

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;
@@ -979,6 +1001,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 +1028,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;
@@ -1015,6 +1049,8 @@ export interface DeclarativeStealthResponse {
 	tlsInfo?: { protocol?: string; cipher?: string; [key: string]: unknown };
 	cookies: CookieJar;
 	json<T>(): Promise<T>;
+	arrayBuffer(): Promise<ArrayBuffer>;
+	bytes(): Promise<Uint8Array>;
 }
 
 export type StealthResponse = DeclarativeStealthResponse;
@@ -1024,8 +1060,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;
 }
 
@@ -1048,6 +1110,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 {
@@ -1204,6 +1268,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>;
@@ -1217,6 +1320,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 = {
@@ -1395,6 +1502,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;
@@ -1406,6 +1591,7 @@ export interface FlowContext {
 	credential?: CredentialContext;
 	context: ContextScratchpad;
 	stt: SttContext;
+	auth: AuthFlowTerminalContext;
 }
 
 export interface AuthTurn {
@@ -1634,5 +1820,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[];
 }