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

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.39
+
+- Release candidate for main commit ecbe349c44e15c873b7c58b42e14610db029eb5f.
+
 ## 2.2.0-beta.38
 
 - Release candidate for main commit 448775077dbc9ab907209f1feee4e6e4e5ef4283.

package/dist/declaration-validation.d.ts

@@ -23,3 +23,10 @@ export type DeclarationViolation = {
 export declare function declarationInvalidError(violations: readonly DeclarationViolation[]): ProviderError;
 /** Enforces declaration rules whose runtime behavior would otherwise fail open. */
 export declare function validateFailClosedDeclaration(provider: ProviderDefinition): void;
+type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "proxy">;
+type OperationDeclarationRulesInput = Pick<ProviderDefinition, "operations">;
+/** Enforces fail-closed rules that only depend on the provider declaration. */
+export declare function validateFailClosedProviderDeclaration(provider: ProviderDeclarationRulesInput): void;
+/** Enforces fail-closed rules that depend on the operation implementation. */
+export declare function validateFailClosedOperationDeclaration(provider: OperationDeclarationRulesInput): void;
+export {};

package/dist/declaration-validation.js

@@ -34,6 +34,28 @@ export function validateFailClosedDeclaration(provider) {
     if (violations.length > 0)
         throw declarationInvalidError(violations);
 }
+/** Enforces fail-closed rules that only depend on the provider declaration. */
+export function validateFailClosedProviderDeclaration(provider) {
+    const violations = [];
+    collectProviderDeclarationViolations(provider, violations);
+    if (violations.length > 0)
+        throw declarationInvalidError(violations);
+}
+/** Enforces fail-closed rules that depend on the operation implementation. */
+export function validateFailClosedOperationDeclaration(provider) {
+    const violations = [];
+    collectOperationDeclarationViolations(provider, violations);
+    if (violations.length > 0)
+        throw declarationInvalidError(violations);
+}
+function collectProviderDeclarationViolations(provider, violations) {
+    validateHealthDeclaration(provider, violations);
+    validateProxyDeclaration(provider, violations);
+}
+function collectOperationDeclarationViolations(provider, violations) {
+    validateSchemaDeclaration(provider, violations);
+    validateOperationDeclaration(provider, violations);
+}
 function validateHealthDeclaration(provider, violations) {
     for (const [index, journey] of (provider.healthJourneys ?? []).entries()) {
         if (!journey || typeof journey !== "object")

package/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderContext, ProviderContextFor, ProviderOcrConfig, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types.js";
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderOcrConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types.js";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
 interface ProviderImplementationProfile {
@@ -125,7 +125,7 @@ export declare function defineHealthJourney(config: HealthJourneyDefinition): He
 /** The second authoring phase for a declaration established by defineProvider. */
 export type ProviderBuilder<TDeclaration extends ProviderDeclaration> = <TOperations extends Record<string, ProviderOperation>>(implementation: {
     operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
-}) => ProviderDefinition & {
+}) => Omit<ProviderDefinition, "operations"> & {
     operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
 };
 /** Extract the declaration-derived operation context from a provider builder. */

package/dist/define.js

@@ -1,5 +1,5 @@
 import ms from "ms";
-import { validateFailClosedDeclaration } from "./declaration-validation.js";
+import { validateFailClosedOperationDeclaration, validateFailClosedProviderDeclaration, } from "./declaration-validation.js";
 import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
 import { NativeEgressPolicyValidationError, validateNativeProviderConfig, } from "./native-egress-policy.js";
@@ -553,13 +553,12 @@ function validateProxiedOAuthAuth(auth, providerId) {
     validateProxiedOAuthParams(config.authorizeParams, "authorizeParams", providerId);
     validateProxiedOAuthParams(config.tokenParams, "tokenParams", providerId);
 }
-function validateProviderShape(config) {
+function validateProviderDeclarationShape(config) {
     assertObjectConfig(config);
     assertRequiredField(config, "id");
     assertRequiredField(config, "version", String(config.id));
     assertRequiredField(config, "runtime", String(config.id));
     assertRequiredField(config, "meta", String(config.id));
-    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") {
@@ -629,6 +628,10 @@ function validateProviderShape(config) {
         }
     }
 }
+function validateProviderImplementationShape(config) {
+    const configRecord = config;
+    assertRequiredField(configRecord, "operations", String(config.id));
+}
 function validateProviderProxy(config) {
     const proxy = config.proxy;
     if (proxy === undefined || typeof proxy === "boolean") {
@@ -1951,38 +1954,24 @@ function validateProviderDeployment(providerId, deployment) {
 }
 /** Establish a provider declaration before its operations are contextually typed. */
 export function defineProvider(declaration) {
+    validateProviderDeclaration(declaration);
     const buildProvider = (implementation) => finalizeProvider({
         ...declaration,
         ...implementation,
     });
     return buildProvider;
 }
-function finalizeProvider(config) {
-    validateProviderShape(config);
-    const operations = resolveOperationFixtureRequests(config.operations);
+function validateProviderDeclaration(config) {
+    validateProviderDeclarationShape(config);
     if (!CONNECTOR_ID_REGEX.test(config.id))
         throw new ProviderError(`Invalid provider id: "${config.id}"`, {
             fix: 'Use lowercase alphanumeric with dashes, e.g., "korea-air-quality"',
         });
-    if (Object.keys(config.operations).length === 0)
-        throw new ProviderError(`Provider "${config.id}" must define at least one operation`, {
-            fix: "Add at least one operation to the operations object",
-        });
-    validateOperationIds(config.id, config.operations);
-    validateOperationAnnotations(config.id, config.operations);
-    validateOperationObservability(config.id, config.operations);
-    validateOperationErrorCodes(config.id, config.operations);
-    validateOperationTransports(config.id, config.operations);
-    validateOperationContracts(config.id, config.operations);
-    validateToolRouterMetadata(config.id, config.operations);
-    const journeyCoveredOperations = validateHealthJourneys(config.id, config.operations, config.healthJourneys);
-    validateOperationHealthChecks(config.id, config.operations, journeyCoveredOperations);
     if (config.healthMonitor !== undefined && config.healthProbe !== undefined)
         throw new ValidationError(`Provider "${config.id}" declares both healthMonitor and healthProbe. They are aliases; declare exactly one.`, {
             fix: "Keep healthProbe (the new name) and delete the healthMonitor block.",
         });
     validateProviderHealthMonitor(config.id, config.healthProbe ?? config.healthMonitor, config.healthProbe !== undefined ? "healthProbe" : "healthMonitor");
-    validateOperationFixtures(config.id, operations);
     validateProviderDeployment(config.id, config.deployment);
     try {
         validateNativeProviderConfig(config.native);
@@ -2002,6 +1991,25 @@ function finalizeProvider(config) {
         });
     if (config.browser && config.runtime !== "browser")
         throw new ProviderError(`Provider "${config.id}" cannot define browser config unless runtime is "browser"`, { fix: 'Set runtime: "browser" or remove the browser config' });
+    validateFailClosedProviderDeclaration(config);
+}
+function finalizeProvider(config) {
+    validateProviderImplementationShape(config);
+    const operations = resolveOperationFixtureRequests(config.operations);
+    if (Object.keys(config.operations).length === 0)
+        throw new ProviderError(`Provider "${config.id}" must define at least one operation`, {
+            fix: "Add at least one operation to the operations object",
+        });
+    validateOperationIds(config.id, config.operations);
+    validateOperationAnnotations(config.id, config.operations);
+    validateOperationObservability(config.id, config.operations);
+    validateOperationErrorCodes(config.id, config.operations);
+    validateOperationTransports(config.id, config.operations);
+    validateOperationContracts(config.id, config.operations);
+    validateToolRouterMetadata(config.id, config.operations);
+    const journeyCoveredOperations = validateHealthJourneys(config.id, config.operations, config.healthJourneys);
+    validateOperationHealthChecks(config.id, config.operations, journeyCoveredOperations);
+    validateOperationFixtures(config.id, operations);
     const provider = {
         id: config.id,
         version: config.version,
@@ -2024,13 +2032,15 @@ function finalizeProvider(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,
         healthProbe: config.healthProbe ?? config.healthMonitor,
         healthJourneys: config.healthJourneys,
     };
-    validateFailClosedDeclaration(provider);
+    // Declaration validation never invokes handlers, so their declaration-bound
+    // context parameter is irrelevant to the runtime ProviderDefinition shape.
+    validateFailClosedOperationDeclaration(provider);
     return provider;
 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export * from "./auth.js";
 export * from "./ceremonies/index.js";
 export * from "./choice-token.js";
-export type { ApiFuseConfig, BrowserConfig, ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyVendorName, ResolvedProxyConfig, SessionConfig, } from "./config/loader.js";
+export type { ApiFuseConfig, BrowserConfig, ProxyCacheStatus, ProxyProtocol, ProxyResolutionOptions, ProxyResolutionSource, ProxyUserAgentSource, ProxyVendorName, ResolvedProxyConfig, SessionConfig, SmartproxyAllocatorBodyClass, } 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 AuthStartNoInputGuard, type ProviderBuilder, type ProviderContextOf, type ProviderDeclaration, } from "./define.js";
@@ -31,6 +31,7 @@ export { generateInsights } from "./runtime/insights.js";
 export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export type { PrevalidateResult } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
+export type { ProxyTelemetryLogPayload } from "./runtime/proxy-telemetry.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";

package/dist/runtime/executor.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderContext, ProviderDefinition } from "../types.js";
+import type { ProviderDefinition } from "../types.js";
 export declare function isStreamingOperation(provider: ProviderDefinition, operationId: string): boolean;
 /**
  * Execute a provider operation by calling its handler.
@@ -11,6 +11,6 @@ export declare function isStreamingOperation(provider: ProviderDefinition, opera
  *
  * @see openspec/provider-sdk/03-sdk-core.md §3.6
  */
-export declare function executeOperation(provider: ProviderDefinition, operationId: string, ctx: ProviderContext, input: unknown, _options?: {
+export declare function executeOperation<const TProvider extends ProviderDefinition, const TOperationId extends keyof TProvider["operations"] & string>(provider: TProvider, operationId: TOperationId, ctx: NoInfer<Parameters<TProvider["operations"][TOperationId]["handler"]>[0]>, input: unknown, _options?: {
     skipAuth?: boolean;
 }): Promise<unknown>;

package/dist/runtime/executor.js

@@ -30,7 +30,9 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
     // handler, so every invocation path (serve /v1, self-test probes, perf,
     // record) fails with the same structured MISSING_SECRET error instead of a
     // handler-specific crash. Providers must not re-check presence locally.
-    assertRequiredSecretsPresent(provider, ctx.env);
+    if (provider.secrets?.some((secret) => secret.required === true)) {
+        assertRequiredSecretsPresent(provider, "env" in ctx ? ctx.env : { get: () => undefined });
+    }
     const validatedInput = await parseSchema(operation.input, input, `operations.${operationId}.input`);
     const execute = () => ctx.trace.span(`handler:${operationId}`, () => Promise.resolve(operation.handler(ctx, validatedInput)));
     let result;

package/dist/runtime/instrumentation.d.ts

@@ -2,7 +2,7 @@ import type { ProviderContext } from "../types.js";
 import { type CreateTraceContextOptions, type TraceContext } from "./trace.js";
 export interface InstrumentationOptions extends CreateTraceContextOptions {
 }
-export type InstrumentedProviderContext<T extends ProviderContext> = Omit<T, "trace"> & {
+export type InstrumentedProviderContext<T extends Pick<ProviderContext, "trace">> = Omit<T, "trace"> & {
     trace: TraceContext;
 };
-export declare function wrapWithInstrumentation<T extends ProviderContext>(ctx: T, options?: InstrumentationOptions): InstrumentedProviderContext<T>;
+export declare function wrapWithInstrumentation<T extends Pick<ProviderContext, "trace">>(ctx: T, options?: InstrumentationOptions): InstrumentedProviderContext<T>;

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

@@ -1,9 +1,49 @@
-import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink, ProxyVendorFailoverTelemetryEvent } from "../config/loader.js";
+import type { ProxyAttemptTelemetryEvent, ProxyCacheStatus, ProxyProtocol, ProxyResolutionTelemetryEvent, ProxyTelemetrySink, ProxyUserAgentSource, ProxyVendorFailoverTelemetryEvent, ProxyVendorName, SmartproxyAllocatorBodyClass } from "../config/loader.js";
 export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
+export type ProxyTelemetryLogPayload = {
+    provider: ProxyVendorName;
+    userAgentSource?: ProxyUserAgentSource;
+    protocol?: ProxyProtocol;
+    cacheStatus: ProxyCacheStatus;
+    cacheHit: boolean;
+    resolutionMs: number;
+    allocatorMs?: number;
+    allocatorStatus?: number;
+    allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+    allocatorAttempts?: number;
+    lockWaitMs?: number;
+    redisReadMs?: number;
+    redisWriteMs?: number;
+    poolAgeMs?: number;
+    poolExpiresInMs?: number;
+    attempts: number;
+    refreshes?: number;
+    attemptSamples?: {
+        n: number;
+        a: number;
+        i?: number;
+        h?: string;
+        o: ProxyAttemptTelemetryEvent["outcome"];
+        c?: string;
+        s?: number;
+        d?: number;
+    }[];
+    /** Distinct vendors attempted across the resolution chain, in order seen. */
+    vendors?: ProxyVendorName[];
+    /** Cross-vendor failover events (bounded). */
+    failovers?: {
+        v: ProxyVendorName;
+        nx?: ProxyVendorName;
+        p: ProxyVendorFailoverTelemetryEvent["phase"];
+        r: ProxyVendorFailoverTelemetryEvent["reason"];
+        a?: number;
+    }[];
+};
 export declare class ProxyTelemetryCollector implements ProxyTelemetrySink {
     #private;
     recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
     recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void;
     recordProxyAttempt(event: ProxyAttemptTelemetryEvent): void;
+    toLogPayload(): ProxyTelemetryLogPayload | undefined;
     toHeaderValue(): string | undefined;
 }

package/dist/runtime/proxy-telemetry.js

@@ -86,7 +86,7 @@ export class ProxyTelemetryCollector {
                 : { durationMs: Math.max(0, Math.floor(event.durationMs)) }),
         });
     }
-    toHeaderValue() {
+    toLogPayload() {
         const [first, ...rest] = this.#events;
         if (!first)
             return undefined;
@@ -116,62 +116,65 @@ export class ProxyTelemetryCollector {
             attempts: acc.attempts + event.attempts,
             refreshes: sumOptional(acc.refreshes, event.refreshes),
         }), first);
-        const payload = {
-            v: 1,
-            proxy: {
-                provider: serving.provider,
-                ...(aggregate.userAgentSource ? { userAgentSource: aggregate.userAgentSource } : {}),
-                ...(serving.protocol ? { protocol: serving.protocol } : {}),
-                cacheStatus: aggregate.cacheStatus,
-                cacheHit: aggregate.cacheHit,
-                resolutionMs: aggregate.resolutionMs,
-                ...(aggregate.allocatorMs !== undefined ? { allocatorMs: aggregate.allocatorMs } : {}),
-                ...(aggregate.allocatorStatus !== undefined
-                    ? { allocatorStatus: aggregate.allocatorStatus }
-                    : {}),
-                ...(aggregate.allocatorBodyClass !== undefined
-                    ? { allocatorBodyClass: aggregate.allocatorBodyClass }
-                    : {}),
-                ...(aggregate.allocatorAttempts !== undefined
-                    ? { allocatorAttempts: aggregate.allocatorAttempts }
-                    : {}),
-                ...(aggregate.lockWaitMs !== undefined ? { lockWaitMs: aggregate.lockWaitMs } : {}),
-                ...(aggregate.redisReadMs !== undefined ? { redisReadMs: aggregate.redisReadMs } : {}),
-                ...(aggregate.redisWriteMs !== undefined ? { redisWriteMs: aggregate.redisWriteMs } : {}),
-                ...(aggregate.poolAgeMs !== undefined ? { poolAgeMs: aggregate.poolAgeMs } : {}),
-                ...(aggregate.poolExpiresInMs !== undefined
-                    ? { poolExpiresInMs: aggregate.poolExpiresInMs }
-                    : {}),
-                attempts: aggregate.attempts,
-                ...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
-                ...(this.#attempts.length > 0
-                    ? {
-                        attemptSamples: this.#attempts.map((attempt, index) => ({
-                            n: index + 1,
-                            a: attempt.attempt,
-                            ...(attempt.poolIndex === undefined ? {} : { i: attempt.poolIndex }),
-                            ...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
-                            o: attempt.outcome,
-                            ...(attempt.errorCode ? { c: attempt.errorCode } : {}),
-                            ...(attempt.status === undefined ? {} : { s: attempt.status }),
-                            ...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
-                        })),
-                    }
-                    : {}),
-                ...(vendors.length > 1 ? { vendors } : {}),
-                ...(this.#failovers.length > 0
-                    ? {
-                        failovers: this.#failovers.map((failover) => ({
-                            v: failover.vendor,
-                            ...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
-                            p: failover.phase,
-                            r: failover.reason,
-                            ...(failover.attempt === undefined ? {} : { a: failover.attempt }),
-                        })),
-                    }
-                    : {}),
-            },
+        return {
+            provider: serving.provider,
+            ...(aggregate.userAgentSource ? { userAgentSource: aggregate.userAgentSource } : {}),
+            ...(serving.protocol ? { protocol: serving.protocol } : {}),
+            cacheStatus: aggregate.cacheStatus,
+            cacheHit: aggregate.cacheHit,
+            resolutionMs: aggregate.resolutionMs,
+            ...(aggregate.allocatorMs !== undefined ? { allocatorMs: aggregate.allocatorMs } : {}),
+            ...(aggregate.allocatorStatus !== undefined
+                ? { allocatorStatus: aggregate.allocatorStatus }
+                : {}),
+            ...(aggregate.allocatorBodyClass !== undefined
+                ? { allocatorBodyClass: aggregate.allocatorBodyClass }
+                : {}),
+            ...(aggregate.allocatorAttempts !== undefined
+                ? { allocatorAttempts: aggregate.allocatorAttempts }
+                : {}),
+            ...(aggregate.lockWaitMs !== undefined ? { lockWaitMs: aggregate.lockWaitMs } : {}),
+            ...(aggregate.redisReadMs !== undefined ? { redisReadMs: aggregate.redisReadMs } : {}),
+            ...(aggregate.redisWriteMs !== undefined ? { redisWriteMs: aggregate.redisWriteMs } : {}),
+            ...(aggregate.poolAgeMs !== undefined ? { poolAgeMs: aggregate.poolAgeMs } : {}),
+            ...(aggregate.poolExpiresInMs !== undefined
+                ? { poolExpiresInMs: aggregate.poolExpiresInMs }
+                : {}),
+            attempts: aggregate.attempts,
+            ...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
+            ...(this.#attempts.length > 0
+                ? {
+                    attemptSamples: this.#attempts.map((attempt, index) => ({
+                        n: index + 1,
+                        a: attempt.attempt,
+                        ...(attempt.poolIndex === undefined ? {} : { i: attempt.poolIndex }),
+                        ...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
+                        o: attempt.outcome,
+                        ...(attempt.errorCode ? { c: attempt.errorCode } : {}),
+                        ...(attempt.status === undefined ? {} : { s: attempt.status }),
+                        ...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
+                    })),
+                }
+                : {}),
+            ...(vendors.length > 1 ? { vendors } : {}),
+            ...(this.#failovers.length > 0
+                ? {
+                    failovers: this.#failovers.map((failover) => ({
+                        v: failover.vendor,
+                        ...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
+                        p: failover.phase,
+                        r: failover.reason,
+                        ...(failover.attempt === undefined ? {} : { a: failover.attempt }),
+                    })),
+                }
+                : {}),
         };
