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

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/package.json

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

package/src/declaration-validation.ts

@@ -59,8 +59,45 @@ export function validateFailClosedDeclaration(provider: ProviderDefinition): voi
 	if (violations.length > 0) throw declarationInvalidError(violations);
 }
 
+type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "proxy">;
+type OperationDeclarationRulesInput = Pick<ProviderDefinition, "operations">;
+
+/** Enforces fail-closed rules that only depend on the provider declaration. */
+export function validateFailClosedProviderDeclaration(
+	provider: ProviderDeclarationRulesInput,
+): void {
+	const violations: DeclarationViolation[] = [];
+	collectProviderDeclarationViolations(provider, violations);
+	if (violations.length > 0) throw declarationInvalidError(violations);
+}
+
+/** Enforces fail-closed rules that depend on the operation implementation. */
+export function validateFailClosedOperationDeclaration(
+	provider: OperationDeclarationRulesInput,
+): void {
+	const violations: DeclarationViolation[] = [];
+	collectOperationDeclarationViolations(provider, violations);
+	if (violations.length > 0) throw declarationInvalidError(violations);
+}
+
+function collectProviderDeclarationViolations(
+	provider: ProviderDeclarationRulesInput,
+	violations: DeclarationViolation[],
+): void {
+	validateHealthDeclaration(provider, violations);
+	validateProxyDeclaration(provider, violations);
+}
+
+function collectOperationDeclarationViolations(
+	provider: OperationDeclarationRulesInput,
+	violations: DeclarationViolation[],
+): void {
+	validateSchemaDeclaration(provider, violations);
+	validateOperationDeclaration(provider, violations);
+}
+
 function validateHealthDeclaration(
-	provider: ProviderDefinition,
+	provider: ProviderDeclarationRulesInput,
 	violations: DeclarationViolation[],
 ): void {
 	for (const [index, journey] of (provider.healthJourneys ?? []).entries()) {
@@ -113,7 +150,7 @@ function healthJourneyPath(journey: HealthJourneyDefinition, index: number): str
 }
 
 function validateSchemaDeclaration(
-	provider: ProviderDefinition,
+	provider: OperationDeclarationRulesInput,
 	violations: DeclarationViolation[],
 ): void {
 	for (const [operationId, operation] of Object.entries(provider.operations ?? {})) {
@@ -153,7 +190,7 @@ const MANAGED_PROXY_VENDORS = new Set<ProviderProxyProvider>(["smartproxy", "nod
 const STATIC_PROXY_VENDORS = new Set<ProviderProxyProvider>(["custom", "decodo"]);
 
 function validateProxyDeclaration(
-	provider: ProviderDefinition,
+	provider: ProviderDeclarationRulesInput,
 	violations: DeclarationViolation[],
 ): void {
 	if (provider.proxy === true) {
@@ -213,7 +250,7 @@ function declaredProxyVendors(policy: ProviderProxyPolicy): ProviderProxyProvide
 }
 
 function validateOperationDeclaration(
-	provider: ProviderDefinition,
+	provider: OperationDeclarationRulesInput,
 	violations: DeclarationViolation[],
 ): void {
 	for (const [operationId, operation] of Object.entries(provider.operations ?? {})) {

package/src/define.ts

@@ -1,6 +1,9 @@
 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 {
@@ -30,12 +33,12 @@ import type {
 	OperationWebSocketTransport,
 	ProviderAccessConfig,
 	ProviderChallengeKind,
-	ProviderDefinition,
 	ProviderContext,
 	ProviderContextFor,
-	ProviderOcrConfig,
+	ProviderDefinition,
 	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
+	ProviderOcrConfig,
 	ProviderProxyConfig,
 	ProviderProxyProvider,
 	ProviderPublicProfile,
@@ -806,13 +809,12 @@ function validateProxiedOAuthAuth(auth: Record<string, unknown>, providerId: str
 	validateProxiedOAuthParams(config.tokenParams, "tokenParams", providerId);
 }
 
-function validateProviderShape(config: unknown): void {
+function validateProviderDeclarationShape(config: unknown): void {
 	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") {
@@ -910,6 +912,11 @@ function validateProviderShape(config: unknown): void {
 	}
 }
 
+function validateProviderImplementationShape(config: { id: string }): void {
+	const configRecord = config as unknown as Record<string, unknown>;
+	assertRequiredField(configRecord, "operations", String(config.id));
+}
+
 function validateProviderProxy(config: {
 	id: string;
 	proxy?: ProviderProxyConfig;
@@ -2844,7 +2851,7 @@ export type ProviderBuilder<TDeclaration extends ProviderDeclaration> = <
 	implementation: {
 		operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
 	},
-) => ProviderDefinition & {
+) => Omit<ProviderDefinition, "operations"> & {
 	operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
 };
 
@@ -2859,6 +2866,7 @@ export function defineProvider<const TDeclaration extends ProviderDeclaration>(
 		Record<Exclude<keyof TDeclaration, keyof ProviderDeclaration>, never> &
 		AuthStartNoInputGuard<TDeclaration>,
 ): ProviderBuilder<TDeclaration> {
+	validateProviderDeclaration(declaration);
 	const buildProvider = <TOperations extends Record<string, ProviderOperation>>(
 		implementation: {
 			operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
@@ -2871,37 +2879,12 @@ export function defineProvider<const TDeclaration extends ProviderDeclaration>(
 	return buildProvider as ProviderBuilder<TDeclaration>;
 }
 
-function finalizeProvider<
-	TOperations extends Record<string, ProviderOperation>,
-	TContext,
->(
-	config: ProviderConfig<TOperations, TContext>,
-): ProviderDefinition & {
-	operations: OperationMapConfig<TOperations, TContext>;
-} {
-	validateProviderShape(config);
-	const operations = resolveOperationFixtureRequests(config.operations);
+function validateProviderDeclaration(config: ProviderDeclaration): void {
+	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.`,
@@ -2914,7 +2897,6 @@ function finalizeProvider<
 		config.healthProbe ?? config.healthMonitor,
 		config.healthProbe !== undefined ? "healthProbe" : "healthMonitor",
 	);
-	validateOperationFixtures(config.id, operations);
 	validateProviderDeployment(config.id, config.deployment);
 	try {
 		validateNativeProviderConfig(config.native);
@@ -2939,7 +2921,38 @@ function finalizeProvider<
 			`Provider "${config.id}" cannot define browser config unless runtime is "browser"`,
 			{ fix: 'Set runtime: "browser" or remove the browser config' },
 		);
-	const provider: ProviderDefinition & {
+	validateFailClosedProviderDeclaration(config);
+}
+
+function finalizeProvider<
+	TOperations extends Record<string, ProviderOperation>,
+	TContext,
+>(
+	config: ProviderConfig<TOperations, TContext>,
+): Omit<ProviderDefinition, "operations"> & {
+	operations: OperationMapConfig<TOperations, TContext>;
+} {
+	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: Omit<ProviderDefinition, "operations"> & {
 		operations: OperationMapConfig<TOperations, TContext>;
 	} = {
 		id: config.id,
@@ -2963,14 +2976,15 @@ function finalizeProvider<
 		credential: config.credential,
 		context: config.context,
 		meta: config.meta,
-		operations: operations as ProviderDefinition["operations"] &
-			OperationMapConfig<TOperations, TContext>,
+		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 as unknown as ProviderDefinition);
 	return provider;
 }

package/src/index.ts

@@ -6,12 +6,15 @@ export * from "./choice-token.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 {
@@ -174,6 +177,7 @@ export {
 } 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,

package/src/runtime/executor.ts

@@ -7,7 +7,7 @@ import {
 } from "../errors.js";
 import { z } from "zod";
 import { parseSchema } from "../schema.js";
-import type { ProviderContext, ProviderDefinition } from "../types.js";
+import type { ProviderDefinition } from "../types.js";
 import { assertRequiredSecretsPresent } from "./secrets.js";
 
 export function isStreamingOperation(provider: ProviderDefinition, operationId: string): boolean {
@@ -26,10 +26,13 @@ export function isStreamingOperation(provider: ProviderDefinition, operationId:
  *
  * @see openspec/provider-sdk/03-sdk-core.md §3.6
  */
-export async function executeOperation(
-	provider: ProviderDefinition,
-	operationId: string,
-	ctx: ProviderContext,
+export async 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> {
@@ -47,7 +50,9 @@ export async function executeOperation(
 	// 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,

package/src/runtime/instrumentation.ts

@@ -27,7 +27,10 @@ import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver-shared.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;
 };
 
@@ -850,7 +853,7 @@ function hasTraceOverrides(options: InstrumentationOptions): boolean {
 	return options.maxSpans !== undefined || options.onSpan !== undefined;
 }
 
-export function wrapWithInstrumentation<T extends ProviderContext>(
+export function wrapWithInstrumentation<T extends Pick<ProviderContext, "trace">>(
 	ctx: T,
 	options: InstrumentationOptions = {},
 ): InstrumentedProviderContext<T> {