@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.5

package/dist/define.js

@@ -1,27 +1,14 @@
 import ms from "ms";
-import { ProviderError, ValidationError } from "./errors";
-import { safeParseSchemaSync } from "./schema";
-import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types";
+import { ProviderError, ValidationError } from "./errors.js";
+import { safeParseSchemaSync } from "./schema.js";
+import { HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX, HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN, HEALTH_CHECK_TIMEOUT_MS_MAX, HEALTH_CHECK_TIMEOUT_MS_MIN, OPERATION_TIMEOUT_MS_MAX, OPERATION_TIMEOUT_MS_MIN, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
 const OPERATION_ID_REGEX = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const VALID_RUNTIMES = ["standard", "shared", "browser"];
-const VALID_AUTH_MODES = [
-    "none",
-    "platform-managed",
-    "credentials",
-    "oauth2",
-];
+const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"];
 const VALID_PROVIDER_ACCESS_VISIBILITIES = ["public", "early_access"];
-const VALID_PROVIDER_PROXY_MODES = [
-    "disabled",
-    "optional",
-    "required",
-];
-const VALID_PROVIDER_PROXY_PROVIDERS = [
-    "smartproxy",
-    "decodo",
-    "custom",
-];
+const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"];
+const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "decodo", "custom"];
 const VALID_PROVIDER_PROXY_AFFINITIES = [
     "request",
     "operation",
@@ -32,23 +19,9 @@ const VALID_PROVIDER_STT_MODES = ["optional", "required"];
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
 const MCP_TOOL_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
-const VALID_OPERATION_RISK_CLASSES = [
-    "read",
-    "write",
-    "destructive",
-    "external-send",
-];
-const VALID_OPERATION_APPROVAL_POLICIES = [
-    "never",
-    "risk-based",
-    "always",
-];
-const VALID_OPERATION_TRANSPORT_KINDS = [
-    "json",
-    "sse",
-    "http-stream",
-    "websocket",
-];
+const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"];
+const VALID_OPERATION_APPROVAL_POLICIES = ["never", "risk-based", "always"];
+const VALID_OPERATION_TRANSPORT_KINDS = ["json", "sse", "http-stream", "websocket"];
 const SSE_EVENT_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
 const WEBSOCKET_SUBPROTOCOL_REGEX = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 const MS_DURATION_PATTERN = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))\s*([a-zA-Z]+)?$/;
