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

package/dist/define.js

@@ -109,13 +109,357 @@ function parsePositiveMsDuration(value) {
         return undefined;
     return parsed;
 }
-/** Define one provider operation with schema-driven handler inference. */
-export function defineOperation(operation) {
-    return operation;
+function splitAuthStartParameters(parameters) {
+    const parts = [];
+    let start = 0;
+    let round = 0;
+    let square = 0;
+    let curly = 0;
+    let quote;
+    let escaped = false;
+    let lineComment = false;
+    let blockComment = false;
+    const templateDepths = [0];
+    templateDepths.length = 0;
+    for (let index = 0; index < parameters.length; index++) {
+        const character = parameters[index];
+        const nextCharacter = parameters[index + 1];
+        if (lineComment) {
+            if (character === "\n" || character === "\r")
+                lineComment = false;
+            else
+                continue;
+        }
+        if (blockComment) {
+            if (character === "*" && nextCharacter === "/") {
+                blockComment = false;
+                index++;
+            }
+            continue;
+        }
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+            }
+            else if (character === "\\") {
+                escaped = true;
+            }
+            else if (quote === "`" && character === "$" && nextCharacter === "{") {
+                curly++;
+                templateDepths.push(curly);
+                quote = undefined;
+                index++;
+            }
+            else if (character === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (character === "'" || character === '"' || character === "`") {
+            quote = character;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "/") {
+            lineComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "*") {
+            blockComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/")
+            return undefined;
+        // Annex B HTML-like comments are not lexed here; give up rather than
+        // risk misreading the parameter list.
+        if (character === "<" && parameters.startsWith("!--", index + 1))
+            return undefined;
+        if (character === "-" && parameters.startsWith("->", index + 1))
+            return undefined;
+        if (character === "(")
+            round++;
+        else if (character === ")")
+            round--;
+        else if (character === "[")
+            square++;
+        else if (character === "]")
+            square--;
+        else if (character === "{")
+            curly++;
+        else if (character === "}") {
+            if (templateDepths.at(-1) === curly) {
+                templateDepths.pop();
+                curly--;
+                quote = "`";
+            }
+            else
+                curly--;
+        }
+        else if (character === "," && round === 0 && square === 0 && curly === 0) {
+            parts.push(parameters.slice(start, index));
+            start = index + 1;
+        }
+        if (round < 0 || square < 0 || curly < 0)
+            return undefined;
+    }
+    if (quote ||
+        blockComment ||
+        templateDepths.length > 0 ||
+        round !== 0 ||
+        square !== 0 ||
+        curly !== 0)
+        return undefined;
+    parts.push(parameters.slice(start));
+    return parts;
+}
+function authStartParameterList(source) {
+    let index = 0;
+    while (index < source.length && /\s/.test(source[index] ?? ""))
+        index++;
+    if (index >= source.length)
+        return undefined;
+    let openIndex = -1;
+    let parenthesizedArrow = false;
+    let asyncMethodOrArrow = false;
+    const skipTrivia = () => {
+        while (index < source.length) {
+            if (/\s/.test(source[index] ?? "")) {
+                index++;
+                continue;
+            }
+            if (source[index] === "/" && source[index + 1] === "/") {
+                index += 2;
+                while (index < source.length && source[index] !== "\n" && source[index] !== "\r")
+                    index++;
+                continue;
+            }
+            if (source[index] === "/" && source[index + 1] === "*") {
+                const end = source.indexOf("*/", index + 2);
+                if (end < 0) {
+                    index = source.length;
+                    return;
+                }
+                index = end + 2;
+                continue;
+            }
+            return;
+        }
+    };
+    const initial = source.slice(index);
+    const isAsync = initial.startsWith("async") && !/[\w$]/.test(initial[5] ?? "");
+    if (isAsync) {
+        index += 5;
+        skipTrivia();
+    }
+    const afterAsync = source.slice(index);
+    const isFunction = afterAsync.startsWith("function") && !/[\w$]/.test(afterAsync[8] ?? "");
+    if (isFunction) {
+        index += 8;
+        skipTrivia();
+        if (source[index] === "*") {
+            index++;
+            skipTrivia();
+        }
+    }
+    else if (source[index] === "*") {
+        index++;
+        skipTrivia();
+    }
+    if (source[index] === "(") {
+        openIndex = index;
+        parenthesizedArrow = !isFunction;
+        asyncMethodOrArrow = isAsync && !isFunction;
+    }
+    else if (isFunction) {
+        if (!/[A-Za-z_$]/.test(source[index] ?? ""))
+            return undefined;
+        index++;
+        while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? ""))
+            index++;
+        skipTrivia();
+        if (source[index] !== "(")
+            return undefined;
+        openIndex = index;
+    }
+    else {
+        const identifierStart = index;
+        if (!/[A-Za-z_$]/.test(source[index] ?? ""))
+            return undefined;
+        index++;
+        while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? ""))
+            index++;
+        const firstIdentifier = source.slice(identifierStart, index);
+        skipTrivia();
+        if (source[index] === "=" && source[index + 1] === ">")
+            return undefined;
+        if (source[index] !== "(") {
+            if (firstIdentifier !== "get" && firstIdentifier !== "set")
+                return undefined;
+            if (!/[A-Za-z_$]/.test(source[index] ?? ""))
+                return undefined;
+            index++;
+            while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? ""))
+                index++;
+            skipTrivia();
+        }
+        if (source[index] !== "(")
+            return undefined;
+        openIndex = index;
+    }
+    if (openIndex < 0)
+        return undefined;
+    let depth = 1;
+    let square = 0;
+    let curly = 0;
+    let quote;
+    let escaped = false;
+    let lineComment = false;
+    let blockComment = false;
+    const templateDepths = [0];
+    templateDepths.length = 0;
+    for (index = openIndex + 1; index < source.length; index++) {
+        const character = source[index];
+        const nextCharacter = source[index + 1];
+        if (lineComment) {
+            if (character === "\n" || character === "\r")
+                lineComment = false;
+            else
+                continue;
+        }
+        if (blockComment) {
+            if (character === "*" && nextCharacter === "/") {
+                blockComment = false;
+                index++;
+            }
+            continue;
+        }
+        if (quote) {
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (quote === "`" && character === "$" && nextCharacter === "{") {
+                curly++;
+                templateDepths.push(curly);
+                quote = undefined;
+                index++;
+            }
+            else if (character === quote)
+                quote = undefined;
+            continue;
+        }
+        if (character === "'" || character === '"' || character === "`") {
+            quote = character;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "/") {
+            lineComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/" && nextCharacter === "*") {
+            blockComment = true;
+            index++;
+            continue;
+        }
+        if (character === "/")
+            return undefined;
+        // Annex B HTML-like comments are not lexed here; give up rather than
+        // risk misreading the parameter list.
+        if (character === "<" && source.startsWith("!--", index + 1))
+            return undefined;
+        if (character === "-" && source.startsWith("->", index + 1))
+            return undefined;
+        if (character === "(")
+            depth++;
+        else if (character === ")") {
+            depth--;
+            if (depth === 0 && square === 0 && curly === 0) {
+                const closeIndex = index;
+                if (parenthesizedArrow) {
+                    index++;
+                    skipTrivia();
+                    const hasArrow = source[index] === "=" && source[index + 1] === ">";
+                    if (!hasArrow && (!asyncMethodOrArrow || source[index] !== "{"))
+                        return undefined;
+                }
+                return source.slice(openIndex + 1, closeIndex);
+            }
+            if (depth < 0)
+                return undefined;
+        }
+        else if (character === "[")
+            square++;
+        else if (character === "]") {
+            square--;
+            if (square < 0)
+                return undefined;
+        }
+        else if (character === "{")
+            curly++;
+        else if (character === "}") {
+            if (templateDepths.at(-1) === curly) {
+                templateDepths.pop();
+                curly--;
+                quote = "`";
+            }
+            else
+                curly--;
+            if (curly < 0)
+                return undefined;
+        }
+    }
+    return undefined;
 }
