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

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";
@@ -34,8 +35,8 @@ export declare const ProviderServerStatefulForwardEnvelopeSchema: z.ZodObject<{
         connection: z.ZodOptional<z.ZodObject<{
             id: z.ZodString;
             mode: z.ZodEnum<{
-                none: "none";
                 credentials: "credentials";
+                none: "none";
                 oauth2: "oauth2";
                 "platform-managed": "platform-managed";
                 oauth2_proxied: "oauth2_proxied";
@@ -76,6 +77,7 @@ type ProviderServerLogEventBase = ProviderRequestCost & {
     route: string;
     requestId?: string;
     status: number;
+    proxy?: ProxyTelemetryLogPayload;
 };
 export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
     level: "info";

package/dist/server/serve-implementation.js

@@ -21,7 +21,7 @@ import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
 import { createOcrClientFromEnv } from "../runtime/ocr.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
-import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
+import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector, } from "../runtime/proxy-telemetry.js";
 import { createUnsupportedResolverClient } from "../runtime/resolver-shared.js";
 import { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
 import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
@@ -348,7 +348,7 @@ function resolveOperationConnectionId(request) {
     // absent so it can never override a valid id or key a real scope. Requests
     // without any usable id fall back to the documented missing-connection
     // sentinel scope instead of scoping context/affinity/state under "".
-    return normalizeConnectionId(request.connection?.id) ?? normalizeConnectionId(request.connectionId);
+    return (normalizeConnectionId(request.connection?.id) ?? normalizeConnectionId(request.connectionId));
 }
 function normalizeConnectionId(id) {
     return id === "" ? undefined : id;
@@ -512,7 +512,7 @@ export function resolveAuthFlowProxyAffinityKey(provider, request) {
         request.providerId ??
         provider.id);
 }
-function createAuthFlowContext(provider, request, options, state, signal) {
+function createAuthFlowContext(provider, request, options, state, proxyTelemetry, signal) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
     const stealthProfile = getProviderStealthProfile(provider);
@@ -522,11 +522,13 @@ function createAuthFlowContext(provider, request, options, state, signal) {
     const proxyClientOptions = {
         upstream: { proxy: provider.proxy },
         affinityKey: resolveAuthFlowProxyAffinityKey(provider, request),
+        telemetry: proxyTelemetry,
     };
     const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
     const stealthClientOptions = {
         upstream: proxyClientOptions.upstream,
         affinityKey: proxyClientOptions.affinityKey,
+        telemetry: proxyTelemetry,
     };
     const { capabilityModules } = options;
     const logStealthCleanupError = (error) => logProviderCleanupError(options.logger, provider, "auth", "flow", request.requestId, "stealth", error);
@@ -947,7 +949,7 @@ function providerErrorCauseChain(error) {
     }
     return frames.length > 0 ? frames : undefined;
 }
-function logProviderError(logger, provider, kind, route, requestId, error, status, cost, declaredErrorCode) {
+function logProviderError(logger, provider, kind, route, requestId, error, status, cost, declaredErrorCode, proxyTelemetry) {
     const code = isProviderError(error)
         ? (error.code ?? "provider_error")
         : error instanceof z.ZodError
@@ -965,6 +967,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         typeof error.code === "string" &&
         !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code) &&
         declaredErrorCode === undefined;
+    const proxy = proxyTelemetry?.toLogPayload();
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     emit({
         level: status >= 500 ? "error" : "warn",
@@ -975,6 +978,7 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
         ...(requestId ? { requestId } : {}),
         status,
         ...cost,
+        ...(proxy ? { proxy } : {}),
         code,
         errorClass,
         message,
@@ -1008,7 +1012,8 @@ function logProviderCleanupError(logger, provider, kind, operationId, requestId,
         message,
     });
 }
-function logProviderSuccess(logger, provider, kind, route, requestId, status, cost) {
+function logProviderSuccess(logger, provider, kind, route, requestId, status, cost, proxyTelemetry) {
+    const proxy = proxyTelemetry?.toLogPayload();
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     emit({
         level: "info",
@@ -1019,6 +1024,7 @@ function logProviderSuccess(logger, provider, kind, route, requestId, status, co
         ...(requestId ? { requestId } : {}),
         status,
         ...cost,
+        ...(proxy ? { proxy } : {}),
     });
 }
 function toJsonSuccessResponse(result, ctx) {
@@ -1395,7 +1401,7 @@ function responseWithProviderTelemetry(response, proxyTelemetry) {
         statusText: response.statusText,
     });
 }
-async function handleAuthFlow(provider, request, route, options, state, signal) {
+async function handleAuthFlow(provider, request, route, options, state, proxyTelemetry, signal) {
     const flow = provider.auth?.flow;
     if (!flow) {
         throw new ProviderError("Auth flow is not configured", {
@@ -1407,7 +1413,7 @@ async function handleAuthFlow(provider, request, route, options, state, signal)
     // any flow code runs instead of at whatever point the ceremony first reads
     // the env. `abort` stays exempt: a user must always be able to cancel a
     // stranded flow even when provisioning is broken.
-    const { context, getPatch } = createAuthFlowContext(provider, request, options, state, signal);
+    const { context, getPatch } = createAuthFlowContext(provider, request, options, state, proxyTelemetry, signal);
     try {
         if (route !== "abort") {
             assertRequiredSecretsPresent(provider, context.env);
@@ -1752,20 +1758,20 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
             body.headers = { ...requestHeaders, ...body.headers };
             const response = await handleOperation(provider, body, operation, options, state, proxyTelemetry, c.req.raw.signal);
             if (response instanceof Response) {
-                logProviderSuccess(logger, provider, "operation", operation, body.requestId, response.status, finishRequestCost(requestCost));
+                logProviderSuccess(logger, provider, "operation", operation, body.requestId, response.status, finishRequestCost(requestCost), proxyTelemetry);
                 return responseWithProviderTelemetry(response, proxyTelemetry);
             }
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            logProviderSuccess(logger, provider, "operation", operation, body.requestId, 200, finishRequestCost(requestCost));
+            logProviderSuccess(logger, provider, "operation", operation, body.requestId, 200, finishRequestCost(requestCost), proxyTelemetry);
             return c.json(response);
         }
         catch (error) {
             const declaredErrorCode = declaredErrorCodeFor(error, operation, operationErrorCodes);
             const status = toStatusCode(error, declaredErrorCode);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode);
+            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode, proxyTelemetry);
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
@@ -1774,6 +1780,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
     });
     app.post("/auth/start", async (c) => {
         let rawBody;
+        const proxyTelemetry = new ProxyTelemetryCollector();
         const requestCost = startRequestCost();
         try {
             rawBody = await c.req.raw
@@ -1781,19 +1788,28 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "start", options, state, c.req.raw.signal);
-            logProviderSuccess(logger, provider, "auth", "start", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
-            return response instanceof Response ? response : c.json(response);
+            const response = await handleAuthFlow(provider, body, "start", options, state, proxyTelemetry, c.req.raw.signal);
+            logProviderSuccess(logger, provider, "auth", "start", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost), proxyTelemetry);
+            if (response instanceof Response)
+                return responseWithProviderTelemetry(response, proxyTelemetry);
+            const telemetryHeader = proxyTelemetry.toHeaderValue();
+            if (telemetryHeader)
+                c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
+            return c.json(response);
         }
         catch (error) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "auth", "start", requestId, error, status, finishRequestCost(requestCost));
+            logProviderError(logger, provider, "auth", "start", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry);
+            const telemetryHeader = proxyTelemetry.toHeaderValue();
+            if (telemetryHeader)
+                c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
             return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/continue", async (c) => {
         let rawBody;
+        const proxyTelemetry = new ProxyTelemetryCollector();
         const requestCost = startRequestCost();
         try {
             rawBody = await c.req.raw
@@ -1801,19 +1817,28 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "continue", options, state, c.req.raw.signal);
-            logProviderSuccess(logger, provider, "auth", "continue", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
-            return response instanceof Response ? response : c.json(response);
+            const response = await handleAuthFlow(provider, body, "continue", options, state, proxyTelemetry, c.req.raw.signal);
+            logProviderSuccess(logger, provider, "auth", "continue", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost), proxyTelemetry);
+            if (response instanceof Response)
+                return responseWithProviderTelemetry(response, proxyTelemetry);
+            const telemetryHeader = proxyTelemetry.toHeaderValue();
+            if (telemetryHeader)
+                c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
+            return c.json(response);
         }
         catch (error) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "auth", "continue", requestId, error, status, finishRequestCost(requestCost));
+            logProviderError(logger, provider, "auth", "continue", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry);
+            const telemetryHeader = proxyTelemetry.toHeaderValue();
+            if (telemetryHeader)
+                c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
             return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/poll", async (c) => {
         let rawBody;
+        const proxyTelemetry = new ProxyTelemetryCollector();
         const requestCost = startRequestCost();
         try {
             rawBody = await c.req.raw
@@ -1821,19 +1846,28 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "poll", options, state, c.req.raw.signal);
-            logProviderSuccess(logger, provider, "auth", "poll", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
-            return response instanceof Response ? response : c.json(response);
+            const response = await handleAuthFlow(provider, body, "poll", options, state, proxyTelemetry, c.req.raw.signal);
+            logProviderSuccess(logger, provider, "auth", "poll", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost), proxyTelemetry);
+            if (response instanceof Response)
+                return responseWithProviderTelemetry(response, proxyTelemetry);
+            const telemetryHeader = proxyTelemetry.toHeaderValue();
+            if (telemetryHeader)
+                c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
+            return c.json(response);
         }
         catch (error) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "auth", "poll", requestId, error, status, finishRequestCost(requestCost));
+            logProviderError(logger, provider, "auth", "poll", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry);
+            const telemetryHeader = proxyTelemetry.toHeaderValue();
+            if (telemetryHeader)
+                c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
             return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/refresh", async (c) => {
         let rawBody;
+        const proxyTelemetry = new ProxyTelemetryCollector();
         const requestCost = startRequestCost();
         try {
             rawBody = await c.req.raw
@@ -1841,19 +1875,28 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "refresh", options, state, c.req.raw.signal);
-            logProviderSuccess(logger, provider, "auth", "refresh", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
-            return response instanceof Response ? response : c.json(response);
+            const response = await handleAuthFlow(provider, body, "refresh", options, state, proxyTelemetry, c.req.raw.signal);
+            logProviderSuccess(logger, provider, "auth", "refresh", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost), proxyTelemetry);
+            if (response instanceof Response)
+                return responseWithProviderTelemetry(response, proxyTelemetry);
+            const telemetryHeader = proxyTelemetry.toHeaderValue();
+            if (telemetryHeader)
+                c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
+            return c.json(response);
         }
         catch (error) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "auth", "refresh", requestId, error, status, finishRequestCost(requestCost));
+            logProviderError(logger, provider, "auth", "refresh", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry);
+            const telemetryHeader = proxyTelemetry.toHeaderValue();
+            if (telemetryHeader)
+                c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
             return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });
     app.post("/auth/disconnect", async (c) => {
         let rawBody;
+        const proxyTelemetry = new ProxyTelemetryCollector();
         const requestCost = startRequestCost();
         try {
             rawBody = await c.req.raw
@@ -1861,14 +1904,22 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "abort", options, state, c.req.raw.signal);
-            logProviderSuccess(logger, provider, "auth", "disconnect", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
-            return response instanceof Response ? response : c.json(response);
+            const response = await handleAuthFlow(provider, body, "abort", options, state, proxyTelemetry, c.req.raw.signal);
+            logProviderSuccess(logger, provider, "auth", "disconnect", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost), proxyTelemetry);
+            if (response instanceof Response)
+                return responseWithProviderTelemetry(response, proxyTelemetry);
+            const telemetryHeader = proxyTelemetry.toHeaderValue();
+            if (telemetryHeader)
+                c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
+            return c.json(response);
         }
         catch (error) {
             const status = toStatusCode(error);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "auth", "disconnect", requestId, error, status, finishRequestCost(requestCost));
+            logProviderError(logger, provider, "auth", "disconnect", requestId, error, status, finishRequestCost(requestCost), undefined, proxyTelemetry);
+            const telemetryHeader = proxyTelemetry.toHeaderValue();
+            if (telemetryHeader)
+                c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
             return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
         }
     });

