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

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 {
@@ -38,6 +41,80 @@ export {
 	type ProviderContextOf,
 	type ProviderDeclaration,
 } from "./define.js";
+export {
+	AssertionExpressionSchema,
+	AssertionPredicateSchema,
+	AssertStepSchema,
+	BoundedJsonPathSchema,
+	CandidateBlockSchema,
+	CandidatePolicySchema,
+	CredentialRefDeclarationSchema,
+	defineHealthScenario,
+	HealthScenarioSchema,
+	HealthStepSchema,
+	ExtractStepSchema,
+	FindFirstSchema,
+	GuardStepSchema,
+	JournalPolicySchema,
+	JsonTemplateSchema,
+	ManualTriggerPolicySchema,
+	OperandSchema,
+	OperationStepSchema,
+	QuantifierSchema,
+	ReferenceSchema,
+	RetryPolicySchema,
+	SafeRegexSchema,
+	ScopedAssertionExpressionSchema,
+	ScopedAssertionPredicateSchema,
+	ScopedItemReferenceSchema,
+	ScopedOperandSchema,
+	StepReferenceSchema,
+	RelativeDateNodeSchema,
+	ValueTypeSchema,
+} from "./health-scenario.js";
+export type {
+	AssertionExpression,
+	AssertionPredicate,
+	AttemptReference,
+	AssertResult,
+	AssertStep,
+	BoundedJsonPath,
+	CandidateBlock,
+	CandidatePolicy,
+	CandidateReference,
+	CredentialReference,
+	CredentialRefDeclaration,
+	EstablishedConnectionReference,
+	ExtractStep,
+	FindFirst,
+	GuardAttribution,
+	GuardReasonCode,
+	GuardResult,
+	GuardStep,
+	HealthScenario,
+	HealthStep,
+	JsonTemplate,
+	JournalPolicy,
+	ManualTriggerPolicy,
+	NonEmpty,
+	OperationResult,
+	OperationStep,
+	Operand,
+	Quantifier,
+	ReferenceNode,
+	Reference,
+	RelativeDateNode,
+	RetryPolicy,
+	SafeRegex,
+	ScopedAssertionExpression,
+	ScopedAssertionPredicate,
+	ScopedItemReference,
+	ScopedOperand,
+	StepBase,
+	StepReference,
+	ExtractResult,
+	ValueType,
+} from "./health-scenario.js";
 export type { DevServerOptions } from "./dev.js";
 export { createDevServer, startDevServer } from "./dev.js";
 export * from "./errors.js";
@@ -100,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/provider.ts

@@ -40,6 +40,81 @@ export type {
 	ProviderContextOf,
 	ProviderDeclaration,
 } from "./define.js";
+export type { JsonPrimitive, JsonValue } from "./contract-json.js";
+export {
+	AssertionExpressionSchema,
+	AssertionPredicateSchema,
+	AssertStepSchema,
+	BoundedJsonPathSchema,
+	CandidateBlockSchema,
+	CandidatePolicySchema,
+	CredentialRefDeclarationSchema,
+	defineHealthScenario,
+	HealthScenarioSchema,
+	HealthStepSchema,
+	ExtractStepSchema,
+	FindFirstSchema,
+	GuardStepSchema,
+	JournalPolicySchema,
+	JsonTemplateSchema,
+	ManualTriggerPolicySchema,
+	OperandSchema,
+	OperationStepSchema,
+	QuantifierSchema,
+	ReferenceSchema,
+	RetryPolicySchema,
+	SafeRegexSchema,
+	ScopedAssertionExpressionSchema,
+	ScopedAssertionPredicateSchema,
+	ScopedItemReferenceSchema,
+	ScopedOperandSchema,
+	StepReferenceSchema,
+	RelativeDateNodeSchema,
+	ValueTypeSchema,
+} from "./health-scenario.js";
+export type {
+	AssertionExpression,
+	AssertionPredicate,
+	AttemptReference,
+	AssertResult,
+	AssertStep,
+	BoundedJsonPath,
+	CandidateBlock,
+	CandidatePolicy,
+	CandidateReference,
+	CredentialReference,
+	CredentialRefDeclaration,
+	EstablishedConnectionReference,
+	ExtractStep,
+	FindFirst,
+	GuardAttribution,
+	GuardReasonCode,
+	GuardResult,
+	GuardStep,
+	HealthScenario,
+	HealthStep,
+	JsonTemplate,
+	JournalPolicy,
+	ManualTriggerPolicy,
+	NonEmpty,
+	OperationResult,
+	OperationStep,
+	Operand,
+	Quantifier,
+	ReferenceNode,
+	Reference,
+	RelativeDateNode,
+	RetryPolicy,
+	SafeRegex,
+	ScopedAssertionExpression,
+	ScopedAssertionPredicate,
+	ScopedItemReference,
+	ScopedOperand,
+	StepBase,
+	StepReference,
+	ExtractResult,
+	ValueType,
+} from "./health-scenario.js";
 export {
 	AuthError,
 	HttpRedirectError,

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> {

package/src/runtime/proxy-telemetry.ts

@@ -12,51 +12,49 @@ import type {
 
 export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 
-type ProviderTelemetryHeader = {
-	v: 1;
-	proxy?: {
-		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?: CompactProxyAttemptSample[];
-		/** Distinct vendors attempted across the resolution chain, in order seen. */
-		vendors?: ProxyVendorName[];
-		/** Cross-vendor failover events (bounded). */
-		failovers?: CompactVendorFailoverSample[];
-	};
+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;
+	}[];
 };
 
-type CompactProxyAttemptSample = {
-	n: number;
-	a: number;
-	i?: number;
-	h?: string;
-	o: "ok" | "error";
-	c?: string;
-	s?: number;
-	d?: number;
-};
-
-type CompactVendorFailoverSample = {
-	v: ProxyVendorName;
-	nx?: ProxyVendorName;
-	p: "resolution" | "transport";
-	r: ProxyVendorFailoverTelemetryEvent["reason"];
-	a?: number;
+type ProviderTelemetryHeader = {
+	v: 1;
+	proxy?: ProxyTelemetryLogPayload;
 };
 
 const MAX_HEADER_BYTES = 4_096;
@@ -163,7 +161,7 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		});
 	}
 
-	toHeaderValue(): string | undefined {
+	toLogPayload(): ProxyTelemetryLogPayload | undefined {
 		const [first, ...rest] = this.#events;
 		if (!first) return undefined;
 
@@ -196,62 +194,65 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			}),
 			first,
 		);
-		const payload: ProviderTelemetryHeader = {
-			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(): string | undefined {
+		const proxy = this.toLogPayload();
+		if (!proxy) return undefined;
+		const payload: ProviderTelemetryHeader = { v: 1, proxy };
 
 		const encoded = encodeBase64Url(JSON.stringify(payload));
 		if (encoded.length > MAX_HEADER_BYTES) return undefined;

package/src/server/index.ts

@@ -1,3 +1,11 @@
+export type {
+	ProxyCacheStatus,
+	ProxyProtocol,
+	ProxyUserAgentSource,
+	ProxyVendorName,
+	SmartproxyAllocatorBodyClass,
+} from "../config/loader.js";
+export type { ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
 export {
 	createServerApp,
 	createServerAppAsync,