@@ -109,10 +82,7 @@ function validateProviderShape(config) {
     if (typeof config.runtime === "string")
         assertLiteralField(config.runtime, "runtime", VALID_RUNTIMES, String(config.id));
     const auth = config.auth;
-    if (auth &&
-        typeof auth === "object" &&
-        "mode" in auth &&
-        typeof auth.mode === "string")
+    if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
         assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
     if (auth && typeof auth === "object" && "exchange" in auth) {
         throw new ProviderError(`Provider "${String(config.id)}" auth.exchange is not part of the Provider SDK auth contract`, {
@@ -173,9 +143,7 @@ function validateProviderProxy(config) {
         assertLiteralField(proxy.provider, "proxy.provider", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
     }
     if (proxy.geo !== undefined) {
-        if (!proxy.geo ||
-            typeof proxy.geo !== "object" ||
-            Array.isArray(proxy.geo)) {
+        if (!proxy.geo || typeof proxy.geo !== "object" || Array.isArray(proxy.geo)) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.geo: must be an object.`, {
                 fix: `Use proxy.geo: { country: "KR" } with ISO alpha-2 country codes.`,
             });
@@ -192,9 +160,7 @@ function validateProviderProxy(config) {
         }
     }
     if (proxy.session !== undefined) {
-        if (!proxy.session ||
-            typeof proxy.session !== "object" ||
-            Array.isArray(proxy.session)) {
+        if (!proxy.session || typeof proxy.session !== "object" || Array.isArray(proxy.session)) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.session: must be an object.`, {
                 fix: `Use proxy.session: { affinity: "connection", lifetimeMinutes: 30 }.`,
             });
@@ -204,13 +170,11 @@ function validateProviderProxy(config) {
             assertLiteralField(proxy.session.affinity, "proxy.session.affinity", VALID_PROVIDER_PROXY_AFFINITIES, config.id);
         }
         const lifetime = proxy.session.lifetimeMinutes;
-        if (lifetime !== undefined &&
-            (!Number.isFinite(lifetime) || lifetime <= 0)) {
+        if (lifetime !== undefined && (!Number.isFinite(lifetime) || lifetime <= 0)) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.session.lifetimeMinutes: must be a positive number of minutes.`);
         }
         const poolSize = proxy.session.poolSize;
-        if (poolSize !== undefined &&
-            (!Number.isInteger(poolSize) || poolSize <= 0)) {
+        if (poolSize !== undefined && (!Number.isInteger(poolSize) || poolSize <= 0)) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.session.poolSize: must be a positive integer.`);
         }
     }
@@ -228,7 +192,9 @@ function validateProviderStt(config) {
     if (stt === undefined)
         return;
     if (!stt || typeof stt !== "object" || Array.isArray(stt)) {
-        throw new ValidationError(`Provider "${config.id}" has invalid stt: must be an object.`, { fix: `Use stt: { mode: "required" } or stt: { mode: "optional" }.` });
+        throw new ValidationError(`Provider "${config.id}" has invalid stt: must be an object.`, {
+            fix: `Use stt: { mode: "required" } or stt: { mode: "optional" }.`,
+        });
     }
     rejectUnknownFields(stt, new Set(["mode"]), "stt");
     assertLiteralField(stt.mode, "stt.mode", VALID_PROVIDER_STT_MODES, config.id);
@@ -247,12 +213,7 @@ function validateOperationIds(providerId, operations) {
 }
 const OPERATION_CONTRACT_VERSION_REGEX = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
 const OPERATION_SENSITIVE_PATH_REGEX = /^(?:[A-Za-z0-9_$-]+|\*)(?:\.(?:[A-Za-z0-9_$-]+|\*))*$/;
-const VALID_OPERATION_LIFECYCLES = [
-    "stable",
-    "beta",
-    "deprecated",
-    "removed",
-];
+const VALID_OPERATION_LIFECYCLES = ["stable", "beta", "deprecated", "removed"];
 function assertNonEmptyString(value, field, providerId, operationName) {
     if (typeof value !== "string" || value.trim().length === 0) {
         throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid ${field}: must be a non-empty string.`, { fix: `Set ${field} to a non-empty customer-facing value.` });
@@ -268,8 +229,7 @@ function validateToolRouterMetadata(providerId, operations) {
                 fix: `Remove operations.${operationName}.toolRouter or provide MCP-safe metadata.`,
             });
         }
-        if (toolRouter.name !== undefined &&
-            !MCP_TOOL_NAME_REGEX.test(toolRouter.name)) {
+        if (toolRouter.name !== undefined && !MCP_TOOL_NAME_REGEX.test(toolRouter.name)) {
             throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.toolRouter.name: expected an MCP-safe name.`, {
                 fix: `Use letters, numbers, and underscores only, starting with a letter, for example "${providerId.replace(/[^A-Za-z0-9]+/g, "_")}__${operationName.replace(/[^A-Za-z0-9]+/g, "_")}".`,
             });
@@ -307,8 +267,7 @@ function validateOperationContracts(providerId, operations) {
         if (contract.lifecycle !== undefined) {
             assertLiteralField(contract.lifecycle, `operations.${operationName}.contract.lifecycle`, VALID_OPERATION_LIFECYCLES, providerId);
         }
-        if (contract.lifecycle === "deprecated" ||
-            contract.lifecycle === "removed") {
+        if (contract.lifecycle === "deprecated" || contract.lifecycle === "removed") {
             if (!contract.deprecation || typeof contract.deprecation !== "object") {
                 throw new ValidationError(`Provider "${providerId}" operation "${operationName}" is ${contract.lifecycle} but lacks operations.${operationName}.contract.deprecation metadata.`, {
                     fix: `Add announcedAt, removalAfter, and migrationGuide to operations.${operationName}.contract.deprecation.`,
@@ -333,8 +292,7 @@ function validateOperationAnnotations(providerId, operations) {
             throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an integer number of milliseconds.`, {
                 fix: `Set ${field} to an integer in [${OPERATION_TIMEOUT_MS_MIN}, ${OPERATION_TIMEOUT_MS_MAX}] (milliseconds).`,
             });
-        if (timeoutMs < OPERATION_TIMEOUT_MS_MIN ||
-            timeoutMs > OPERATION_TIMEOUT_MS_MAX)
+        if (timeoutMs < OPERATION_TIMEOUT_MS_MIN || timeoutMs > OPERATION_TIMEOUT_MS_MAX)
             throw new ValidationError(`Provider "${providerId}" has invalid ${field}: ${timeoutMs} is outside [${OPERATION_TIMEOUT_MS_MIN}, ${OPERATION_TIMEOUT_MS_MAX}] ms.`, {
                 fix: `Set ${field} to an integer in [${OPERATION_TIMEOUT_MS_MIN}, ${OPERATION_TIMEOUT_MS_MAX}] ms (the upper bound stays below the gateway/ALB ceiling).`,
             });
@@ -478,9 +436,7 @@ function validateOperationTransports(providerId, operations) {
                 assertStreamMs(maxDurationMs, `${fieldPath}.maxDurationMs`, STREAM_MAX_DURATION_MS_MIN, STREAM_MAX_DURATION_MS_MAX, "max duration");
                 assertPositiveBytes(Reflect.get(transport, "maxEventBytes"), `${fieldPath}.maxEventBytes`);
                 const resumable = Reflect.get(transport, "resumable");
-                if (resumable !== undefined &&
-                    resumable !== false &&
-                    resumable !== "last-event-id") {
+                if (resumable !== undefined && resumable !== false && resumable !== "last-event-id") {
                     throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid ${fieldPath}.resumable: expected false or "last-event-id".`, {
                         fix: `Use ${fieldPath}.resumable: "last-event-id" for SSE Last-Event-ID resume support, or false to disable resume.`,
                     });
@@ -515,8 +471,7 @@ function validateOperationTransports(providerId, operations) {
                         });
                     }
                     for (const subprotocol of subprotocols) {
-                        if (typeof subprotocol !== "string" ||
-                            !WEBSOCKET_SUBPROTOCOL_REGEX.test(subprotocol)) {
+                        if (typeof subprotocol !== "string" || !WEBSOCKET_SUBPROTOCOL_REGEX.test(subprotocol)) {
                             throw new ValidationError(`Provider "${providerId}" operation "${operationName}" has invalid ${fieldPath}.subprotocols: each subprotocol must be an RFC token string.`, {
                                 fix: `Use values such as "apifuse.v1" without spaces or separators that are invalid for Sec-WebSocket-Protocol.`,
                             });
@@ -624,9 +579,7 @@ function assertBoundedIntegerMs(value, fieldPath, options) {
 function validateProviderHealthMonitor(providerId, healthMonitor, field = "healthMonitor") {
     if (healthMonitor === undefined)
         return;
-    if (!healthMonitor ||
-        typeof healthMonitor !== "object" ||
-        Array.isArray(healthMonitor))
+    if (!healthMonitor || typeof healthMonitor !== "object" || Array.isArray(healthMonitor))
         throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an object.`, {
             fix: `Set ${field} to { requiredSecrets?: string[]; serviceAccount?: string }`,
         });
@@ -676,9 +629,7 @@ function validateProviderHealthMonitor(providerId, healthMonitor, field = "healt
     }
     const probeOverrides = healthMonitorRecord.probeOverrides;
     if (probeOverrides !== undefined) {
-        if (!probeOverrides ||
-            typeof probeOverrides !== "object" ||
-            Array.isArray(probeOverrides))
+        if (!probeOverrides || typeof probeOverrides !== "object" || Array.isArray(probeOverrides))
             throw new ValidationError(`Provider "${providerId}" has invalid ${field}.probeOverrides: must be an object keyed by probe id.`);
         for (const [probeId, override] of Object.entries(probeOverrides)) {
             if (probeId.length === 0)
@@ -756,9 +707,7 @@ function validateHealthCheckSuite(providerId, operationName, suite) {
             fix: `Set ${fieldPath}.interval to a positive ms-style duration string.`,
         });
     if (s.schedule !== undefined) {
-        if (!s.schedule ||
-            typeof s.schedule !== "object" ||
-            Array.isArray(s.schedule)) {
+        if (!s.schedule || typeof s.schedule !== "object" || Array.isArray(s.schedule)) {
             throw new ValidationError(`Provider "${providerId}" ${fieldPath}.schedule must be an object.`);
         }
         if (Reflect.get(s.schedule, "jitter") !== undefined) {
@@ -784,8 +733,7 @@ function validateHealthCheckSuite(providerId, operationName, suite) {
             label: "degraded threshold",
         });
     }
-    if (s.requiresConnection !== undefined &&
-        typeof s.requiresConnection !== "boolean")
+    if (s.requiresConnection !== undefined && typeof s.requiresConnection !== "boolean")
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.requiresConnection must be a boolean.`);
     if (!Array.isArray(s.cases) || s.cases.length === 0)
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.cases must be a non-empty array.`, {
@@ -804,9 +752,7 @@ function validateHealthCheckSuite(providerId, operationName, suite) {
 }
 function validateHealthCheckUnsupported(providerId, operationName, unsupported) {
     const fieldPath = `operations.${operationName}.healthCheckUnsupported`;
-    if (!unsupported ||
-        typeof unsupported !== "object" ||
-        Array.isArray(unsupported))
+    if (!unsupported || typeof unsupported !== "object" || Array.isArray(unsupported))
         throw new ValidationError(`Provider "${providerId}" ${fieldPath} must be an object.`);
     rejectUnknownFields(unsupported, HEALTH_CHECK_UNSUPPORTED_FIELDS, fieldPath);
     const u = unsupported;
@@ -831,12 +777,7 @@ const HEALTH_JOURNEY_FIELDS = new Set([
     "steps",
     "run",
 ]);
-const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set([
-    "kind",
-    "interval",
-    "jitter",
-    "randomize",
-]);
+const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set(["kind", "interval", "jitter", "randomize"]);
 const HEALTH_JOURNEY_STEP_FIELDS = new Set([
     "id",
     "description",
@@ -854,10 +795,7 @@ const HEALTH_JOURNEY_MANUAL_TRIGGER_FIELDS = new Set([
     "minManualInterval",
     "publicRationale",
 ]);
-const HEALTH_JOURNEY_MANUAL_TRIGGER_DISABLED_FIELDS = new Set([
-    "enabled",
-    "reason",
-]);
+const HEALTH_JOURNEY_MANUAL_TRIGGER_DISABLED_FIELDS = new Set(["enabled", "reason"]);
 const HEALTH_JOURNEY_MANUAL_TRIGGER_ENABLED_FIELDS = new Set([
     "enabled",
     "requiresAcknowledgement",
@@ -872,9 +810,7 @@ const HEALTH_JOURNEY_MANUAL_TRIGGER_RISKS = new Set([
 ]);
 function validateHealthJourneyManualTrigger(providerId, journeyId, manualTrigger) {
     const fieldPath = `healthJourneys.${journeyId}.manualTrigger`;
-    if (!manualTrigger ||
-        typeof manualTrigger !== "object" ||
-        Array.isArray(manualTrigger)) {
+    if (!manualTrigger || typeof manualTrigger !== "object" || Array.isArray(manualTrigger)) {
         throw new ValidationError(`Provider "${providerId}" ${fieldPath} must be an object when present.`);
     }
     rejectUnknownFields(manualTrigger, HEALTH_JOURNEY_MANUAL_TRIGGER_FIELDS, fieldPath);
@@ -897,8 +833,7 @@ function validateHealthJourneyManualTrigger(providerId, journeyId, manualTrigger
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.requiresAcknowledgement must be a boolean.`);
     }
     const risk = Reflect.get(manualTrigger, "risk");
-    if (typeof risk !== "string" ||
-        !HEALTH_JOURNEY_MANUAL_TRIGGER_RISKS.has(risk)) {
+    if (typeof risk !== "string" || !HEALTH_JOURNEY_MANUAL_TRIGGER_RISKS.has(risk)) {
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.risk must be one of read_only, writes_external_state, or sms_or_payment.`);
     }
     if (risk !== "read_only" && requiresAcknowledgement !== true) {
@@ -950,7 +885,7 @@ function isoDurationMs(value) {
     const hours = Number(/(\d+)H/.exec(value)?.[1] ?? 0);
     const minutes = Number(/(\d+)M/.exec(value)?.[1] ?? 0);
     const seconds = Number(/(\d+(?:\.\d+)?)S/.exec(value)?.[1] ?? 0);
-    return (days * 86_400_000 + hours * 3_600_000 + minutes * 60_000 + seconds * 1_000);
+    return days * 86_400_000 + hours * 3_600_000 + minutes * 60_000 + seconds * 1_000;
 }
 function scheduleRandomizationMs(randomize, fieldPath) {
     const mode = Reflect.get(randomize, "mode");
@@ -974,9 +909,7 @@ function validateScheduleRandomization(randomize, fieldPath, intervalMs) {
         throw new ValidationError(`${fieldPath} must be an object.`);
     }
     const mode = Reflect.get(randomize, "mode");
-    const allowedFields = mode === "centered"
-        ? new Set(["mode", "maxOffset"])
-        : new Set(["mode", "maxDelay"]);
+    const allowedFields = mode === "centered" ? new Set(["mode", "maxOffset"]) : new Set(["mode", "maxDelay"]);
     rejectUnknownFields(randomize, allowedFields, fieldPath);
     const offsetMs = scheduleRandomizationMs(randomize, fieldPath);
     if (offsetMs <= 0) {
@@ -1062,9 +995,7 @@ function countCapturingGroups(pattern) {
         const next = source[i + 1];
         if (next === "?" && source[i + 2] !== "<")
             continue;
-        if (next === "?" &&
-            source[i + 2] === "<" &&
-            (source[i + 3] === "=" || source[i + 3] === "!"))
+        if (next === "?" && source[i + 2] === "<" && (source[i + 3] === "=" || source[i + 3] === "!"))
             continue;
         count += 1;
     }
@@ -1142,8 +1073,7 @@ function validateSmsOtpMatcher(matcher, fieldPath) {
         throw new ValidationError(`${fieldPath}.code.pattern must be a RegExp or pattern source string.`);
     }
     const regex = pattern instanceof RegExp ? pattern : new RegExp(pattern);
-    if (countCapturingGroups(regex) !== 1 &&
-        Reflect.get(code, "capture") === undefined) {
+    if (countCapturingGroups(regex) !== 1 && Reflect.get(code, "capture") === undefined) {
         throw new ValidationError(`${fieldPath}.code.pattern must contain exactly one OTP capture or declare code.capture.`);
     }
     if (Reflect.get(code, "capture") !== undefined &&
@@ -1195,8 +1125,7 @@ function validateHealthJourneySchedule(providerId, journeyId, schedule) {
     const interval = Reflect.get(schedule, "interval");
     assertIsoDuration(interval, `Provider "${providerId}" ${fieldPath}.interval`);
     const randomize = Reflect.get(schedule, "randomize");
-    if (Reflect.get(schedule, "jitter") !== undefined &&
-        randomize !== undefined) {
+    if (Reflect.get(schedule, "jitter") !== undefined && randomize !== undefined) {
         throw new ValidationError(`Provider "${providerId}" ${fieldPath} cannot define both jitter and randomize.`);
     }
     if (Reflect.get(schedule, "jitter") !== undefined)
@@ -1226,8 +1155,7 @@ function validateHealthJourneys(providerId, operations, healthJourneys) {
             throw new ValidationError(`Provider "${providerId}" has duplicate health journey id "${journey.id}".`);
         journeyIds.add(journey.id);
         validateHealthJourneySchedule(providerId, journey.id, journey.schedule);
-        if (!Array.isArray(journey.coversOperations) ||
-            journey.coversOperations.length === 0) {
+        if (!Array.isArray(journey.coversOperations) || journey.coversOperations.length === 0) {
             throw new ValidationError(`Provider "${providerId}" healthJourneys.${journey.id}.coversOperations must be a non-empty array.`);
         }
         for (const operationId of journey.coversOperations) {
@@ -1265,8 +1193,7 @@ function validateHealthJourneys(providerId, operations, healthJourneys) {
                 throw new ValidationError(`Provider "${providerId}" ${stepPath}.id must be a kebab-case identifier.`);
             if (step.operationId !== undefined && !operations[step.operationId])
                 throw new ValidationError(`Provider "${providerId}" ${stepPath}.operationId references unknown operation "${step.operationId}".`);
-            if (step.usesSmsMatcher !== undefined &&
-                !matcherIds.has(step.usesSmsMatcher))
+            if (step.usesSmsMatcher !== undefined && !matcherIds.has(step.usesSmsMatcher))
                 throw new ValidationError(`Provider "${providerId}" ${stepPath}.usesSmsMatcher references unknown matcher "${step.usesSmsMatcher}".`);
         }
         if (journey.manualTrigger !== undefined)
@@ -1300,9 +1227,7 @@ function validateOperationHealthChecks(providerId, operations, journeyCoveredOpe
             validateHealthCheckSuite(providerId, operationName, operation.healthCheck);
         if (hasUnsupported)
             validateHealthCheckUnsupported(providerId, operationName, operation.healthCheckUnsupported);
-        if (!hasCheck &&
-            !hasUnsupported &&
-            !journeyCoveredOperations.has(operationName))
+        if (!hasCheck && !hasUnsupported && !journeyCoveredOperations.has(operationName))
             throw new ValidationError(`Provider "${providerId}" operation "${operationName}" declares neither healthCheck nor healthCheckUnsupported.`, {
                 fix: `Add \`healthCheck: { interval, cases: [...] }\` or \`healthCheckUnsupported: { reason: "..." }\` to operations.${operationName}.`,
             });
@@ -1332,6 +1257,19 @@ function validateOperationFixtures(providerId, operations) {
         }
     }
 }
+/**
+ * Shallow shape guard only: the `deployment` object is passed through
+ * verbatim and deliberately not deep-validated by the SDK — the APIFuse
+ * registry builder owns deployment validation and profile resolution.
+ */
+function validateProviderDeployment(providerId, deployment) {
+    if (deployment === undefined)
+        return;
+    if (!deployment || typeof deployment !== "object" || Array.isArray(deployment))
+        throw new ProviderError(`Provider "${providerId}" deployment must be an object when present`, {
+            fix: 'Pass deployment: { runtime: "shared" | "dedicated" | "browser", ... } or remove the field',
+        });
+}
 export function defineProvider(config) {
     validateProviderShape(config);
     if (!CONNECTOR_ID_REGEX.test(config.id))
@@ -1356,6 +1294,7 @@ export function defineProvider(config) {
         });
     validateProviderHealthMonitor(config.id, config.healthProbe ?? config.healthMonitor, config.healthProbe !== undefined ? "healthProbe" : "healthMonitor");
     validateOperationFixtures(config.id, config.operations);
+    validateProviderDeployment(config.id, config.deployment);
     validateProviderProxy(config);
     validateProviderStt(config);
     if (config.runtime === "browser" && !config.browser)
@@ -1368,6 +1307,9 @@ export function defineProvider(config) {
         id: config.id,
         version: config.version,
         runtime: config.runtime,
+        // Verbatim passthrough: deployment validation and profile resolution
+        // are owned by the APIFuse registry builder, not the SDK.
+        deployment: config.deployment,
         allowedHosts: config.allowedHosts,
         stealth: config.stealth,
         proxy: config.proxy,

package/dist/dev.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderDefinition } from "./types";
+import type { ProviderDefinition } from "./types.js";
 export interface DevServerOptions {
     port?: number;
     sessionDbPath?: string;

package/dist/dev.js

@@ -1,4 +1,4 @@
-import { serve } from "./server/serve";
+import { serve } from "./server/serve.js";
 export function createDevServer(provider, options) {
     const port = options?.port ?? 3900;
     return {

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderErrorCategory } from "./observability";
+import type { ProviderErrorCategory } from "./observability.js";
 export type ProviderErrorOptions = {
     fix?: string;
     code?: string;

package/dist/errors.js

@@ -28,9 +28,7 @@ function hasOwnBrand(value, brand, expected) {
         return false;
     }
     const descriptor = Object.getOwnPropertyDescriptor(value, brand);
-    return (descriptor !== undefined &&
-        Object.hasOwn(descriptor, "value") &&
-        descriptor.value === expected);
+    return (descriptor !== undefined && Object.hasOwn(descriptor, "value") && descriptor.value === expected);
 }
 export class ProviderError extends Error {
     options;

package/dist/i18n/catalog.d.ts

@@ -1,5 +1,5 @@
-import type { AuthTurn } from "../types";
-import { type ProviderLocale, type ProviderLocaleCatalog, type ProviderLocaleKey, type ProviderLocaleValue } from "./keys";
+import type { AuthTurn } from "../types.js";
+import { type ProviderLocale, type ProviderLocaleCatalog, type ProviderLocaleKey, type ProviderLocaleValue } from "./keys.js";
 export type ProviderLocaleCatalogMap = Record<ProviderLocale, ProviderLocaleCatalog>;
 export interface LoadProviderLocaleCatalogsOptions {
     providerDir: string;

package/dist/i18n/catalog.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { getProviderLocalePath, isProviderLocaleValue, providerLocaleKey, } from "./keys";
+import { getProviderLocalePath, isProviderLocaleValue, providerLocaleKey, } from "./keys.js";
 export function loadProviderLocaleCatalogs(options) {
     const catalogs = {};
     for (const locale of options.locales) {
@@ -26,9 +26,7 @@ function isStringRecord(value) {
 function localizeAuthInputSchema(expectedInput, options) {
     if (!expectedInput)
         return undefined;
-    const schema = isRecord(expectedInput.schema)
-        ? expectedInput.schema
-        : expectedInput;
+    const schema = isRecord(expectedInput.schema) ? expectedInput.schema : expectedInput;
     const localizedSchema = localizeAuthSchemaObject(schema, options);
     if (localizedSchema === schema)
         return undefined;
@@ -40,9 +38,7 @@ function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
 function localizeAuthSchemaObject(schema, options) {
-    const properties = isRecord(schema.properties)
-        ? schema.properties
-        : undefined;
+    const properties = isRecord(schema.properties) ? schema.properties : undefined;
     if (!properties)
         return schema;
     let changed = false;
@@ -50,9 +46,7 @@ function localizeAuthSchemaObject(schema, options) {
         if (!isRecord(property))
             return [fieldName, property];
         const nameKey = typeof property.nameKey === "string" ? property.nameKey : undefined;
-        const descriptionKey = typeof property.descriptionKey === "string"
-            ? property.descriptionKey
-            : undefined;
+        const descriptionKey = typeof property.descriptionKey === "string" ? property.descriptionKey : undefined;
         const title = nameKey
             ? asStringValue(resolveProviderLocaleValue(options.catalogs, nameKey, options.locale, options.fallbackLocale))
             : undefined;

package/dist/i18n/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./catalog";
-export * from "./keys";
+export * from "./catalog.js";
+export * from "./keys.js";

package/dist/i18n/index.js

@@ -1,2 +1,2 @@
-export * from "./catalog";
-export * from "./keys";
+export * from "./catalog.js";
+export * from "./keys.js";

package/dist/i18n/keys.d.ts

@@ -1,5 +1,5 @@
-import type { ProviderLocaleKey } from "../types";
-export type { ProviderLocale, ProviderLocaleKey } from "../types";
+import type { ProviderLocaleKey } from "../types.js";
+export type { ProviderLocale, ProviderLocaleKey } from "../types.js";
 export declare function providerLocaleKey(key: string): ProviderLocaleKey;
 export declare function isProviderLocaleKey(value: unknown): value is ProviderLocaleKey;
 export declare function assertProviderLocaleKey(value: unknown): asserts value is ProviderLocaleKey;

package/dist/index.d.ts

@@ -1,42 +1,43 @@
-export * from "./auth";
-export * from "./ceremonies";
-export * from "./choice-token";
-export type { ApiFuseConfig, BrowserConfig, ProxyConfig, SessionConfig, } from "./config/loader";
-export { defineConfig, loadApiFuseConfig } from "./config/loader";
-export { canonicalJson, digestProviderContract, extractProviderContract, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, } from "./contract";
-export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type ProviderConfig, } from "./define";
-export type { DevServerOptions } from "./dev";
-export { createDevServer, startDevServer } from "./dev";
-export * from "./errors";
-export * from "./i18n";
-export { type LintDiagnostic, lintOperation, lintProvider, } from "./lint";
-export * from "./recipes/gov-api";
-export * from "./recipes/rest-api";
-export { createFlowContext, createScratchpad } from "./runtime/auth-flow";
-export type { BrowserClientOptions } from "./runtime/browser";
-export { BrowserClient, createBrowserClient } from "./runtime/browser";
-export { createBypassProviderCache, createProviderCache, type ProviderCacheOptions, resetProviderCacheForTests, } from "./runtime/cache";
-export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice";
-export { type CreateCredentialContextOptions, createCredentialContext, } from "./runtime/credential";
-export { createEnvContext } from "./runtime/env";
-export { executeOperation } from "./runtime/executor";
-export { createHttpClient } from "./runtime/http";
-export type { Insight, InsightSeverity } from "./runtime/insights";
-export { generateInsights } from "./runtime/insights";
-export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } from "./runtime/instrumentation";
-export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate";
-export { getProviderBaseUrl } from "./runtime/provider";
-export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state";
-export { createStealthClient } from "./runtime/stealth";
-export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt";
-export { type CreateTraceContextOptions, createTraceContext, type Span, type TraceContext, } from "./runtime/trace";
-export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema";
-export { createServerApp, type ServeOptions, serve } from "./server";
-export { getStealthProfile, listStealthProfiles } from "./stealth/profiles";
-export * from "./stream";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types";
-export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types";
-export * from "./utils/date";
-export * from "./utils/parse";
-export * from "./utils/text";
-export * from "./utils/transform";
+export * from "./auth.js";
+export * from "./ceremonies/index.js";
+export * from "./choice-token.js";
+export type { ApiFuseConfig, BrowserConfig, ProxyConfig, SessionConfig, } from "./config/loader.js";
+export { defineConfig, loadApiFuseConfig } from "./config/loader.js";
+export { canonicalJson, digestProviderContract, extractProviderContract, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, } from "./contract.js";
+export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type ProviderConfig, } from "./define.js";
+export type { DevServerOptions } from "./dev.js";
+export { createDevServer, startDevServer } from "./dev.js";
+export * from "./errors.js";
+export * from "./user-input.js";
+export * from "./i18n/index.js";
+export { type LintDiagnostic, lintOperation, lintProvider, } from "./lint.js";
+export * from "./recipes/gov-api.js";
+export * from "./recipes/rest-api.js";
+export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
+export type { BrowserClientOptions } from "./runtime/browser.js";
+export { BrowserClient, createBrowserClient } from "./runtime/browser.js";
+export { createBypassProviderCache, createProviderCache, type ProviderCacheOptions, resetProviderCacheForTests, } from "./runtime/cache.js";
+export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice.js";
+export { type CreateCredentialContextOptions, createCredentialContext, } from "./runtime/credential.js";
+export { createEnvContext } from "./runtime/env.js";
+export { executeOperation } from "./runtime/executor.js";
+export { createHttpClient } from "./runtime/http.js";
+export type { Insight, InsightSeverity } from "./runtime/insights.js";
+export { generateInsights } from "./runtime/insights.js";
+export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } from "./runtime/instrumentation.js";
+export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate.js";
+export { getProviderBaseUrl } from "./runtime/provider.js";
+export { createUnsupportedProviderRuntimeState, UnsupportedProviderStateError, } from "./runtime/state.js";
+export { createStealthClient } from "./runtime/stealth.js";
+export { APIFUSE__STT__BACKEND_ENV, APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV, APIFUSE__STT__MODEL_ENV, createSttClientFromEnv, createUnsupportedSttClient, extractVerificationCode, resolveSttPrompt, } from "./runtime/stt.js";
+export { type CreateTraceContextOptions, createTraceContext, type Span, type TraceContext, } from "./runtime/trace.js";
+export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SENSITIVE_KIND_META_KEY, APIFUSE_SENSITIVE_META_KEY, collectSensitivePaths, describeKey, field, fields, isSensitiveSchema, redactPayload, type SensitiveFieldKind, type SensitiveFieldOptions, type SensitivePath, sensitive, z, } from "./schema.js";
+export { createServerApp, type ServeOptions, serve } from "./server/index.js";
+export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
+export * from "./stream.js";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, OperationAnnotations, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationDocMeta, OperationErrorCode, OperationHandlerResult, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, StealthClient, StealthFetchOptions, StealthPlatform, StealthProfile, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
+export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
+export * from "./utils/date.js";
+export * from "./utils/parse.js";
+export * from "./utils/text.js";
+export * from "./utils/transform.js";