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

package/src/cli/templates/provider/index.ts.tpl

@@ -1,9 +1,9 @@
-import { defineProvider } from "@apifuse/provider-sdk/provider";
+import { defineProvider, type ProviderContextOf } from "@apifuse/provider-sdk/provider";
 
 import { providerMeta } from "./meta";
 import { operations } from "./operations";
 
-export default defineProvider({
+const buildProvider = defineProvider({
   id: "{{PROVIDER_ID}}",
   version: "1.0.0",
   runtime: "{{RUNTIME}}"{{BROWSER_BLOCK}},
@@ -11,5 +11,8 @@ export default defineProvider({
   reviewed: "community",
   {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
   meta: providerMeta,
-  operations: operations,
 });
+
+export type ProviderContext = ProviderContextOf<typeof buildProvider>;
+
+export default buildProvider({ operations });

package/src/cli/templates/provider/operations/ping.ts.tpl

@@ -1,8 +1,9 @@
 import { defineOperation } from "@apifuse/provider-sdk/provider";
+import type { ProviderContext } from "../index";
 
 import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
 
-export const pingOperation = defineOperation({
+export const pingOperation = defineOperation<ProviderContext>()({
   descriptionKey: "operations.ping.description",
   input: pingInputSchema,
   output: pingOutputSchema,

package/src/declaration-validation.ts

@@ -1,5 +1,6 @@
 import { describeSchema } from "./contract-serialization.js";
 import { ProviderError } from "./errors.js";
+import { HealthScenarioSchema } from "./health-scenario.js";
 import type {
 	HealthJourneyDefinition,
 	ProviderDefinition,
@@ -12,6 +13,8 @@ export const DECLARATION_INVALID_CODE = "DECLARATION_INVALID";
 export const DECLARATION_RULE_IDS = {
 	challengeShape: "credentials-challenge-shape",
 	journeyExecutable: "health-journey-executable",
+	journeyRunScenarioExclusive: "health-journey-run-scenario-exclusive",
+	journeyScenarioValid: "health-journey-scenario-valid",
 	schemaSerializable: "operation-schema-serializable",
 	proxyExplicitPolicy: "proxy-explicit-policy",
 	proxyVendorExclusive: "proxy-vendor-fields-exclusive",
@@ -62,15 +65,39 @@ function validateHealthDeclaration(
 ): void {
 	for (const [index, journey] of (provider.healthJourneys ?? []).entries()) {
 		if (!journey || typeof journey !== "object") continue;
-		if (typeof journey.run !== "function") {
+		const hasRun = journey.run !== undefined;
+		const hasScenario = journey.scenario !== undefined;
+		if (hasRun && hasScenario) {
+			const journeyPath = healthJourneyPath(journey, index);
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.journeyRunScenarioExclusive,
+				path: journeyPath,
+				message: "A health journey must declare exactly one of run or scenario, not both.",
+				fix: `Remove either ${journeyPath}.run or ${journeyPath}.scenario.`,
+			});
+		}
+		if (!hasRun && !hasScenario) {
 			const journeyPath = healthJourneyPath(journey, index);
 			violations.push({
 				ruleId: DECLARATION_RULE_IDS.journeyExecutable,
 				path: `${journeyPath}.run`,
-				message: "coversOperations cannot provide health coverage without executable run logic.",
-				fix: `Add an async run(ctx) implementation to ${journeyPath}.`,
+				message:
+					"coversOperations cannot provide health coverage without run or a declarative scenario.",
+				fix: `Add an async run(ctx) implementation or a valid scenario to ${journeyPath}.`,
 			});
 		}
+		if (hasScenario) {
+			const parsed = HealthScenarioSchema.safeParse(journey.scenario);
+			if (!parsed.success) {
+				const journeyPath = healthJourneyPath(journey, index);
+				violations.push({
+					ruleId: DECLARATION_RULE_IDS.journeyScenarioValid,
+					path: `${journeyPath}.scenario`,
+					message: "scenario must conform to HealthScenario.",
+					fix: "Build the scenario with defineHealthScenario().",
+				});
+			}
+		}
 	}
 
 	// NOTE: healthCheck.cases[].enabled is intentionally NOT validated here.

package/src/define.ts

@@ -31,6 +31,8 @@ import type {
 	ProviderAccessConfig,
 	ProviderChallengeKind,
 	ProviderDefinition,
+	ProviderContext,
+	ProviderContextFor,
 	ProviderOcrConfig,
 	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
@@ -197,54 +199,65 @@ function parsePositiveMsDuration(value: string): number | undefined {
 	return parsed;
 }
 
-type ProviderOperation = OperationDefinition<SchemaLike, SchemaLike>;
-type OperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationDefinition<TInput, TOutput>,
-	"handler"
-> & {
+type ProviderOperation = OperationDefinition<any, any, any>;
+type OperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationDefinition<TInput, TOutput, TContext>, "handler"> & {
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	):
 		| OperationHandlerResult<InferSchemaOutput<TOutput>>
 		| Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
 };
-type OperationMapConfig<TOperations extends Record<string, ProviderOperation>> = {
+type OperationMapConfig<
+	TOperations extends Record<string, ProviderOperation>,
+	TContext = ProviderContext,
+> = {
 	[K in keyof TOperations]: TOperations[K] extends OperationDefinition<infer TInput, infer TOutput>
-		? OperationConfig<TInput, TOutput> | OperationDefinition<TInput, TOutput>
+		? OperationConfig<TInput, TOutput, TContext> | OperationDefinition<TInput, TOutput, TContext>
 		: never;
 };
-type StreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> =
-	| SseOperationConfig<TInput, TOutput>
-	| HttpStreamOperationConfig<TInput, TOutput>
-	| WebSocketOperationConfig<TInput, TOutput>;
-type SseOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type StreamOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> =
+	| SseOperationConfig<TInput, TOutput, TContext>
+	| HttpStreamOperationConfig<TInput, TOutput, TContext>
+	| WebSocketOperationConfig<TInput, TOutput, TContext>;
+type SseOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationSseTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): AsyncIterable<ProviderStreamEvent> | Promise<AsyncIterable<ProviderStreamEvent>>;
 };
-type HttpStreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type HttpStreamOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationHttpStreamTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
-type WebSocketOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type WebSocketOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationWebSocketTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
@@ -562,7 +575,7 @@ function authStartHasHiddenInput(start: unknown): boolean {
 	return /\s=\s/.test(second);
 }
 
-export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
+export interface ProviderDeclaration {
 	id: string;
 	version: string;
 	runtime: "standard" | "shared" | "browser";
@@ -573,6 +586,8 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 	 * resolves omitted fields against the runtime deployment profiles.
 	 */
 	deployment?: ProviderDeploymentOverrides;
+	/** Declares that provider operations use the SDK HTTP client. */
+	http?: true;
 	allowedHosts?: string[];
 	native?: NativeProviderConfig;
 	stealth?: {
@@ -585,11 +600,21 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 	resolver?: ProviderResolverConfig;
 	browser?: { engine: BrowserEngine };
 	auth?: AuthConfig;
+	/** Declares that provider operations issue and consume SDK choice tokens. */
+	choice?: true;
 	reviewed?: ProviderReviewed;
 	access?: ProviderAccessConfig;
 	secrets?: ProviderSecretDeclaration[];
+	/** Declares that provider operations read SDK-managed environment values. */
+	env?: true;
 	credential?: CredentialDeclaration;
 	context?: ContextDeclaration;
+	/** Declares that provider operations use SDK-managed persistent state. */
+	state?: true;
+	/** Declares that provider operations use the SDK provider cache. */
+	cache?: true;
+	/** Declares that provider operations access runtime-resolvable files. */
+	files?: true;
 	meta: {
 		displayName: string;
 		displayNameKey?: string;
@@ -611,25 +636,35 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 			publicSchemaFieldNames?: "normalized";
 		};
 	};
-	operations: OperationMapConfig<TOperations>;
 	healthMonitor?: ProviderHealthMonitorConfig;
 	/** New name for `healthMonitor` (transitional alias); declaring both is a ValidationError. */
 	healthProbe?: ProviderHealthMonitorConfig;
 	healthJourneys?: readonly HealthJourneyDefinition[];
 }
 
-/** Define one provider operation with schema-driven handler inference. */
-export function defineOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
-	operation: OperationConfig<TInput, TOutput>,
-): OperationDefinition<TInput, TOutput> {
-	return operation;
+interface ProviderConfig<
+	TOperations extends Record<string, ProviderOperation>,
+	TContext = ProviderContext,
+> extends ProviderDeclaration {
+	operations: OperationMapConfig<TOperations, TContext>;
 }
 
-/** Define a non-JSON provider operation with explicit transport metadata. */
-export function defineStreamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
-	operation: StreamOperationConfig<TInput, TOutput>,
-): OperationDefinition<TInput, TOutput> {
-	return operation;
+/** Define one factored provider operation with schema-driven handler inference. */
+export function defineOperation<TContext>() {
+	return function operation<TInput extends SchemaLike, TOutput extends SchemaLike>(
+		config: OperationConfig<TInput, TOutput, TContext>,
+	): OperationDefinition<TInput, TOutput, TContext> {
+		return config;
+	};
+}
+
+/** Define a factored non-JSON operation with explicit transport metadata. */
+export function defineStreamOperation<TContext>() {
+	return function streamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
+		config: StreamOperationConfig<TInput, TOutput, TContext>,
+	): OperationDefinition<TInput, TOutput, TContext> {
+		return config;
+	};
 }
 
 function assertObjectConfig(value: unknown): asserts value is Record<string, unknown> {
@@ -780,6 +815,14 @@ function validateProviderShape(config: unknown): void {
 	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") {
+		throw new ValidationError(
+			`Provider "${String(config.id)}" cannot declare capability "native" with runtime "browser"`,
+			{
+				fix: 'Use runtime: "standard" or runtime: "shared", or remove the native declaration.',
+			},
+		);
+	}
 	const auth = config.auth;
 	if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
 		assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
@@ -1087,12 +1130,14 @@ function validateProviderResolver(config: { id: string; resolver?: ProviderResol
 		"resolver",
 		config.id,
 	);
-	validateResolverLiteralArray(
-		resolver.vendors,
-		"resolver.vendors",
-		VALID_PROVIDER_RESOLVER_VENDORS,
-		config.id,
-	);
+	if (resolver.vendors !== undefined) {
+		validateResolverLiteralArray(
+			resolver.vendors,
+			"resolver.vendors",
+			VALID_PROVIDER_RESOLVER_VENDORS,
+			config.id,
+		);
+	}
 	validateResolverLiteralArray(
 		resolver.kinds,
 		"resolver.kinds",
@@ -2087,6 +2132,7 @@ const HEALTH_JOURNEY_FIELDS = new Set([
 	"manualTrigger",
 	"steps",
 	"run",
+	"scenario",
 ]);
 const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set(["kind", "interval", "jitter", "randomize"]);
 const HEALTH_JOURNEY_STEP_FIELDS = new Set([
@@ -2622,6 +2668,14 @@ function validateHealthJourneys(
 		}
 		if (journey.manualTrigger !== undefined)
 			validateHealthJourneyManualTrigger(providerId, journey.id, journey.manualTrigger);
+		if (journey.scenario !== undefined && journey.smsMatchers !== undefined)
+			throw new ValidationError(
+				`Provider "${providerId}" healthJourneys.${journey.id}.smsMatchers is not allowed on declarative scenarios.`,
+			);
+		if (journey.scenario !== undefined && journey.requiredSecrets !== undefined)
+			throw new ValidationError(
+				`Provider "${providerId}" healthJourneys.${journey.id}.requiredSecrets is not allowed on declarative scenarios.`,
+			);
 		if (journey.timeout !== undefined)
 			assertIsoDuration(
 				journey.timeout,
@@ -2783,12 +2837,48 @@ function validateProviderDeployment(providerId: string, deployment: unknown): vo
 		});
 }
 
-export function defineProvider<
+/** 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 & {
+	operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+};
+
+/** Extract the declaration-derived operation context from a provider builder. */
+export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer TDeclaration>
+	? ProviderContextFor<TDeclaration>
+	: never;
+
+/** Establish a provider declaration before its operations are contextually typed. */
+export function defineProvider<const TDeclaration extends ProviderDeclaration>(
+	declaration: TDeclaration &
+		Record<Exclude<keyof TDeclaration, keyof ProviderDeclaration>, never> &
+		AuthStartNoInputGuard<TDeclaration>,
+): ProviderBuilder<TDeclaration> {
+	const buildProvider = <TOperations extends Record<string, ProviderOperation>>(
+		implementation: {
+			operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
+		},
+	) =>
+		finalizeProvider({
+			...declaration,
+			...implementation,
+		} as ProviderConfig<TOperations, ProviderContextFor<TDeclaration>>);
+	return buildProvider as ProviderBuilder<TDeclaration>;
+}
+
+function finalizeProvider<
 	TOperations extends Record<string, ProviderOperation>,
-	TConfig extends ProviderConfig<TOperations>,
+	TContext,
 >(
-	config: TConfig & AuthStartNoInputGuard<TConfig>,
-): ProviderDefinition & { operations: OperationMapConfig<TOperations> } {
+	config: ProviderConfig<TOperations, TContext>,
+): ProviderDefinition & {
+	operations: OperationMapConfig<TOperations, TContext>;
+} {
 	validateProviderShape(config);
 	const operations = resolveOperationFixtureRequests(config.operations);
 	if (!CONNECTOR_ID_REGEX.test(config.id))
@@ -2849,7 +2939,9 @@ export function defineProvider<
 			`Provider "${config.id}" cannot define browser config unless runtime is "browser"`,
 			{ fix: 'Set runtime: "browser" or remove the browser config' },
 		);
-	const provider: ProviderDefinition & { operations: OperationMapConfig<TOperations> } = {
+	const provider: ProviderDefinition & {
+		operations: OperationMapConfig<TOperations, TContext>;
+	} = {
 		id: config.id,
 		version: config.version,
 		runtime: config.runtime,
@@ -2871,7 +2963,8 @@ export function defineProvider<
 		credential: config.credential,
 		context: config.context,
 		meta: config.meta,
-		operations,
+		operations: operations as ProviderDefinition["operations"] &
+			OperationMapConfig<TOperations, TContext>,
 		// Transitional healthMonitor → healthProbe alias: mirror whichever field
 		// was declared onto both so old and new consumers keep working.
 		healthMonitor: config.healthMonitor ?? config.healthProbe,