@apifuse/provider-sdk 2.2.0-beta.61 → 2.2.0-beta.63

package/dist/provider.d.ts

@@ -6,14 +6,16 @@ export type { OperationDefinitionFor, ProviderBuilder, ProviderContextOf, Provid
 export type { JsonPrimitive, JsonValue } from "./contract-json.js";
 export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
 export type { AssertionExpression, AssertionPredicate, AttemptReference, AssertResult, AssertStep, BoundedJsonPath, CandidateBlock, CandidatePolicy, CandidateReference, CredentialReference, CredentialRefDeclaration, EstablishedConnectionReference, ExtractStep, FindFirst, GuardAttribution, GuardReasonCode, GuardResult, GuardStep, HealthScenario, HealthStep, JsonTemplate, JournalPolicy, ManualTriggerPolicy, NonEmpty, OperationResult, OperationStep, Operand, Quantifier, ReferenceNode, Reference, RelativeDateNode, RetryPolicy, SafeRegex, ScopedAssertionExpression, ScopedAssertionPredicate, ScopedItemReference, ScopedOperand, StepBase, StepReference, ExtractResult, ValueType, } from "./health-scenario.js";
-export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, type ProviderErrorObservability, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
-export { createProviderEnvironment, createInProcessProviderEngine, 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_PROTOCOL_VERSION, readEngineProxyCredentials, } from "./engine.js";
-export type { ProviderCapabilityKey, ProviderEngine, ProviderEngineAttachmentInput, ProviderEngineBindingCandidates, ProviderEngineCapabilitySurface, ProviderEngineRequest, ProviderEngineResidentSurface, ProviderEngineSession, ProviderEngineTransport, } from "./engine.js";
-export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
+export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderEgressDeniedError, ProviderEngineAuthenticationError, ProviderEngineProtocolVersionError, ProviderEngineUnavailableError, ProviderError, type ProviderErrorObservability, SDKError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
+export { createProviderEnvironment, createInProcessProviderEngine, 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 type { ProviderCapabilityKey, ProviderEngine, ProviderEngineAttachmentInput, ProviderEngineBindingCandidates, ProviderEngineCapabilitySurface, ProviderEngineMode, ProviderEngineRequest, ProviderEngineResidentSurface, ProviderEngineSession, ProviderEngineTransport, } from "./engine.js";
+export { getProviderLocalePath, type ProviderErrorMessageParams, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export * from "./handle.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
 export { type CreateHandleContextOptions, type CreateTestHandleContextOptions, createHandleContext, createTestHandleContext, type HandleNormalizationClass, type NormalizedHandle, normalizeHandle, } from "./runtime/handle.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, 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, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, ProviderAccessVisibility, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeTarget, ProviderRuntimeState, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthChallengeClassification, } from "./types.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, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, ProviderAccessVisibility, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderResolvedFile, ProviderRuntimeTarget, ProviderRuntimeState, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, RedirectRunReason, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthChallengeClassification, } 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/provider.js

@@ -2,11 +2,13 @@ export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, define
 export { createFormCeremony } from "./ceremonies/index.js";
 export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define.js";
 export { AssertionExpressionSchema, AssertionPredicateSchema, AssertStepSchema, BoundedJsonPathSchema, CandidateBlockSchema, CandidatePolicySchema, CredentialRefDeclarationSchema, defineHealthScenario, HealthScenarioSchema, HealthStepSchema, ExtractStepSchema, FindFirstSchema, GuardStepSchema, JournalPolicySchema, JsonTemplateSchema, ManualTriggerPolicySchema, OperandSchema, OperationStepSchema, QuantifierSchema, ReferenceSchema, RetryPolicySchema, SafeRegexSchema, ScopedAssertionExpressionSchema, ScopedAssertionPredicateSchema, ScopedItemReferenceSchema, ScopedOperandSchema, StepReferenceSchema, RelativeDateNodeSchema, ValueTypeSchema, } from "./health-scenario.js";
-export { AuthError, HttpRedirectError, isProviderError, isSessionExpiredError, isTransportError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors.js";
-export { createProviderEnvironment, createInProcessProviderEngine, 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_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 { createProviderEnvironment, createInProcessProviderEngine, 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 { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n/index.js";
 export * from "./handle.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
 export { createHandleContext, createTestHandleContext, normalizeHandle, } from "./runtime/handle.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 { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types.js";

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 & {
@@ -6,6 +7,7 @@ export type BrowserClientOptions = BrowserOptions & {
     executablePath?: string;
     extraArgs?: string[];
     serviceWorkers?: "allow" | "block";
+    telemetry?: BrowserTelemetrySink;
 };
 export declare class BrowserClient implements BrowserClientContract {
     private readonly client;
@@ -13,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>;