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

package/src/types.ts

@@ -1,4 +1,5 @@
 import type ms from "ms";
+import type { HealthScenario } from "./health-scenario.js";
 import type { SerializedCookieJar } from "tough-cookie";
 
 import type { infer as ZodInfer, ZodType } from "zod";
@@ -308,16 +309,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 +412,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[];
 	/**
@@ -645,7 +646,7 @@ export interface HealthJourneyRunResult {
 	metadata?: Record<string, unknown>;
 }
 
-export interface HealthJourneyDefinition {
+interface HealthJourneyDefinitionBase {
 	id: string;
 	title?: string;
 	description?: string;
@@ -657,15 +658,17 @@ export interface HealthJourneyDefinition {
 	requiredSecrets?: readonly string[];
 	manualTrigger?: HealthJourneyManualTriggerPolicy;
 	steps: readonly [HealthJourneyStep, ...HealthJourneyStep[]];
-	/**
-	 * Required: a journey always declares `coversOperations`, and the health
-	 * monitor reports a run-less journey as `journey_run_missing`. Declaration
-	 * validation rejects a missing `run` (`health-journey-executable`), so this
-	 * is typed required to fail at compile time rather than at boot.
-	 */
-	run: (ctx: HealthJourneyRunContext) => Promise<HealthJourneyRunResult | undefined>;
 }
 
+export type HealthJourneyDefinition = HealthJourneyDefinitionBase &
+	(
+		| {
+				run: (ctx: HealthJourneyRunContext) => Promise<HealthJourneyRunResult | undefined>;
+			scenario?: never;
+		}
+		| { scenario: HealthScenario; run?: never }
+	);
+
 /**
  * Health-check authoring surface owned by `@apifuse/provider-sdk`.
  *
@@ -1636,9 +1639,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 +1816,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 +2143,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 +2279,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 +2293,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 +2371,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 +2403,7 @@ export interface OperationDefinition<
 	input: TInput;
 	output: TOutput;
 	handler(
-		ctx: ProviderContext,
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	):
 		| OperationHandlerResult<InferSchemaOutput<TOutput>>