@apifuse/provider-sdk 2.1.0-beta.4 → 2.1.0-beta.6

package/src/server/types.ts

@@ -82,8 +82,10 @@ export const AuthFlowRequestSchema = z.object({
 	externalRef: z.string().optional(),
 	tenantId: z.string().optional(),
 	providerId: z.string().optional(),
+	headers: z.record(z.string(), z.string()).optional(),
 	input: z.record(z.string(), z.unknown()).optional(),
 	context: z.record(z.string(), z.unknown()).optional(),
+	connection: OperationConnectionSchema.optional(),
 });
 
 export const AuthFlowSuccessResponseSchema = z.object({

package/src/testing/run.ts

@@ -1,7 +1,8 @@
 import { describe, expect, it } from "bun:test";
 
 import { createProviderCache } from "../runtime/cache";
-import { createUnsupportedProviderRuntimeState } from "../runtime/state";
+import { createTestProviderChoiceContext } from "../runtime/choice";
+import { createMemoryProviderRuntimeState } from "../runtime/state";
 import { createUnsupportedSttClient } from "../runtime/stt";
 import { safeParseSchemaSync } from "../schema";
 import type {
@@ -149,11 +150,13 @@ function createSnapshotContext(rawFixture: unknown): ProviderContext {
 		getAccessToken: () => undefined,
 		getScopes: () => [],
 	};
+	const request = { headers: {} };
+	const state = createMemoryProviderRuntimeState();
 
 	return {
 		env: { get: () => undefined },
 		credential,
-		request: { headers: {} },
+		request,
 		http: {
 			request: async () => jsonResponse(rawFixture),
 			get: async () => jsonResponse(rawFixture),
@@ -164,7 +167,7 @@ function createSnapshotContext(rawFixture: unknown): ProviderContext {
 			sse: async () => unsupported("ctx.http.sse"),
 		},
 		cache: createProviderCache({ providerId: "standard-test" }),
-		state: createUnsupportedProviderRuntimeState(),
+		state,
 		stealth: {
 			fetch: async () => unsupported("ctx.stealth.fetch"),
 			createSession: () => unsupported("ctx.stealth.createSession"),
@@ -172,6 +175,10 @@ function createSnapshotContext(rawFixture: unknown): ProviderContext {
 		browser: {
 			engine: "playwright-stealth",
 			newPage: async () => unsupported("ctx.browser.newPage"),
+			rawPage: async () => unsupported("ctx.browser.rawPage"),
+			withIsolatedContext: async () =>
+				unsupported("ctx.browser.withIsolatedContext"),
+			solveChallenge: async () => unsupported("ctx.browser.solveChallenge"),
 		},
 		trace: {
 			span: async (_name, fn) => fn(),
@@ -183,6 +190,12 @@ function createSnapshotContext(rawFixture: unknown): ProviderContext {
 		stt: createUnsupportedSttClient(
 			"Standard test snapshot context does not support ctx.stt.transcribe",
 		),
+		choice: createTestProviderChoiceContext({
+			providerId: "standard-test",
+			request,
+			credential,
+			state,
+		}),
 	};
 }
 

package/src/types.ts

@@ -524,6 +524,26 @@ export interface HealthCheckAssertionContext<TOutput = unknown> {
 	readonly meta?: Record<string, unknown>;
 }
 
+export interface HealthCheckInputPreparationContext<TInput = unknown> {
+	readonly providerId: string;
+	readonly operationId: string;
+	readonly input: TInput;
+	readonly connectionId?: string;
+	readonly gateway: {
+		execute: (
+			providerId: string,
+			operationId: string,
+			input: unknown,
+			options?: { connectionId?: string },
+		) => Promise<{
+			status: number;
+			duration: number;
+			data: unknown;
+			meta?: Record<string, unknown>;
+		}>;
+	};
+}
+
 /**
  * Optional return value from an assertions lambda. Allows the case to
  * downgrade to "degraded" without throwing, and to attach a human-friendly
@@ -550,6 +570,14 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
 	description?: string;
 	/** Input passed to the operation handler for this case. */
 	input: TInput;
+	/**
+	 * Optional runtime input preparation hook for volatile probes. Use this when
+	 * the durable probe input must be derived from a live read-only operation
+	 * immediately before the checked operation executes.
+	 */
+	prepareInput?: (
+		ctx: HealthCheckInputPreparationContext<TInput>,
+	) => TInput | Promise<TInput>;
 	/**
 	 * Assertion executed against the operation's response and timing.
 	 *
@@ -694,6 +722,7 @@ export interface BrowserOptions {
 	stealth?: boolean;
 	proxy?: string;
 	engine?: BrowserEngine;
+	requireCdpPool?: boolean;
 }
 
 export interface StealthProfile {
@@ -798,15 +827,15 @@ export interface ProviderPublicProfile {
 	longDescriptionKey?: ProviderLocaleKeyInput;
 	logo?: ProviderLogoProfile;
 	category?: string;
-	tags?: string[];
-	capabilityKeys?: ProviderLocaleKeyInput[];
-	examplePromptKeys?: ProviderLocaleKeyInput[];
+	tags?: readonly string[];
+	capabilityKeys?: readonly ProviderLocaleKeyInput[];
+	examplePromptKeys?: readonly ProviderLocaleKeyInput[];
 	setupSummaryKey?: ProviderLocaleKeyInput;
 	connectionMode?: ProviderPublicConnectionMode;
-	requirementKeys?: ProviderLocaleKeyInput[];
-	limitationKeys?: ProviderLocaleKeyInput[];
+	requirementKeys?: readonly ProviderLocaleKeyInput[];
+	limitationKeys?: readonly ProviderLocaleKeyInput[];
 	availability?: {
-		regions?: string[];
+		regions?: readonly string[];
 		supportLevel?: ProviderSupportLevel;
 	};
 	/**
@@ -823,13 +852,13 @@ export interface ProviderMeta {
 	displayNameKey?: ProviderLocaleKeyInput;
 	descriptionKey: ProviderLocaleKeyInput;
 	category: string;
-	tags?: string[];
+	tags?: readonly string[];
 	icon?: string;
 	docTitleKey?: ProviderLocaleKeyInput;
 	docDescriptionKey?: ProviderLocaleKeyInput;
 	docSummaryKey?: ProviderLocaleKeyInput;
 	docMarkdownKey?: ProviderLocaleKeyInput;
-	normalizationNotesKeys?: ProviderLocaleKeyInput[];
+	normalizationNotesKeys?: readonly ProviderLocaleKeyInput[];
 	environment?: "staging";
 	purpose?: string;
 	purposeKey?: ProviderLocaleKeyInput;
@@ -950,6 +979,13 @@ export type HttpMethod =
 export interface StealthFetchOptions extends RequestOptions {
 	method?: HttpMethod;
 	body?: string | Buffer;
+	/**
+	 * Offsets policy-managed proxy pool selection for caller-managed retries.
+	 * Use when a request receives an upstream challenge page rather than a
+	 * transport error, so the next logical retry does not restart at the same
+	 * operation-affinity proxy.
+	 */
+	proxyAttemptOffset?: number;
 	/** Override the configured browser-like stealth profile for this request. */
 	profile?: string;
 	/**
@@ -1139,9 +1175,62 @@ export interface StealthClient {
 
 export interface BrowserClient {
 	readonly engine: BrowserEngine;
-	newPage(): Promise<unknown>;
+	close?(): Promise<void>;
+	newPage(): Promise<BrowserPage>;
+	rawPage(): Promise<BrowserPage>;
+	withIsolatedContext<T>(
+		handler: (page: BrowserPage) => Promise<T>,
+	): Promise<T>;
+	solveChallenge(
+		request: BrowserChallengeRequest,
+	): Promise<BrowserChallengeResult>;
+}
+
+export interface BrowserLocator {
+	click(): Promise<void>;
+	fill(text: string): Promise<void>;
+	textContent(): Promise<string | null>;
+	waitFor(options?: { timeout?: number }): Promise<void>;
 }
 
+export interface BrowserFrame {
+	id: string;
+	name?: string;
+	parentId?: string;
+	url(): Promise<string>;
+	title(): Promise<string>;
+	content(): Promise<string>;
+	evaluate<T>(fn: string | (() => T)): Promise<T>;
+	locator(selector: string): BrowserLocator;
+}
+
+export interface BrowserPage extends BrowserFrame {
+	close(): Promise<void>;
+	fill(selector: string, text: string): Promise<void>;
+	goto(url: string): Promise<void>;
+	pageId?: string;
+	screenshot(options?: { fullPage?: boolean }): Promise<Buffer>;
+	click(selector: string): Promise<void>;
+	type(selector: string, text: string): Promise<void>;
+	waitForSelector(
+		selector: string,
+		options?: { timeout?: number },
+	): Promise<void>;
+	frames(): Promise<BrowserFrame[]>;
+}
+
+export type BrowserChallengeRequest = {
+	type: "recaptcha";
+	siteKey?: string;
+	timeout?: number;
+};
+
+export type BrowserChallengeResult = {
+	type: BrowserChallengeRequest["type"];
+	solved: boolean;
+	frameUrl?: string;
+};
+
 export type TraceAttributeValue = string | number | boolean;
 
 export interface TraceSpan {
@@ -1197,6 +1286,107 @@ export interface ProviderRequestContext {
 	headers: Record<string, string>;
 }
 
+export interface ProviderChoiceBindingOptions {
+	connection?: boolean;
+	credentialKeys?: readonly string[];
+}
+
+export type ProviderChoiceStorageOptions =
+	| {
+			readonly mode: "inline";
+	  }
+	| {
+			readonly mode: "server";
+			readonly namespace: string;
+			readonly state?: ProviderRuntimeState;
+			readonly ttl?: ProviderStateDurationString;
+			readonly maxEntries: number;
+			readonly maxValueBytes: number;
+			readonly unavailable?: "reject";
+	  }
+	| {
+			readonly mode: "auto";
+			readonly namespace: string;
+			readonly state?: ProviderRuntimeState;
+			readonly ttl?: ProviderStateDurationString;
+			readonly maxInlineBytes: number;
+			readonly maxEntries: number;
+			readonly maxValueBytes: number;
+			readonly unavailable?: "reject";
+	  };
+
+export interface ProviderChoiceIssueOptions<
+	TPayload extends Record<string, unknown>,
+> {
+	prefix: string;
+	purpose: string;
+	payload: TPayload;
+	ttlMs: number;
+	nowMs?: number;
+	bind?: ProviderChoiceBindingOptions;
+	storage?: ProviderChoiceStorageOptions;
+}
+
+export interface ProviderChoiceParseOptions {
+	token: string;
+	prefix: string;
+	purpose: string;
+	ttlMs?: number;
+	nowMs?: number;
+	futureToleranceMs?: number;
+	bind?: ProviderChoiceBindingOptions;
+	storage?: ProviderChoiceStorageOptions;
+}
+
+export interface ProviderChoiceContext {
+	issue<TPayload extends Record<string, unknown>>(
+		options: ProviderChoiceIssueOptions<TPayload> & {
+			readonly storage?: { readonly mode: "inline" };
+		},
+	): string;
+	issue<TPayload extends Record<string, unknown>>(
+		options: ProviderChoiceIssueOptions<TPayload> & {
+			readonly storage: Extract<
+				ProviderChoiceStorageOptions,
+				{ readonly mode: "server" }
+			>;
+		},
+	): Promise<string>;
+	issue<TPayload extends Record<string, unknown>>(
+		options: ProviderChoiceIssueOptions<TPayload> & {
+			readonly storage: Extract<
+				ProviderChoiceStorageOptions,
+				{ readonly mode: "auto" }
+			>;
+		},
+	): string | Promise<string>;
+	issue<TPayload extends Record<string, unknown>>(
+		options: ProviderChoiceIssueOptions<TPayload>,
+	): string | Promise<string>;
+	parse(
+		options: ProviderChoiceParseOptions & {
+			readonly storage?: { readonly mode: "inline" };
+		},
+	): Record<string, unknown>;
+	parse(
+		options: ProviderChoiceParseOptions & {
+			readonly storage: Extract<
+				ProviderChoiceStorageOptions,
+				{ readonly mode: "server" }
+			>;
+		},
+	): Promise<Record<string, unknown>>;
+	parse(
+		options: ProviderChoiceParseOptions & {
+			readonly storage: Extract<
+				ProviderChoiceStorageOptions,
+				{ readonly mode: "auto" }
+			>;
+		},
+	): Record<string, unknown> | Promise<Record<string, unknown>>;
+	parse(options: ProviderChoiceParseOptions): Record<string, unknown>;
+}
+
 export interface ContextScratchpad {
 	get(key: string): unknown;
 	set(key: string, value: unknown): void;
@@ -1213,6 +1403,7 @@ export interface FlowContext {
 	http: HttpClient;
 	stealth: StealthClient;
 	env: EnvContext;
+	credential?: CredentialContext;
 	context: ContextScratchpad;
 	stt: SttContext;
 }
@@ -1223,23 +1414,33 @@ export interface AuthTurn {
 	expiresAt?: string;
 	data?: Record<string, unknown>;
 	expectedInput?: Record<string, unknown>;
+	/**
+	 * @deprecated Compatibility-only materialized provider auth hint.
+	 * Provider source must emit hintKey; SDK/server boundaries may materialize
+	 * this field from provider locale catalogs for legacy clients.
+	 */
 	hint?: string;
+	/** Provider locale catalog key for the auth turn hint. */
+	hintKey?: ProviderLocaleKeyInput;
 	timing?: {
 		suggestedPollIntervalMs?: number;
 		maxWaitMs?: number;
 	};
 }
 
-export type AuthFlowHandler = (
+export type AuthFlowStartHandler = (ctx: FlowContext) => Promise<AuthTurn>;
+
+export type AuthFlowInputHandler = (
 	ctx: FlowContext,
 	input?: Record<string, unknown>,
 ) => Promise<AuthTurn>;
 
 export interface AuthFlowDefinition {
-	start: AuthFlowHandler;
-	continue: AuthFlowHandler;
-	poll?: AuthFlowHandler;
-	abort?: AuthFlowHandler;
+	start: AuthFlowStartHandler;
+	continue: AuthFlowInputHandler;
+	poll?: AuthFlowStartHandler;
+	abort?: AuthFlowStartHandler;
+	refresh?: AuthFlowInputHandler;
 }
 
 export type ProviderStateDurationString =
@@ -1325,6 +1526,7 @@ export interface ProviderContext {
 	trace: TraceContext;
 	auth: AuthContext;
 	stt: SttContext;
+	choice: ProviderChoiceContext;
 }
 
 export interface AuthConfig {
@@ -1373,17 +1575,18 @@ export interface OperationDefinition<
 > {
 	descriptionKey?: ProviderLocaleKeyInput;
 	docs?: OperationDocMeta;
-	whenToUseKeys?: ProviderLocaleKeyInput[];
-	whenNotToUseKeys?: ProviderLocaleKeyInput[];
+	whenToUseKeys?: readonly ProviderLocaleKeyInput[];
+	whenNotToUseKeys?: readonly ProviderLocaleKeyInput[];
 	derivations?: Record<string, string>;
-	inputExamples?: OperationInputExample[];
+	inputExamples?: readonly OperationInputExample[];
 	annotations?: OperationAnnotations;
 	contract?: OperationContractMetadata;
-	tags?: string[];
+	tags?: readonly string[];
 	relatedOperations?: OperationRelationships;
 	toolRouter?: OperationToolRouterMetadata;
 	observability?: OperationObservabilityConfig;
 	transport?: OperationTransport;
+	retryOnAuthRefresh?: boolean;
 	input: TInput;
 	output: TOutput;
 	handler(
@@ -1396,6 +1599,10 @@ export interface OperationDefinition<
 		request: InferSchemaOutput<TInput>;
 		response: InferSchemaOutput<TOutput>;
 	};
+	upstream?: {
+		baseUrl?: string;
+		proxy?: boolean | ProviderProxyPolicy;
+	};
 	hints?: Record<string, string>;
 	healthCheck?: HealthCheckSuite<
 		InferSchemaOutput<TInput>,