+    }
+    toHeaderValue() {
+        const proxy = this.toLogPayload();
+        if (!proxy)
+            return undefined;
+        const payload = { v: 1, proxy };
         const encoded = encodeBase64Url(JSON.stringify(payload));
         if (encoded.length > MAX_HEADER_BYTES)
             return undefined;

package/dist/server/index.d.ts

@@ -1,3 +1,5 @@
+export type { ProxyCacheStatus, ProxyProtocol, ProxyUserAgentSource, ProxyVendorName, SmartproxyAllocatorBodyClass, } from "../config/loader.js";
+export type { ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
 export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";

package/dist/server/serve-implementation.d.ts

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { z } from "zod";
 import { type ProviderErrorCategory } from "../observability.js";
+import { type ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
 import type { OcrContext, ProviderContext, ProviderDefinition, ProviderRuntimeState, ResolverContext, SttContext } from "../types.js";
 import type { SelfTestCancellationLogEvent } from "./self-test.js";
 import { type AuthFlowRequest, type OperationRequest } from "./types.js";
@@ -76,6 +77,7 @@ type ProviderServerLogEventBase = ProviderRequestCost & {
     route: string;
     requestId?: string;
     status: number;
+    proxy?: ProxyTelemetryLogPayload;
 };
 export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     level: "info";