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

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.39
+
+- Release candidate for main commit ecbe349c44e15c873b7c58b42e14610db029eb5f.
+
+## 2.2.0-beta.38
+
+- Release candidate for main commit 448775077dbc9ab907209f1feee4e6e4e5ef4283.
+
 ## 2.2.0-beta.37
 
 - Release candidate for main commit aa14b268dffe1196f25c2b6b314598fe0896edec.

package/dist/declaration-validation.d.ts

@@ -4,6 +4,8 @@ export declare const DECLARATION_INVALID_CODE = "DECLARATION_INVALID";
 export declare const DECLARATION_RULE_IDS: {
     readonly challengeShape: "credentials-challenge-shape";
     readonly journeyExecutable: "health-journey-executable";
+    readonly journeyRunScenarioExclusive: "health-journey-run-scenario-exclusive";
+    readonly journeyScenarioValid: "health-journey-scenario-valid";
     readonly schemaSerializable: "operation-schema-serializable";
     readonly proxyExplicitPolicy: "proxy-explicit-policy";
     readonly proxyVendorExclusive: "proxy-vendor-fields-exclusive";
@@ -21,3 +23,10 @@ export type DeclarationViolation = {
 export declare function declarationInvalidError(violations: readonly DeclarationViolation[]): ProviderError;
 /** Enforces declaration rules whose runtime behavior would otherwise fail open. */
 export declare function validateFailClosedDeclaration(provider: ProviderDefinition): void;
+type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "proxy">;
+type OperationDeclarationRulesInput = Pick<ProviderDefinition, "operations">;
+/** Enforces fail-closed rules that only depend on the provider declaration. */
+export declare function validateFailClosedProviderDeclaration(provider: ProviderDeclarationRulesInput): void;
+/** Enforces fail-closed rules that depend on the operation implementation. */
+export declare function validateFailClosedOperationDeclaration(provider: OperationDeclarationRulesInput): void;
+export {};

package/dist/declaration-validation.js

@@ -1,9 +1,12 @@
 import { describeSchema } from "./contract-serialization.js";
 import { ProviderError } from "./errors.js";
+import { HealthScenarioSchema } from "./health-scenario.js";
 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",
@@ -31,19 +34,64 @@ export function validateFailClosedDeclaration(provider) {
     if (violations.length > 0)
         throw declarationInvalidError(violations);
 }
+/** Enforces fail-closed rules that only depend on the provider declaration. */
+export function validateFailClosedProviderDeclaration(provider) {
+    const violations = [];
+    collectProviderDeclarationViolations(provider, violations);
+    if (violations.length > 0)
+        throw declarationInvalidError(violations);
+}
+/** Enforces fail-closed rules that depend on the operation implementation. */
+export function validateFailClosedOperationDeclaration(provider) {
+    const violations = [];
+    collectOperationDeclarationViolations(provider, violations);
+    if (violations.length > 0)
+        throw declarationInvalidError(violations);
+}
+function collectProviderDeclarationViolations(provider, violations) {
+    validateHealthDeclaration(provider, violations);
+    validateProxyDeclaration(provider, violations);
+}
+function collectOperationDeclarationViolations(provider, violations) {
+    validateSchemaDeclaration(provider, violations);
+    validateOperationDeclaration(provider, violations);
+}
 function validateHealthDeclaration(provider, violations) {
     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.
     // self-test.ts reports a gated case as status "skipped" with skipReason

package/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderContext, ProviderContextFor, ProviderOcrConfig, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types.js";
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderOcrConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types.js";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
 interface ProviderImplementationProfile {
@@ -125,7 +125,7 @@ export declare function defineHealthJourney(config: HealthJourneyDefinition): He
 /** 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 & {
+}) => Omit<ProviderDefinition, "operations"> & {
     operations: OperationMapConfig<TOperations, ProviderContextFor<TDeclaration>>;
 };
 /** Extract the declaration-derived operation context from a provider builder. */

package/dist/define.js

@@ -1,5 +1,5 @@
 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 { NativeEgressPolicyValidationError, validateNativeProviderConfig, } from "./native-egress-policy.js";
@@ -553,13 +553,12 @@ function validateProxiedOAuthAuth(auth, providerId) {
     validateProxiedOAuthParams(config.authorizeParams, "authorizeParams", providerId);
     validateProxiedOAuthParams(config.tokenParams, "tokenParams", providerId);
 }
-function validateProviderShape(config) {
+function validateProviderDeclarationShape(config) {
     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") {
@@ -629,6 +628,10 @@ function validateProviderShape(config) {
         }
     }
 }
+function validateProviderImplementationShape(config) {
+    const configRecord = config;
+    assertRequiredField(configRecord, "operations", String(config.id));
+}
 function validateProviderProxy(config) {
     const proxy = config.proxy;
     if (proxy === undefined || typeof proxy === "boolean") {
@@ -1413,6 +1416,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([
@@ -1835,6 +1839,10 @@ function validateHealthJourneys(providerId, operations, healthJourneys) {
         }
         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, `Provider "${providerId}" healthJourneys.${journey.id}.timeout`);
         if (journey.cooldown !== undefined)
@@ -1946,38 +1954,24 @@ function validateProviderDeployment(providerId, deployment) {
 }
 /** Establish a provider declaration before its operations are contextually typed. */
 export function defineProvider(declaration) {
+    validateProviderDeclaration(declaration);
     const buildProvider = (implementation) => finalizeProvider({
         ...declaration,
         ...implementation,
     });
     return buildProvider;
 }
-function finalizeProvider(config) {
-    validateProviderShape(config);
-    const operations = resolveOperationFixtureRequests(config.operations);
+function validateProviderDeclaration(config) {
+    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.`, {
             fix: "Keep healthProbe (the new name) and delete the healthMonitor block.",
         });
     validateProviderHealthMonitor(config.id, config.healthProbe ?? config.healthMonitor, config.healthProbe !== undefined ? "healthProbe" : "healthMonitor");
-    validateOperationFixtures(config.id, operations);
     validateProviderDeployment(config.id, config.deployment);
     try {
         validateNativeProviderConfig(config.native);
@@ -1997,6 +1991,25 @@ function finalizeProvider(config) {
         });
     if (config.browser && config.runtime !== "browser")
         throw new ProviderError(`Provider "${config.id}" cannot define browser config unless runtime is "browser"`, { fix: 'Set runtime: "browser" or remove the browser config' });
+    validateFailClosedProviderDeclaration(config);
+}
+function finalizeProvider(config) {
+    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 = {
         id: config.id,
         version: config.version,
@@ -2019,13 +2032,15 @@ function finalizeProvider(config) {
         credential: config.credential,
         context: config.context,
         meta: config.meta,
-        operations: operations,
+        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);
     return provider;
 }