package/dist/server/types.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 export declare const ConnectionModeSchema: z.ZodEnum<{
-    none: "none";
     credentials: "credentials";
+    none: "none";
     oauth2: "oauth2";
     "platform-managed": "platform-managed";
     oauth2_proxied: "oauth2_proxied";
@@ -9,8 +9,8 @@ export declare const ConnectionModeSchema: z.ZodEnum<{
 export declare const OperationConnectionSchema: z.ZodObject<{
     id: z.ZodString;
     mode: z.ZodEnum<{
-        none: "none";
         credentials: "credentials";
+        none: "none";
         oauth2: "oauth2";
         "platform-managed": "platform-managed";
         oauth2_proxied: "oauth2_proxied";
@@ -27,8 +27,8 @@ export declare const OperationRequestSchema: z.ZodObject<{
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
-            none: "none";
             credentials: "credentials";
+            none: "none";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
             oauth2_proxied: "oauth2_proxied";
@@ -118,8 +118,8 @@ export declare const AuthFlowRequestSchema: z.ZodObject<{
     connection: z.ZodOptional<z.ZodObject<{
         id: z.ZodString;
         mode: z.ZodEnum<{
-            none: "none";
             credentials: "credentials";
+            none: "none";
             oauth2: "oauth2";
             "platform-managed": "platform-managed";
             oauth2_proxied: "oauth2_proxied";

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type ms from "ms";
+import type { HealthScenario } from "./health-scenario.js";
 import type { SerializedCookieJar } from "tough-cookie";
 import type { infer as ZodInfer, ZodType } from "zod";
 /** Minimal Standard Schema v1 shape accepted by provider operations. */
@@ -549,7 +550,7 @@ export interface HealthJourneyRunResult {
     label?: string;
     metadata?: Record<string, unknown>;
 }
-export interface HealthJourneyDefinition {
+interface HealthJourneyDefinitionBase {
     id: string;
     title?: string;
     description?: string;
@@ -561,14 +562,14 @@ export interface HealthJourneyDefinition {
     requiredSecrets?: readonly string[];
     manualTrigger?: HealthJourneyManualTriggerPolicy;
     steps: readonly [HealthJourneyStep, ...HealthJourneyStep[]];
-    /**
-     * Required: a journey always declares `coversOperations`, and the health
-     * monitor reports a run-less journey as `journey_run_missing`. Declaration
-     * validation rejects a missing `run` (`health-journey-executable`), so this
-     * is typed required to fail at compile time rather than at boot.
-     */
-    run: (ctx: HealthJourneyRunContext) => Promise<HealthJourneyRunResult | undefined>;
 }
+export type HealthJourneyDefinition = HealthJourneyDefinitionBase & ({
+    run: (ctx: HealthJourneyRunContext) => Promise<HealthJourneyRunResult | undefined>;
+    scenario?: never;
+} | {
+    scenario: HealthScenario;
+    run?: never;
+});
 /**
  * Health-check authoring surface owned by `@apifuse/provider-sdk`.
  *
@@ -2051,3 +2052,4 @@ export interface ProviderDefinition {
     healthProbe?: ProviderHealthProbeConfig;
     healthJourneys?: readonly HealthJourneyDefinition[];
 }
+export {};

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.37",
+	"version": "2.2.0-beta.39",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",