-/** Define a non-JSON provider operation with explicit transport metadata. */
-export function defineStreamOperation(operation) {
-    return operation;
+/**
+ * Conservative defense in depth for defaulted second parameters, which
+ * JavaScript intentionally omits from Function.length. Ambiguous source is
+ * ignored so this check can never reject a valid provider on weak evidence.
+ */
+function authStartHasHiddenInput(start) {
+    let source;
+    try {
+        source = Function.prototype.toString.call(start);
+    }
+    catch {
+        return false;
+    }
+    if (!source ||
+        source.includes("[native code]") ||
+        /^\s*(?:async\s+)?function\s+bound\b/.test(source))
+        return false;
+    const parameters = authStartParameterList(source);
+    if (!parameters)
+        return false;
+    const parts = splitAuthStartParameters(parameters);
+    if (!parts || parts.length < 2)
+        return false;
+    // Require ordinary, readable source formatting. This intentionally fails
+    // open for minified output and for transpilers that rewrite defaults.
+    const commaIndex = parameters.indexOf(",");
+    if (commaIndex < 0 || !/\s/.test(parameters[commaIndex + 1] ?? ""))
+        return false;
+    const first = parts[0].trim();
+    const second = parts[1].trim();
+    const identifier = /^[_$A-Za-z][_$A-Za-z0-9]*/;
+    const firstName = first.match(identifier)?.[0];
+    const secondName = second.match(identifier)?.[0];
+    if (!firstName || !secondName || firstName.length < 3 || secondName.length < 3)
+        return false;
+    return /\s=\s/.test(second);
+}
+/** Define one factored provider operation with schema-driven handler inference. */
+export function defineOperation() {
+    return function operation(config) {
+        return config;
+    };
+}
+/** Define a factored non-JSON operation with explicit transport metadata. */
+export function defineStreamOperation() {
+    return function streamOperation(config) {
+        return config;
+    };
 }
 function assertObjectConfig(value) {
     if (!value || typeof value !== "object") {
@@ -218,6 +562,11 @@ function validateProviderShape(config) {
     assertRequiredField(config, "operations", String(config.id));
     if (typeof config.runtime === "string")
         assertLiteralField(config.runtime, "runtime", VALID_RUNTIMES, String(config.id));
+    if (config.native !== undefined && config.runtime === "browser") {
+        throw new ValidationError(`Provider "${String(config.id)}" cannot declare capability "native" with runtime "browser"`, {
+            fix: 'Use runtime: "standard" or runtime: "shared", or remove the native declaration.',
+        });
+    }
     const auth = config.auth;
     if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
         assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
@@ -241,6 +590,19 @@ function validateProviderShape(config) {
             fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
         });
     }
+    if (auth &&
+        typeof auth === "object" &&
+        "flow" in auth &&
+        auth.flow &&
+        typeof auth.flow === "object" &&
+        "start" in auth.flow &&
+        typeof auth.flow.start === "function" &&
+        auth.flow.start.length <= 1 &&
+        authStartHasHiddenInput(auth.flow.start)) {
+        throw new ProviderError(`Provider "${String(config.id)}" auth.flow.start must not declare an input parameter`, {
+            fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
+        });
+    }
     const access = config.access;
     if (access !== undefined) {
         if (!access || typeof access !== "object" || Array.isArray(access)) {
@@ -427,7 +789,9 @@ function validateProviderResolver(config) {
         });
     }
     rejectUnknownFields(resolver, new Set(["vendors", "kinds", "clientProfile"]), "resolver", config.id);
-    validateResolverLiteralArray(resolver.vendors, "resolver.vendors", VALID_PROVIDER_RESOLVER_VENDORS, config.id);
+    if (resolver.vendors !== undefined) {
+        validateResolverLiteralArray(resolver.vendors, "resolver.vendors", VALID_PROVIDER_RESOLVER_VENDORS, config.id);
+    }
     validateResolverLiteralArray(resolver.kinds, "resolver.kinds", VALID_PROVIDER_CHALLENGE_KINDS, config.id);
     if (resolver.clientProfile !== undefined &&
         (typeof resolver.clientProfile !== "string" || !resolver.clientProfile.trim())) {
@@ -1580,7 +1944,15 @@ function validateProviderDeployment(providerId, deployment) {
             fix: 'Pass deployment: { runtime: "shared" | "dedicated" | "browser", ... } or remove the field',
         });
 }
-export function defineProvider(config) {
+/** Establish a provider declaration before its operations are contextually typed. */
+export function defineProvider(declaration) {
+    const buildProvider = (implementation) => finalizeProvider({
+        ...declaration,
+        ...implementation,
+    });
+    return buildProvider;
+}
+function finalizeProvider(config) {
     validateProviderShape(config);
     const operations = resolveOperationFixtureRequests(config.operations);
     if (!CONNECTOR_ID_REGEX.test(config.id))
@@ -1647,7 +2019,7 @@ export function defineProvider(config) {
         credential: config.credential,
         context: config.context,
         meta: config.meta,
-        operations,
+        operations: operations,
         // Transitional healthMonitor → healthProbe alias: mirror whichever field
         // was declared onto both so old and new consumers keep working.
         healthMonitor: config.healthMonitor ?? config.healthProbe,

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export * from "./choice-token.js";
 export type { ApiFuseConfig, BrowserConfig, ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyVendorName, ResolvedProxyConfig, SessionConfig, } from "./config/loader.js";
 export { defineConfig, loadApiFuseConfig, resolveProxy } from "./config/loader.js";
 export { canonicalJson, digestProviderContract, extractProviderContract, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, } from "./contract.js";
-export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type ProviderConfig, } from "./define.js";
+export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type AuthStartNoInputGuard, type ProviderBuilder, type ProviderContextOf, type ProviderDeclaration, } from "./define.js";
 export type { DevServerOptions } from "./dev.js";
 export { createDevServer, startDevServer } from "./dev.js";
 export * from "./errors.js";
@@ -42,7 +42,7 @@ export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SEN
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ServeOptions, serve, } from "./server/serve.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 export * from "./utils/date.js";
 export * from "./utils/parse.js";

package/dist/provider.d.ts

@@ -3,11 +3,12 @@ export type { CredentialsAuthChallengeDefinition, CredentialsAuthChallengeReques
 export { createFormCeremony } from "./ceremonies/index.js";
 export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, type ProviderChoiceTokenErrorReason, type ProviderChoiceTokenPayload, parseProviderChoiceToken, } from "./choice-token.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
+export type { ProviderBuilder, ProviderContextOf, ProviderDeclaration, } from "./define.js";
 export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
 export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";
-export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProviderContext, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, } from "./types.js";
+export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, ProviderErrorStatus, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceConsumeMode, ProviderChoiceConsumeResult, ProviderChoiceContext, ProviderChoiceExplicitParseResult, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, } from "./types.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export type { NativeGatewayProxy, NativeGatewayProxyResolutionInput, NativeGatewayProxySkipReason, NativeGatewayProxySynthesizer, NativeGatewayProxySynthesisResult, NativeGatewayProxySynthesisInput, NativeNetworkClientOptions, NativeNetworkErrorCode, VendorCredentialLookup, VendorCredentialResolver, } from "./runtime/native-network.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/runtime/browser.js

