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

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",
@@ -56,21 +59,82 @@ 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()) {
 		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.
@@ -86,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 ?? {})) {
@@ -126,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) {
@@ -186,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;
@@ -2132,6 +2139,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([
@@ -2667,6 +2675,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,
@@ -2835,7 +2851,7 @@ export type ProviderBuilder<TDeclaration extends ProviderDeclaration> = <
 	implementation: {
 		operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
 	},
-) => ProviderDefinition & {
+) => Omit<ProviderDefinition, "operations"> & {
 	operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
 };
 
@@ -2850,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>>;
@@ -2862,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.`,
@@ -2905,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);
@@ -2930,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,
@@ -2954,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;
 }