@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/dist/observability.js

@@ -1,4 +1,5 @@
-export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-05-26";
+// Mirrors packages/provider-observability in the platform monorepo (SoT).
+export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-08-07";
 export const PROVIDER_ERROR_CATEGORIES = [
     "ok",
     "timeout",
@@ -6,6 +7,7 @@ export const PROVIDER_ERROR_CATEGORIES = [
     "upstream_http",
     "upstream_rate_limited",
     "upstream_auth",
+    "upstream_rejected",
     "upstream_schema_drift",
     "proxy_pool",
     "anti_bot_blocked",
@@ -15,6 +17,9 @@ export const PROVIDER_ERROR_CATEGORIES = [
     "output_validation",
     "provider_error",
     "internal_error",
+    "dependency_unavailable",
+    "unsupported_transport",
+    "client_cancelled",
     "unclassified",
 ];
 export function categoryForStatus(status) {
@@ -26,6 +31,10 @@ export function categoryForStatus(status) {
         return "upstream_rate_limited";
     if (status === 401 || status === 403)
         return "upstream_auth";
+    // provider-error-contract: 409/410/422 are the deterministic
+    // upstream-rejection status class — not a retryable upstream failure.
+    if (status === 409 || status === 410 || status === 422)
+        return "upstream_rejected";
     if (status >= 400)
         return "upstream_http";
     return "unclassified";
@@ -37,3 +46,41 @@ export function isRetryableCategory(category) {
         category === "upstream_http" ||
         category === "proxy_pool");
 }
+// Who stopped the request (honest-provider-error-contract). A deliberately
+// small public projection of the internal taxonomy:
+// - client: the request itself is fixable by the caller
+// - upstream_rule: the upstream service refused it under its own business
+//   rules (deterministic) or rate limits
+// - upstream_failure: the upstream service malfunctioned — retryable
+// - apifuse: an APIFuse-side fault (provider bug, platform dependency)
+export const PROVIDER_ERROR_SOURCES = [
+    "client",
+    "upstream_rule",
+    "upstream_failure",
+    "apifuse",
+];
+export function sourceForCategory(category) {
+    switch (category) {
+        case "input_validation":
+        case "credential_expired":
+        case "credential_unavailable":
+        case "client_cancelled":
+            return "client";
+        case "upstream_rejected":
+        case "upstream_rate_limited":
+            return "upstream_rule";
+        case "timeout":
+        case "network":
+        case "upstream_http":
+        case "upstream_auth":
+        case "upstream_schema_drift":
+        case "anti_bot_blocked":
+            return "upstream_failure";
+        default:
+            // ok never reaches error serialization; provider_error,
+            // internal_error, output_validation, proxy_pool,
+            // dependency_unavailable, unsupported_transport, unclassified are
+            // APIFuse-side faults.
+            return "apifuse";
+    }
+}

package/dist/provider.d.ts

@@ -1,11 +1,21 @@
-export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, defineCredentialsAuth, } from "./auth.js";
 export type { CredentialsAuthChallengeDefinition, CredentialsAuthChallengeRequest, CredentialsAuthCompleteResult, CredentialsAuthCredential, CredentialsAuthField, CredentialsAuthFields, CredentialsAuthFieldType, CredentialsAuthInput, CredentialsAuthLoginResult, DefineCredentialsAuthOptions, DefinedCredentialsAuth, } from "./auth.js";
+export { AuthAbortError, createAuthFlowHelpers, credentialsAuthChallenge, defineCredentialsAuth, } from "./auth.js";
 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 { AuthError, 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, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types.js";
+export type { JsonPrimitive, JsonValue } from "./contract-json.js";
+export type { OperationDefinitionFor, ProviderBuilder, ProviderContextOf, ProviderDeclaration, ProviderDefinitionFor, } from "./define.js";
+export { centered, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, delayed, every, } from "./define.js";
+export type { ProviderCapabilityKey, ProviderEngine, ProviderEngineAttachmentInput, ProviderEngineBindingCandidates, ProviderEngineCapabilitySurface, ProviderEngineMode, ProviderEngineRequest, ProviderEngineResidentSurface, ProviderEngineSession, ProviderEngineTransport, } from "./engine.js";
+export { createInProcessProviderEngine, createProviderEnvironment, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_MODE_ENV, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
+export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderEgressDeniedError, ProviderEngineAuthenticationError, ProviderEngineProtocolVersionError, ProviderEngineUnavailableError, ProviderError, type ProviderErrorObservability, SDKError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
+export * from "./handle.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, handleFieldNameFor, handleHasDirectionalFieldNames, isHandleFieldMeta, } from "./handle-meta.js";
+export type { AssertionExpression, AssertionPredicate, AssertResult, AssertStep, AttemptReference, BoundedJsonPath, CandidateBlock, CandidatePolicy, CandidateReference, CredentialRefDeclaration, CredentialReference, EstablishedConnectionReference, ExtractResult, ExtractStep, FindFirst, GuardAttribution, GuardReasonCode, GuardResult, GuardStep, HealthScenario, HealthStep, JournalPolicy, JsonTemplate, ManualTriggerPolicy, NonEmpty, Operand, OperationResult, OperationStep, Quantifier, Reference, ReferenceNode, RelativeDateNode, RetryPolicy, SafeRegex, ScopedAssertionExpression, ScopedAssertionPredicate, ScopedItemReference, ScopedOperand, StepBase, StepReference, ValueType, } from "./health-scenario.js";
+export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, ExtractStepSchema, FindFirstSchema, GUARD_REASON_CODES, GuardStepSchema, HealthScenarioSchema, HealthStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RelativeDateNodeSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, ValueTypeSchema, } from "./health-scenario.js";
+export { getProviderLocalePath, type ProviderErrorMessageParams, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
+export { type CreateHandleContextOptions, type CreateTestHandleContextOptions, createHandleContext, createTestHandleContext, type HandleNormalizationClass, type NormalizedHandle, normalizeHandle, } from "./runtime/handle.js";
+export type { NativeGatewayProxy, NativeGatewayProxyResolutionInput, NativeGatewayProxySkipReason, NativeGatewayProxySynthesisInput, NativeGatewayProxySynthesisResult, NativeGatewayProxySynthesizer, NativeNetworkClientOptions, NativeNetworkErrorCode, VendorCredentialLookup, VendorCredentialResolver, } from "./runtime/native-network.js";
+export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
+export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, } from "./runtime/state.js";
+export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, publicField, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, untrustedContent, z, } from "./schema.js";
+export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpAttemptContext, HttpHeadersFactory, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnectInput, NativeNetworkConnection, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationErrorCode, OperationExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, ProviderAccessVisibility, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderErrorStatus, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeState, ProviderRuntimeTarget, ProviderStateDurationString, ProviderStateNamespace, ProviderStealthConfig, ProviderSupportLevel, ProxiedOAuthConfig, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthChallengeClassification, } from "./types.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/provider.js

@@ -1,9 +1,14 @@
-export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, defineCredentialsAuth, } from "./auth.js";
+export { AuthAbortError, createAuthFlowHelpers, credentialsAuthChallenge, defineCredentialsAuth, } from "./auth.js";
 export { createFormCeremony } from "./ceremonies/index.js";