@@ -548,8 +548,8 @@ class PlaywrightBrowserPage {
         this.page = page;
         this.proxy = proxy;
     }
-    async goto(url) {
-        await this.page.goto(url);
+    async goto(url, options) {
+        await this.page.goto(url, options);
     }
     async evaluate(fn) {
         if (typeof fn === "string") {
@@ -1101,16 +1101,22 @@ class CdpPoolBrowserPage {
     get id() {
         return this.pageId;
     }
-    async goto(url) {
+    async goto(url, options) {
         await this.initialize();
         const startedAt = Date.now();
-        let loadEventSeen = false;
-        const unsubscribe = this.pageClient.on("Page.loadEventFired", () => {
-            loadEventSeen = true;
+        const timeout = options?.timeout ?? DEFAULT_WAIT_TIMEOUT_MS;
+        const waitUntil = options?.waitUntil ?? "load";
+        let expectedEventSeen = false;
+        const eventName = waitUntil === "domcontentloaded" ? "Page.domContentEventFired" : "Page.loadEventFired";
+        const unsubscribe = this.pageClient.on(eventName, () => {
+            expectedEventSeen = true;
         });
         try {
-            await this.pageClient.send("Page.navigate", { url });
-            await this.waitForDocumentReady(startedAt + DEFAULT_WAIT_TIMEOUT_MS, () => loadEventSeen);
+            const navigation = (await this.pageClient.send("Page.navigate", { url }));
+            if (typeof navigation.errorText === "string" && navigation.errorText.length > 0) {
+                throw new Error(`Page.navigate failed: ${navigation.errorText} at ${url}`);
+            }
+            await this.waitForDocumentReady(startedAt + timeout, () => expectedEventSeen, waitUntil);
         }
         finally {
             unsubscribe();
@@ -1397,11 +1403,13 @@ class CdpPoolBrowserPage {
         this.frameExecutionContexts.set(frameId, contextId);
         return contextId;
     }
-    async waitForDocumentReady(deadline, isLoadEventSeen) {
+    async waitForDocumentReady(deadline, isExpectedEventSeen, waitUntil) {
         while (Date.now() < deadline) {
             const readyState = await this.evaluate("document.readyState");
-            if (readyState === "complete" || readyState === "interactive") {
-                if (isLoadEventSeen() || readyState === "complete") {
+            const documentReady = readyState === "complete" ||
+                (waitUntil === "domcontentloaded" && readyState === "interactive");
+            if (documentReady) {
+                if (isExpectedEventSeen() || readyState === "complete") {
                     return;
                 }
             }

package/dist/runtime/choice.js

@@ -407,13 +407,6 @@ async function parseWordServerStoredChoice(options) {
             record.prefix !== options.parseOptions.prefix) {
             throw wordChoiceNotFoundError();
         }
-        assertFreshProviderChoiceIssuedAt(record.issued_at_ms, {
-            ttlMs: options.parseOptions.ttlMs != null
-                ? Math.min(options.parseOptions.ttlMs, record.ttl_ms)
-                : record.ttl_ms,
-            nowMs: options.parseOptions.nowMs,
-            futureToleranceMs: options.parseOptions.futureToleranceMs,
-        });
         assertPayloadDigestMatches({
             actual: digestChoicePayload(serializeChoicePayload(record.payload)),
             expected: record.payload_digest,
@@ -434,6 +427,30 @@ async function parseWordServerStoredChoice(options) {
         }
         throw error;
     }
+    // Freshness is classified last, reachable only after every identity,
+    // integrity, and binding check above has passed (ADR 0006, amended
+    // 2026-08-20): a caller that proved the record's binding may observe the
+    // canonical stale error, while an unbound record keeps the collapsed
+    // not-found error so expiry never becomes an existence signal for
+    // guessable tokens.
+    try {
+        assertFreshProviderChoiceIssuedAt(record.issued_at_ms, {
+            ttlMs: options.parseOptions.ttlMs != null
+                ? Math.min(options.parseOptions.ttlMs, record.ttl_ms)
+                : record.ttl_ms,
+            nowMs: options.parseOptions.nowMs,
+            futureToleranceMs: options.parseOptions.futureToleranceMs,
+        });
+    }
+    catch (error) {
+        const recordIsBound = Boolean(record.binding?.connection_hash || record.binding?.credential_hash);
+        if (recordIsBound && error instanceof ProviderChoiceTokenError && error.reason === "stale") {
+            throw error;
+        }
+        if (error instanceof ProviderChoiceTokenError)
+            throw wordChoiceNotFoundError();
+        throw error;
+    }
     const consumeMode = options.parseOptions.consume ?? "never";
     if (record.status === "consumed") {
         if (consumeMode === "explicit") {

package/dist/runtime/resolver-public.d.ts

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, } from "./resolver.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, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, } from "./resolver.js";

package/dist/runtime/resolver-public.js

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, } from "./resolver.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, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";