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

package/dist/runtime/resolver-vendors/browser.js

@@ -5,6 +5,7 @@ import { assertResolverHostAllowed, normalizedResolverHostname } from "./hosts.j
 import { ResolverVendorUnavailableError, } from "./types.js";
 const BROWSER_VENDOR_ID = "browser";
 const DEFAULT_COOKIE_POLL_INTERVAL_MS = 100;
+const NAVIGATION_BLOCKED_ERROR_TEXT = "net::ERR_BLOCKED_BY_CLIENT";
 const AWS_WAF_CHALLENGE_INFRASTRUCTURE_HOST_SUFFIX = ".awswaf.com";
 const RESOLVER_DOCUMENT_CONTENT_SECURITY_POLICY = "connect-src http: https:; worker-src 'none'";
 const SUCCESS_COOKIE_NAMES = {
@@ -25,11 +26,32 @@ export function swapBrowserResolverClientFactoryForTests(factory) {
     };
 }
 class BrowserSolveTimeoutError extends Error {
-    constructor() {
-        super("Browser resolver solve budget elapsed");
+    constructor(blockedRequests) {
+        super(`Browser resolver solve budget elapsed${formatBlockedRequests(blockedRequests)}`);
         this.name = "BrowserSolveTimeoutError";
     }
 }
+class BrowserNavigationBlockedError extends Error {
+    navigationUrl;
+    blockedUrls;
+    code = "RESOLVER_BROWSER_NAVIGATION_BLOCKED";
+    constructor(navigationUrl, blockedUrls, options) {
+        super(`Browser resolver navigation was blocked for ${navigationUrl}${formatBlockedRequests(blockedUrls)}`, options);
+        this.navigationUrl = navigationUrl;
+        this.blockedUrls = blockedUrls;
+        this.name = "BrowserNavigationBlockedError";
+    }
+}
+function formatBlockedRequests(blockedRequests) {
+    if (blockedRequests.length === 0)
+        return "";
+    const displayed = blockedRequests.slice(0, 5);
+    const remainder = blockedRequests.length - displayed.length;
+    return `; blocked ${blockedRequests.length} requests: [${displayed.join(", ")}]${remainder > 0 ? ` (+${remainder} more)` : ""}`;
+}
+function isNavigationBlockedError(error) {
+    return error instanceof Error && error.message.includes(NAVIGATION_BLOCKED_ERROR_TEXT);
+}
 class BrowserCleanupTimeoutError extends Error {
     constructor(timeoutMs) {
         super(`Browser resolver cleanup exceeded ${timeoutMs}ms`);
@@ -141,23 +163,35 @@ function selectSuccessCookie(cookies, successCookieName, pageUrl) {
         cookieDomainSpecificity(right) - cookieDomainSpecificity(left) ||
         right.path.length - left.path.length)[0];
 }
-async function solveInPage(page, challengeKind, pageUrl, allowedHosts, successCookieName, pollIntervalMs, signal) {
+async function solveInPage(page, challengeKind, pageUrl, allowedHosts, successCookieName, pollIntervalMs, gotoTimeoutMs, blockedRequests, signal) {
     return await page.withResourcePolicy({
         allowedMethods: ["GET", "HEAD", "POST"],
         documentContentSecurityPolicy: RESOLVER_DOCUMENT_CONTENT_SECURITY_POLICY,
         routes: [
             {
                 match: () => true,
-                handle: (request) => ({
-                    action: isResolverBrowserRequestAllowed(request.url, challengeKind, allowedHosts)
-                        ? "continue"
-                        : "block",
-                }),
+                handle: (request) => {
+                    if (isResolverBrowserRequestAllowed(request.url, challengeKind, allowedHosts)) {
+                        return { action: "continue" };
+                    }
+                    blockedRequests.add(request.url);
+                    return { action: "block" };
+                },
             },
         ],
     }, async () => {
         const userAgent = await raceWithAbort(() => page.userAgent(), signal);
-        await raceWithAbort(() => page.goto(pageUrl), signal);
+        try {
+            await raceWithAbort(() => page.goto(pageUrl, {
+                timeout: gotoTimeoutMs,
+                waitUntil: "domcontentloaded",
+            }), signal);
+        }
+        catch (error) {
+            if (!isNavigationBlockedError(error))
+                throw error;
+            throw new BrowserNavigationBlockedError(pageUrl, [...blockedRequests], { cause: error });
+        }
         while (true) {
             const cookies = await raceWithAbort(() => page.cookies(), signal);
             const successCookie = selectSuccessCookie(cookies, successCookieName, pageUrl);
@@ -203,7 +237,7 @@ function poolErrorCode(error) {
     const code = error.code;
     return typeof code === "number" ? code : undefined;
 }
-function knownUnavailableReason(error) {
+function knownUnavailableReason(error, beforePageSolve = false) {
     // Source-grounded mappings:
     // - apps/cdp-pool/src/index.ts: the JSON-RPC codes and messages below.
     // - src/runtime/browser.ts: BROWSER_CDP_POOL_REQUIRED and the two WebSocket messages.
@@ -230,7 +264,10 @@ function knownUnavailableReason(error) {
         error.message.includes("WebSocket closed")) {
         return "transport_failure";
     }
-    return undefined;
+    // Browser creation, Playwright launch, and CDP connection all happen before the
+    // isolated-page handler is entered. Errors after that boundary belong to the
+    // challenge solve and must retain their existing classification.
+    return beforePageSolve ? "transport_failure" : undefined;
 }
 async function closeBrowserClient(client, timeoutMs, challengeKind, traceRecorder) {
     const close = client?.close;
@@ -274,10 +311,11 @@ export function createBrowserResolverVendorAdapter(options) {
                 // Refuse so the chain can choose a vendor that can honor the resolved identity.
                 throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "not_implemented");
             }
+            const blockedRequests = new Set();
             const solveController = new AbortController();
             const onCallerAbort = () => solveController.abort(abortReason(callerSignal));
             callerSignal.addEventListener("abort", onCallerAbort, { once: true });
-            const timeout = setTimeout(() => solveController.abort(new BrowserSolveTimeoutError()), options.timeoutMs);
+            const timeout = setTimeout(() => solveController.abort(new BrowserSolveTimeoutError([...blockedRequests])), options.timeoutMs);
             let client;
             let handlerEntered = false;
             try {
@@ -290,7 +328,7 @@ export function createBrowserResolverVendorAdapter(options) {
                 });
                 const contextOperation = client.withIsolatedContext(async (page) => {
                     handlerEntered = true;
-                    return await solveInPage(page, challengeKind, challenge.pageUrl, options.allowedHosts, SUCCESS_COOKIE_NAMES[challengeKind], pollIntervalMs, solveController.signal);
+                    return await solveInPage(page, challengeKind, challenge.pageUrl, options.allowedHosts, SUCCESS_COOKIE_NAMES[challengeKind], pollIntervalMs, options.timeoutMs, blockedRequests, solveController.signal);
                 });
                 try {
                     return await raceWithAbort(() => contextOperation, solveController.signal);
@@ -315,10 +353,15 @@ export function createBrowserResolverVendorAdapter(options) {
                         cause: error,
                     });
                 }
+                if (error instanceof BrowserNavigationBlockedError) {
+                    throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "transport_failure", {
+                        cause: error,
+                    });
+                }
                 if (error instanceof ResolverVendorUnavailableError) {
                     throw error;
                 }
-                const reason = knownUnavailableReason(error);
+                const reason = knownUnavailableReason(error, !handlerEntered);
                 if (reason) {
                     throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, reason, { cause: error });
                 }

package/dist/runtime/resolver-vendors/types.d.ts

@@ -1,4 +1,4 @@
-import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind, ProviderResolverVendor } from "../../types.js";
+import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind, ProviderResolverConfig, ProviderResolverVendor } from "../../types.js";
 import type { TraceRecorder } from "../trace.js";
 export declare const RESOLVER_VENDOR_CAPABILITIES: {
     readonly browser: readonly ["aws_waf", "cloudflare_interstitial"];
@@ -7,7 +7,15 @@ export declare const RESOLVER_VENDOR_CAPABILITIES: {
     readonly capmonster: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha"];
     readonly custom: readonly ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha", "cloudflare_interstitial", "aws_waf", "akamai_sec_cpt", "akamai_sensor"];
 };
+/**
+ * SDK-owned fallback policy for hosted resolver vendors. Capability support is
+ * applied separately, so each provider receives only vendors that support one
+ * or more of its declared challenge kinds.
+ */
+export declare const DEFAULT_RESOLVER_VENDOR_PREFERENCE: readonly ["capsolver", "2captcha"];
 export declare function resolverVendorSupports(vendor: ProviderResolverVendor, kind: ProviderChallengeKind): boolean;
+/** Resolves an explicit provider override or the SDK-owned default vendor chain. */
+export declare function resolveProviderResolverVendors(config: ProviderResolverConfig): readonly ProviderResolverVendor[];
 export interface ResolverIdentity {
     readonly proxyUrl: string;
     readonly userAgent: string;

package/dist/runtime/resolver-vendors/types.js

@@ -33,9 +33,24 @@ export const RESOLVER_VENDOR_CAPABILITIES = {
         "akamai_sensor",
     ],
 };
+/**
+ * SDK-owned fallback policy for hosted resolver vendors. Capability support is
+ * applied separately, so each provider receives only vendors that support one
+ * or more of its declared challenge kinds.
+ */
+export const DEFAULT_RESOLVER_VENDOR_PREFERENCE = [
+    "capsolver",
+    "2captcha",
+];
 export function resolverVendorSupports(vendor, kind) {
     return RESOLVER_VENDOR_CAPABILITIES[vendor].includes(kind);
 }
+/** Resolves an explicit provider override or the SDK-owned default vendor chain. */
+export function resolveProviderResolverVendors(config) {
+    if (config.vendors !== undefined)
+        return config.vendors;
+    return DEFAULT_RESOLVER_VENDOR_PREFERENCE.filter((vendor) => config.kinds.some((kind) => resolverVendorSupports(vendor, kind)));
+}
 export class ResolverVendorUnavailableError extends Error {
     vendor;
     reason;

package/dist/runtime/resolver.d.ts

@@ -4,6 +4,7 @@ import { type ResolverIdentity, type ResolverVendorAdapter, type ResolverVendorT
 import type { TraceRecorder } from "./trace.js";
 export { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, 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>;
 type ResolverChainClient = ResolverContext & {
     solve(challenge: ProviderChallenge, signal?: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;

package/dist/runtime/resolver.js

@@ -7,12 +7,13 @@ import { createBrowserResolverVendorAdapter } from "./resolver-vendors/browser.j
 import { createCapsolverResolverVendorAdapter } from "./resolver-vendors/capsolver.js";
 import { assertResolverHostAllowed } from "./resolver-vendors/hosts.js";
 import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocaptcha.js";
-import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolverVendorSupports, } from "./resolver-vendors/types.js";
+import { RESOLVER_VENDOR_CAPABILITIES, ResolverVendorUnavailableError, resolveProviderResolverVendors, resolverVendorSupports, } from "./resolver-vendors/types.js";
 import { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
 import { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
 import { DEFAULT_PROFILE } from "./stealth.js";
 export { createUnsupportedResolverClient, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver-shared.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./resolver-config.js";
+export { DEFAULT_RESOLVER_VENDOR_PREFERENCE, resolveProviderResolverVendors, } from "./resolver-vendors/types.js";
 const RESOLVER_SOLUTION_CACHE_NAMESPACE = "resolver-solution";
 const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
 const MIN_RESOLVER_CACHE_TTL_MS = 1_000;
@@ -169,10 +170,12 @@ function assertKnownResolverVendor(vendor) {
         return;
     throw new Error(`Unknown resolver vendor "${vendor}" in resolver configuration`);
 }
-function throwUnsupportedKind(kind) {
+function throwUnsupportedKind(kind, usingDefaultVendors) {
     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.`,
     });
 }
 function throwExhausted(attempts) {
@@ -542,8 +545,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)
@@ -692,7 +696,8 @@ function createResolverClientFromEnvInternal(config, env, options, adapterFactor
         return createUnsupportedResolverClient("Provider does not declare resolver capability");
     }
     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: [],
@@ -704,7 +709,7 @@ function createResolverClientFromEnvInternal(config, env, options, adapterFactor
     const allowedHosts = [...(options.allowedHosts ?? [])];
     return createResolverChainClient({
         kinds: config.kinds,
-        entries: config.vendors.map((configuredVendor) => {
+        entries: vendors.map((configuredVendor) => {
             assertKnownResolverVendor(configuredVendor);
             const vendor = configuredVendor;
             return {
@@ -713,6 +718,7 @@ function createResolverClientFromEnvInternal(config, env, options, adapterFactor
                 createAdapter: () => createAdapter(resolveVendorAvailability(vendor, env), timeoutMs, allowedHosts, adapterFactories),
             };
         }),
+        usingDefaultVendors: config.vendors === undefined,
         cache: options.cache,
         proxyIntent: options.proxyIntent,
         identityScope: options.identityScope,

package/dist/server/serve-implementation.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join } from "node:path";
@@ -924,6 +925,28 @@ function extractRequestId(raw) {
     const value = Object.getOwnPropertyDescriptor(raw, "requestId")?.value;
     return typeof value === "string" ? value : undefined;
 }
+const MAX_PROVIDER_ERROR_CAUSE_FRAMES = 5;
+function providerErrorCauseChain(error) {
+    if (!(error instanceof Error) && !isProviderError(error))
+        return undefined;
+    const seen = new Set([error]);
+    const frames = [];
+    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, provider, kind, route, requestId, error, status, cost, declaredErrorCode) {
     const code = isProviderError(error)
         ? (error.code ?? "provider_error")
@@ -934,6 +957,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
                 : "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 &&
         isProviderError(error) &&
@@ -954,6 +978,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         code,
         errorClass,
         message,
+        ...(causeChain ? { causeChain } : {}),
         ...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
         errorCategory: details.category,
         taxonomyVersion: details.taxonomyVersion,

package/dist/types.d.ts

@@ -252,16 +252,16 @@ export interface ProviderSttConfig {
     mode: ProviderSttMode;
 }
 /**
- * `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" | "capsolver" | "capmonster" | "2captcha" | "custom";
 /**
@@ -339,8 +339,8 @@ export type ChallengeSolution = {
     readonly expires?: number;
 };
 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[];
     /**
@@ -1355,8 +1355,6 @@ export interface NativeNetworkClient {
 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[];
@@ -1496,6 +1494,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;
@@ -1762,7 +1764,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;
@@ -1863,8 +1865,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;
@@ -1876,6 +1878,12 @@ export interface ProviderContext {
     resolver: ResolverContext;
     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;
@@ -1921,7 +1929,7 @@ export interface OperationContractMetadata {
     lifecycle?: OperationLifecycle;
     deprecation?: OperationDeprecationMetadata;
 }
-export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike> {
+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
      * verbatim; the APIFuse registry derives the operation's en locale title
@@ -1951,7 +1959,7 @@ export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOu
     retryOnAuthRefresh?: boolean;
     input: TInput;
     output: TOutput;
-    handler(ctx: ProviderContext, input: InferSchemaOutput<TInput>): OperationHandlerResult<InferSchemaOutput<TOutput>> | Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
+    handler(ctx: TContext, input: InferSchemaOutput<TInput>): OperationHandlerResult<InferSchemaOutput<TOutput>> | Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
     fixtures?: {
         request: InferSchemaOutput<TInput>;
         response: InferSchemaOutput<TOutput>;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.35",
+	"version": "2.2.0-beta.37",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -111,6 +111,9 @@
 		"type-check": "tsc --noEmit",
 		"test": "bun test",
 		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run lint:test-typesafety && bun run build",
+		"api:update": "bun run build && bun scripts/api-reports.ts update",
+		"api:check": "bun run build && bun scripts/api-reports.ts check",
+		"changeset:check": "bun scripts/check-changeset.ts",
 		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
 		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
 		"pack:types": "bun run build && bun bin/apifuse-pack-types.ts",
@@ -121,6 +124,8 @@
 	"devDependencies": {
 		"@arethetypeswrong/cli": "^0.18.5",
 		"@biomejs/biome": "^2.5.0",
+		"@changesets/cli": "^3.0.1",
+		"@microsoft/api-extractor": "^7.58.13",
 		"@types/bun": "latest",
 		"@types/node": "^25.9.3",
 		"ajv": "^8.17",

package/src/ceremonies/index.ts

@@ -7,6 +7,7 @@ import {
 	TurnValidationError,
 	ValidationError,
 } from "../errors.js";
+import type { AuthStartNoInputGuard } from "../define.js";
 import type { AuthFlowDefinition, AuthFlowInputHandler, AuthTurn, FlowContext } from "../types.js";
 
 type TurnKind = KnownAuthTurnKind;
@@ -224,6 +225,18 @@ export function validateCeremonyOutput(turn: unknown): AuthTurn {
 	return turn as AuthTurn;
 }
 
+/**
+ * Defines an auth flow while preserving its concrete type for downstream checks.
+ * The compile-time guard validates the inferred literal; annotating or widening
+ * a flow to `AuthFlowDefinition` before passing it defeats the check. Full
+ * enforcement requires branding, which is deferred to a future major.
+ */
+export function defineAuthFlow<const TFlow extends AuthFlowDefinition>(
+	flow: TFlow & AuthStartNoInputGuard<TFlow>,
+): TFlow {
+	return flow;
+}
+
 export function createOAuth2Ceremony(options: {
 	authorizeUrl: string;
 	tokenUrl: string;
@@ -232,7 +245,7 @@ export function createOAuth2Ceremony(options: {
 	scopes: string[];
 	usePKCE?: boolean;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -306,7 +319,7 @@ export function createOAuth2Ceremony(options: {
 				input,
 			),
 		abort: async () => validateCeremonyOutput(createTurn("abort", { hint: "OAuth flow aborted." })),
-	};
+	});
 }
 
 /**
@@ -384,7 +397,7 @@ export function createDeviceFlowCeremony(options: {
 	clientSecretEnvKey?: string;
 	scopes: string[];
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -461,7 +474,7 @@ export function createDeviceFlowCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Device flow aborted." })),
-	};
+	});
 }
 
 export function createWebAuthnCeremony(options: {
@@ -470,7 +483,7 @@ export function createWebAuthnCeremony(options: {
 	verifyUrl?: string;
 	timeoutMs?: number;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -529,7 +542,7 @@ export function createWebAuthnCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "WebAuthn ceremony aborted." })),
-	};
+	});
 }
 
 export function createMagicLinkCeremony(options: {
@@ -539,23 +552,31 @@ export function createMagicLinkCeremony(options: {
 	expiresInMs?: number;
 }): AuthFlowDefinition {
 	const emailField = options.emailField ?? "email";
+	const buildEmailForm = () =>
+		buildJsonSchemaForm(
+			{
+				type: "object",
+				required: [emailField],
+				properties: {
+					[emailField]: { type: "string", format: "email" },
+				},
+			},
+			"Provide the email address to receive a magic link.",
+		);
 
-	return {
-		start: (ctx, input = {}) =>
+	return defineAuthFlow({
+		start: (ctx) =>
+			runCeremonyHandler(
+				async () => buildEmailForm(),
+				"Magic link start failed",
+				ctx,
+			),
+		continue: (ctx, input = {}) =>
 			runCeremonyHandler(
 				async () => {
 					const email = getString(input, emailField);
 					if (!email) {
-						return buildJsonSchemaForm(
-							{
-								type: "object",
-								required: [emailField],
-								properties: {
-									[emailField]: { type: "string", format: "email" },
-								},
-							},
-							"Provide the email address to receive a magic link.",
-						);
+						return buildEmailForm();
 					}
 
 					await ctx.http.post(options.sendUrl, { email });
@@ -570,17 +591,10 @@ export function createMagicLinkCeremony(options: {
 						timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
 					});
 				},
-				"Magic link start failed",
+				"Magic link continuation failed",
 				ctx,
 				input,
 			),
-		continue: async () =>
-			validateCeremonyOutput(
-				createTurn("poll", {
-					hint: "Continue polling for magic link completion.",
-					timing: { suggestedPollIntervalMs: 5_000, maxWaitMs: 300_000 },
-				}),
-			),
 		poll: (ctx) =>
 			runCeremonyHandler(
 				async () => {
@@ -616,7 +630,7 @@ export function createMagicLinkCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Magic link flow aborted." })),
-	};
+	});
 }
 
 export function createFormCeremony(options: {
@@ -624,7 +638,7 @@ export function createFormCeremony(options: {
 	hint?: string;
 	mapCredential?: (input: Record<string, unknown>) => JsonObject;
 }): AuthFlowDefinition {
-	return {
+	return defineAuthFlow({
 		start: async () =>
 			validateCeremonyOutput(
 				buildJsonSchemaForm(
@@ -656,7 +670,7 @@ export function createFormCeremony(options: {
 			),
 		abort: async () =>
 			validateCeremonyOutput(createTurn("abort", { hint: "Form ceremony aborted." })),
-	};
+	});
 }
 
 export function combineCeremonies(...ceremonies: AuthFlowDefinition[]): AuthFlowDefinition {
@@ -739,7 +753,7 @@ export function createSwitchCeremony(options: {
 }): AuthFlowDefinition {
 	const choiceKeys = Object.keys(options.choices);
 
-	return {
+	return defineAuthFlow({
 		start: async () =>
 			validateCeremonyOutput(
 				createTurn("multi_choice", {
@@ -811,5 +825,5 @@ export function createSwitchCeremony(options: {
 				"Switch ceremony abort failed",
 				ctx,
 			),
-	};
+	});
 }

package/src/cli/templates/provider/Dockerfile.tpl

@@ -1,6 +1,6 @@
 FROM oven/bun:1.2-alpine
 WORKDIR /provider
-COPY package.json bun.lockb* ./
+COPY package.json bun.lock ./
 RUN bun install --frozen-lockfile
 COPY . .
 EXPOSE 3000