-export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, parseProviderChoiceToken, } from "./choice-token.js";
-export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
-export { AuthError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
+export { centered, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, delayed, every, } from "./define.js";
+export { createInProcessProviderEngine, createProviderEnvironment, ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RESOLVER_CREDENTIAL_ENV_NAMES, ENGINE_OWNED_RUNTIME_ENV_NAMES, ENGINE_OWNED_TELEMETRY_ENV_NAMES, isEngineOwnedEnvName, isEngineOwnedProxyCredentialName, isEngineOwnedResolverCredentialName, isEngineOwnedRuntimeEnvName, isEngineOwnedTelemetryEnvName, PROVIDER_CAPABILITY_KEYS, PROVIDER_ENGINE_MODE_ENV, PROVIDER_ENGINE_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
+export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderEgressDeniedError, ProviderEngineAuthenticationError, ProviderEngineProtocolVersionError, ProviderEngineUnavailableError, ProviderError, SDKError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
+export * from "./handle.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, handleFieldNameFor, handleHasDirectionalFieldNames, isHandleFieldMeta, } from "./handle-meta.js";
+export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, ExtractStepSchema, FindFirstSchema, GUARD_REASON_CODES, GuardStepSchema, HealthScenarioSchema, HealthStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RelativeDateNodeSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, ValueTypeSchema, } from "./health-scenario.js";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
-export { 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, sensitive, z, } from "./schema.js";
+export { createHandleContext, createTestHandleContext, normalizeHandle, } from "./runtime/handle.js";
+export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
+export { createMemoryProviderRuntimeState, createUnsupportedProviderRuntimeState, } from "./runtime/state.js";
+export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, publicField, redactPayload, sensitive, untrustedContent, z, } from "./schema.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

package/dist/runtime/auth-flow.d.ts

@@ -1,6 +1,7 @@
-import type { ContextScratchpad, EnvContext, FlowContext, HttpClient, StealthClient, SttContext } from "../types.js";
+import type { ContextScratchpad, EnvContext, FlowContext, HttpClient, OcrContext, ProviderRuntimeState, StealthClient, SttContext } from "../types.js";
 export declare function createScratchpad(allowedKeys: string[], initial?: Record<string, unknown>): ContextScratchpad;
 export declare function createFlowContext(options: {
+    flowId?: string;
     http: HttpClient;
     stealth: StealthClient;
     env: EnvContext;
@@ -8,7 +9,11 @@ export declare function createFlowContext(options: {
     providerId: string;
     connectionId?: string;
     externalRef?: string;
+    /** Host-agnostic: callers pass an already-scoped runtime state, which this helper forwards verbatim. */
+    state?: ProviderRuntimeState;
     allowedKeys: string[];
     initialContext?: Record<string, unknown>;
+    ocr?: OcrContext;
     stt?: SttContext;
+    trace?: FlowContext["trace"];
 }): FlowContext;

package/dist/runtime/auth-flow.js

@@ -1,6 +1,9 @@
 import { ContextAccessError } from "../errors.js";
 import { createAuthFlowHelpers } from "../auth.js";
+import { createUnsupportedOcrClient } from "./ocr.js";
+import { createUnsupportedResolverClient } from "./resolver-shared.js";
 import { createUnsupportedSttClient } from "./stt.js";
+import { createTraceContext } from "./trace.js";
 function normalizeAllowedKeys(allowedKeys) {
     return new Set(allowedKeys.filter((key) => key.trim().length > 0));
 }
@@ -32,15 +35,20 @@ export function createScratchpad(allowedKeys, initial = {}) {
 }
 export function createFlowContext(options) {
     return {
+        flowId: options.flowId,
         connectionId: options.connectionId,
         externalRef: options.externalRef,
         tenantId: options.tenantId,
         providerId: options.providerId,
+        trace: options.trace ?? createTraceContext(),
         http: options.http,
+        state: options.state,
         stealth: options.stealth,
         env: options.env,
         context: createScratchpad(options.allowedKeys, options.initialContext),
+        ocr: options.ocr ?? createUnsupportedOcrClient(),
         stt: options.stt ?? createUnsupportedSttClient(),
+        resolver: createUnsupportedResolverClient("Resolver is not available in auth flow context"),
         auth: createAuthFlowHelpers(),
     };
 }

package/dist/runtime/bounded-expiring-map.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Map whose entries carry an expiry and whose size is capped.
+ *
+ * Expired entries are dropped when read and swept on every insert, so a
+ * process that keeps minting new keys does not retain dead values. When the
+ * cap is still exceeded after the sweep, the least recently used entry is
+ * evicted and counted in `capacityEvictions` so callers can tell the two
+ * kinds of removal apart. Callers pass `now` explicitly so a single timestamp
+ * is used across a lookup-then-store sequence.
+ */
+export declare class BoundedExpiringMap<K, V> {
+    #private;
+    constructor(maxEntries: number, expiresAt: (value: V) => number);
+    get size(): number;
+    /** Entries removed to satisfy `maxEntries`; expiry removals are not counted. */
+    get capacityEvictions(): number;
+    get(key: K, now: number): V | undefined;
+    set(key: K, value: V, now: number): void;
+    delete(key: K): boolean;
+    clear(): void;
+}

package/dist/runtime/bounded-expiring-map.js

@@ -0,0 +1,64 @@
+/**
+ * Map whose entries carry an expiry and whose size is capped.
+ *
+ * Expired entries are dropped when read and swept on every insert, so a
+ * process that keeps minting new keys does not retain dead values. When the
+ * cap is still exceeded after the sweep, the least recently used entry is
+ * evicted and counted in `capacityEvictions` so callers can tell the two
+ * kinds of removal apart. Callers pass `now` explicitly so a single timestamp
+ * is used across a lookup-then-store sequence.
+ */
+export class BoundedExpiringMap {
+    #entries = new Map();
+    #maxEntries;
+    #expiresAt;
+    #capacityEvictions = 0;
+    constructor(maxEntries, expiresAt) {
+        if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+            throw new RangeError("maxEntries must be a positive integer");
+        }
+        this.#maxEntries = maxEntries;
+        this.#expiresAt = expiresAt;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    /** Entries removed to satisfy `maxEntries`; expiry removals are not counted. */
+    get capacityEvictions() {
+        return this.#capacityEvictions;
+    }
+    get(key, now) {
+        if (!this.#entries.has(key))
+            return undefined;
+        const value = this.#entries.get(key);
+        this.#entries.delete(key);
+        if (this.#expiresAt(value) <= now)
+            return undefined;
+        // Re-insert so Map iteration order doubles as the LRU order.
+        this.#entries.set(key, value);
+        return value;
+    }
+    set(key, value, now) {
+        for (const [existingKey, existing] of this.#entries) {
+            if (this.#expiresAt(existing) <= now)
+                this.#entries.delete(existingKey);
+        }
+        this.#entries.delete(key);
+        if (this.#expiresAt(value) <= now)
+            return;
+        this.#entries.set(key, value);
+        if (this.#entries.size > this.#maxEntries) {
+            const oldest = this.#entries.keys().next();
+            if (!oldest.done) {
+                this.#entries.delete(oldest.value);
+                this.#capacityEvictions += 1;
+            }
+        }
+    }
+    delete(key) {
+        return this.#entries.delete(key);
+    }
+    clear() {
+        this.#entries.clear();
+    }
+}

package/dist/runtime/browser-telemetry-binding.d.ts

@@ -0,0 +1,5 @@
+import type { BrowserClient } from "../types.js";
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
+export declare function isSupportedBrowserBinding(value: unknown): value is BrowserClient;
+export declare function warnUnsupportedBrowserBinding(): void;
+export declare function bindBrowserTelemetry(client: BrowserClient, sink: BrowserTelemetrySink): BrowserClient;

package/dist/runtime/browser-telemetry-binding.js

@@ -0,0 +1,83 @@
+import { observeTelemetryCallback } from "./http-telemetry-guard.js";
+const methods = new Set(["newPage", "rawPage", "withIsolatedContext", "solveChallenge"]);
+const adapters = new WeakMap();
+let warned = false;
+export function isSupportedBrowserBinding(value) {
+    if ((typeof value !== "object" && typeof value !== "function") || value === null)
+        return false;
+    return [...methods].some((method) => {
+        try {
+            return typeof Reflect.get(value, method) === "function";
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function warnUnsupportedBrowserBinding() {
+    if (warned)
+        return;
+    warned = true;
+    try {
+        console.warn("[apifuse] browser telemetry not attached; reason=unsupported_binding_shape");
+    }
+    catch { }
+}
+export function bindBrowserTelemetry(client, sink) {
+    const existing = adapters.get(client);
+    if (existing) {
+        existing.sink = sink;
+        return existing.adapter;
+    }
+    const wrappers = new Map();
+    const adapter = new Proxy(Object.create(client), {
+        get(_target, property) {
+            const original = Reflect.get(client, property, client);
+            if (typeof property !== "string" || !methods.has(property) || typeof original !== "function")
+                return original;
+            const cached = wrappers.get(property);
+            if (cached && cached.original === original)
+                return cached.wrapped;
+            const wrapped = function (...args) {
+                const receiver = this === adapter ? client : this;
+                observeTelemetryCallback(state.sink, () => {
+                    const declared = client.engine;
+                    const engine = declared === "playwright-stealth" ||
+                        declared === "nodriver" ||
+                        declared === "selenium-uc"
+                        ? declared
+                        : "host";
+                    return state.sink.recordEngine(engine);
+                });
+                if (property === "newPage" || property === "rawPage" || property === "withIsolatedContext")
+                    observeTelemetryCallback(state.sink, () => state.sink.recordPoolAcquire("not_configured"));
+                let result;
+                try {
+                    result = Reflect.apply(original, receiver, args);
+                }
+                catch (error) {
+                    observeTelemetryCallback(state.sink, () => state.sink.recordError("other"));
+                    throw error;
+                }
+                try {
+                    if (result instanceof Promise)
+                        void Promise.prototype.then.call(result, undefined, () => {
+                            observeTelemetryCallback(state.sink, () => state.sink.recordError("other"));
+                        });
+                }
+                catch (error) {
+                    observeTelemetryCallback(state.sink, () => {
+                        throw error;
+                    });
+                }
+                return result;
+            };
+            wrappers.set(property, { original, wrapped });
+            return wrapped;
+        },
+    });
+    const state = { sink, adapter };
+    adapters.set(client, state);
+    adapters.set(adapter, state);
+    return adapter;
+}

package/dist/runtime/browser-telemetry.d.ts

@@ -0,0 +1,76 @@
+import type { BrowserEngine } from "../types.js";
+export type BrowserTelemetryEngine = BrowserEngine | "host";
+import { type ClosedEnum, type SpanIndex, type TelemetryContributor } from "./request-telemetry.js";
+export type BrowserTelemetryPoolAcquireOutcome = "ok" | "not_configured" | "queue_full" | "timed_out" | "shutting_down" | "unknown_lease" | "unknown_method" | "missing_allowed_hosts" | "transport_failure" | "other";
+export type BrowserTelemetryErrorCode = "BROWSER_CDP_POOL_REQUIRED" | "BROWSER_PROXY_INVALID" | "BROWSER_RUNTIME_UNSUPPORTED" | "BROWSER_CDP_POOL_ERROR" | "other";
+export type BrowserTelemetrySampleName = "browser.newPage" | "browser.page.goto" | "browser.page.fill" | "browser.page.click" | "browser.page.type" | "browser.page.waitForSelector" | "browser.evaluate" | "browser.content" | "browser.screenshot" | "other";
+export type BrowserTelemetryLogPayload = {
+    allocateMs: number;
+    pages: number;
+    navigations: number;
+    actions: number;
+    evaluate: number;
+    content: number;
+    screenshot: number;
+    poolAcquireOutcome?: BrowserTelemetryPoolAcquireOutcome;
+    poolAcquireAttempts: number;
+    poolAcquireFailures: number;
+    poolAcquireUnknownCode?: number;
+    proxyAuthChallenges: number;
+    engine?: BrowserTelemetryEngine;
+    lastErrorCode?: BrowserTelemetryErrorCode;
+    samples: {
+        name: BrowserTelemetrySampleName;
+        ms: number;
+        status: "ok" | "error";
+        diagnostics?: string;
+    }[];
+    dropped: number;
+    telemetryFailed?: true;
+};
+export type BrowserTelemetryHeaderPayload = {
+    allocateMs: number;
+    pages: number;
+    navigations: number;
+    actions: number;
+    evaluate: number;
+    content: number;
+    screenshot: number;
+    poolAcquireOutcome?: ClosedEnum<BrowserTelemetryPoolAcquireOutcome>;
+    poolAcquireAttempts: number;
+    poolAcquireFailures: number;
+    proxyAuthChallenges: number;
+    engine?: ClosedEnum<BrowserTelemetryEngine>;
+    lastErrorCode?: ClosedEnum<BrowserTelemetryErrorCode>;
+    samples: {
+        name: ClosedEnum<BrowserTelemetrySampleName>;
+        ms: number;
+        status: ClosedEnum<"ok" | "error">;
+    }[];
+    dropped: number;
+};
+export interface BrowserTelemetrySink {
+    recordPoolAcquire(outcome: BrowserTelemetryPoolAcquireOutcome): void;
+    recordPoolAcquireUnknownCode?(code: number): void;
+    recordProxyAuthChallenge(): void;
+    recordEngine(engine: BrowserTelemetryEngine): void;
+    recordError(code: BrowserTelemetryErrorCode): void;
+    markTelemetryFailed?(): void;
+}
+export declare class BrowserTelemetryCollector implements TelemetryContributor<BrowserTelemetryLogPayload, BrowserTelemetryHeaderPayload>, BrowserTelemetrySink {
+    #private;
+    readonly key: "browser";
+    constructor(options?: {
+        redact?: (value: string) => string;
+    });
+    recordPoolAcquire(outcome: BrowserTelemetryPoolAcquireOutcome): void;
+    recordPoolAcquireUnknownCode(code: number): void;
+    recordProxyAuthChallenge(): void;
+    recordEngine(engine: BrowserTelemetryEngine): void;
+    recordError(code: BrowserTelemetryErrorCode): void;
+    markTelemetryFailed(): void;
+    toLogPayload(spans: SpanIndex): BrowserTelemetryLogPayload | undefined;
+    toHeaderPayload(log: BrowserTelemetryLogPayload): BrowserTelemetryHeaderPayload;
+}
+/** Defence in depth for diagnostics that accidentally contain protocol headers. */
+export declare function stripBrowserHeaderMaterial(value: string): string;

package/dist/runtime/browser-telemetry.js

@@ -0,0 +1,165 @@
+import { Buffer } from "node:buffer";
+import { closedEnum, } from "./request-telemetry.js";
+const MAX_SAMPLES = 24;
+const SAMPLE_NAMES = new Set([
+    "browser.newPage",
+    "browser.page.goto",
+    "browser.page.fill",
+    "browser.page.click",
+    "browser.page.type",
+    "browser.page.waitForSelector",
+    "browser.evaluate",
+    "browser.content",
+    "browser.screenshot",
+]);
+function sampleName(name) {
+    if (name === "browser.page.evaluate")
+        return "browser.evaluate";
+    if (name === "browser.page.content")
+        return "browser.content";
+    if (name === "browser.page.screenshot")
+        return "browser.screenshot";
+    return name === "[REDACTION_FAILED]" || !SAMPLE_NAMES.has(name)
+        ? "other"
+        : name;
+}
+function boundedDiagnostics(text, redact) {
+    let result;
+    try {
+        result = stripBrowserHeaderMaterial(redact?.(text) ?? text);
+    }
+    catch {
+        return "[REDACTION_FAILED]";
+    }
+    const length = Math.min(result.length, 300);
+    const units = Buffer.alloc(length * 2);
+    for (let i = 0; i < length; i += 1)
+        units.writeUInt16LE(result.charCodeAt(i), i * 2);
+    return units.toString("utf16le");
+}
+function integer(value) {
+    return Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(Number.isFinite(value) ? value : 0)));
+}
+function add(a, b) {
+    return Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+}
+export class BrowserTelemetryCollector {
+    key = "browser";
+    #poolAcquireOutcome;
+    #poolAcquireAttempts = 0;
+    #poolAcquireFailures = 0;
+    #poolAcquireUnknownCode;
+    #telemetryFailed = false;
+    #proxyAuthChallenges = 0;
+    #engine;
+    #lastErrorCode;
+    #redact;
+    constructor(options = {}) {
+        this.#redact = options.redact;
+    }
+    recordPoolAcquire(outcome) {
+        this.#poolAcquireOutcome = outcome;
+        this.#poolAcquireAttempts = add(this.#poolAcquireAttempts, 1);
+        if (outcome !== "ok")
+            this.#poolAcquireFailures = add(this.#poolAcquireFailures, 1);
+    }
+    recordPoolAcquireUnknownCode(code) {
+        this.#poolAcquireUnknownCode = code;
+    }
+    recordProxyAuthChallenge() {
+        this.#proxyAuthChallenges = add(this.#proxyAuthChallenges, 1);
+    }
+    recordEngine(engine) {
+        this.#engine = engine;
+    }
+    recordError(code) {
+        this.#lastErrorCode = code;
+    }
+    markTelemetryFailed() {
+        this.#telemetryFailed = true;
+    }
+    toLogPayload(spans) {
+        const browserSpans = spans.spans.filter((span) => span.name === "browser.newPage" ||
+            span.name === "browser.rawPage" ||
+            span.name === "browser.withIsolatedContext" ||
+            span.name.startsWith("browser.page.") ||
+            /^browser\.(evaluate|content|screenshot)$/.test(span.name));
+        const failedSpan = spans.spans.some((span) => span.name === "[REDACTION_FAILED]");
+        if (browserSpans.length === 0 &&
+            !failedSpan &&
+            !this.#poolAcquireOutcome &&
+            this.#proxyAuthChallenges === 0 &&
+            !this.#engine &&
+            !this.#lastErrorCode &&
+            !this.#telemetryFailed)
+            return undefined;
+        const count = (name) => spans.count(name);
+        const sampleSpans = failedSpan
+            ? [...browserSpans, ...spans.spans.filter((span) => span.name === "[REDACTION_FAILED]")]
+            : browserSpans;
+        const samples = sampleSpans
+            .slice(0, MAX_SAMPLES)
+            .map((span) => ({
+            name: sampleName(span.name),
+            ms: integer(span.duration_ms),
+            status: (span.status === "error" ? "error" : "ok"),
+            ...(span.name === "[REDACTION_FAILED]"
+                ? { diagnostics: "[REDACTION_FAILED]" }
+                : span.error
+                    ? { diagnostics: boundedDiagnostics(span.error, this.#redact) }
+                    : {}),
+        }));
+        return {
+            allocateMs: integer(browserSpans
+                .filter((span) => span.name === "browser.newPage")
+                .reduce((sum, span) => sum + Number(span.attributes.allocate_ms ?? span.duration_ms), 0)),
+            pages: add(add(count("browser.newPage"), count("browser.rawPage")), count("browser.withIsolatedContext")),
+            navigations: integer(count("browser.page.goto")),
+            actions: ["fill", "click", "type", "waitForSelector"].reduce((sum, method) => add(sum, count(`browser.page.${method}`)), 0),
+            evaluate: add(count("browser.evaluate"), count("browser.page.evaluate")),
+            content: add(count("browser.page.content"), count("browser.content")),
+            screenshot: add(count("browser.page.screenshot"), count("browser.screenshot")),
+            ...(this.#poolAcquireOutcome ? { poolAcquireOutcome: this.#poolAcquireOutcome } : {}),
+            poolAcquireAttempts: this.#poolAcquireAttempts,
+            poolAcquireFailures: this.#poolAcquireFailures,
+            ...(this.#poolAcquireUnknownCode === undefined
+                ? {}
+                : { poolAcquireUnknownCode: this.#poolAcquireUnknownCode }),
+            proxyAuthChallenges: this.#proxyAuthChallenges,
+            ...(this.#engine ? { engine: this.#engine } : {}),
+            ...(this.#lastErrorCode ? { lastErrorCode: this.#lastErrorCode } : {}),
+            samples,
+            dropped: Math.max(0, sampleSpans.length - samples.length),
+            ...(this.#telemetryFailed ? { telemetryFailed: true } : {}),
+        };
+    }
+    toHeaderPayload(log) {
+        return {
+            allocateMs: log.allocateMs,
+            pages: log.pages,
+            navigations: log.navigations,
+            actions: log.actions,
+            evaluate: log.evaluate,
+            content: log.content,
+            screenshot: log.screenshot,
+            ...(log.poolAcquireOutcome ? { poolAcquireOutcome: closedEnum(log.poolAcquireOutcome) } : {}),
+            poolAcquireAttempts: log.poolAcquireAttempts,
+            poolAcquireFailures: log.poolAcquireFailures,
+            proxyAuthChallenges: log.proxyAuthChallenges,
+            ...(log.engine ? { engine: closedEnum(log.engine) } : {}),
+            ...(log.lastErrorCode ? { lastErrorCode: closedEnum(log.lastErrorCode) } : {}),
+            samples: log.samples.map((sample) => ({
+                name: closedEnum(sample.name),
+                ms: sample.ms,
+                status: closedEnum(sample.status),
+            })),
+            dropped: log.dropped,
+        };
+    }
+}
+/** Defence in depth for diagnostics that accidentally contain protocol headers. */
+export function stripBrowserHeaderMaterial(value) {
+    return value
+        .replace(/(^|[^\p{L}\p{N}_-])[\t ]*(?:cookie|set-cookie|authorization)[\t ]*(?::|=)[^\r\n]*/giu, "$1[REDACTED]")
+        .replace(/"(?:cookie|set-cookie|authorization)"[\t ]*:[\t ]*"(?:\\.|[^"\\])*"/giu, "[REDACTED]");
+}

package/dist/runtime/browser.d.ts

@@ -1,3 +1,4 @@
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
 import type { BrowserChallengeRequest, BrowserChallengeResult, BrowserClient as BrowserClientContract, BrowserEngine, BrowserOptions, BrowserPage } from "../types.js";
 type BrowserPageContract = BrowserPage;
 export type BrowserClientOptions = BrowserOptions & {
@@ -5,6 +6,8 @@ export type BrowserClientOptions = BrowserOptions & {
     cdpUrl?: string;
     executablePath?: string;
     extraArgs?: string[];
+    serviceWorkers?: "allow" | "block";
+    telemetry?: BrowserTelemetrySink;
 };
 export declare class BrowserClient implements BrowserClientContract {
     private readonly client;
@@ -12,6 +15,7 @@ export declare class BrowserClient implements BrowserClientContract {
     private activePage?;
     private readonly activePages;
     private readonly _engine;
+    private readonly telemetry?;
     constructor(options?: BrowserClientOptions);
     get engine(): BrowserEngine;
     newPage(): Promise<BrowserPageContract>;