@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.10

package/dist/contract-serialization.d.ts

@@ -1,4 +1,4 @@
-import { type JsonValue } from "./contract-json";
-import type { SchemaLike } from "./types";
+import { type JsonValue } from "./contract-json.js";
+import type { SchemaLike } from "./types.js";
 export declare function describeSchema(schema: SchemaLike): JsonValue;
 export declare function serializeSmsMatcher(value: Record<string, unknown>): Record<string, unknown>;

package/dist/contract-serialization.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { z } from "zod";
-import { canonicalJson, compactObject, isRecord, toJsonValue, } from "./contract-json";
+import { canonicalJson, compactObject, isRecord, toJsonValue, } from "./contract-json.js";
 export function describeSchema(schema) {
     if (isZodSchema(schema)) {
         const jsonSchema = zodJsonSchema(schema);
@@ -9,9 +9,7 @@ export function describeSchema(schema) {
             vendor: "zod",
             typeName: getSchemaTypeName(schema),
             jsonSchema,
-            jsonSchemaHash: jsonSchema === undefined
-                ? undefined
-                : digest(canonicalJson(jsonSchema)),
+            jsonSchemaHash: jsonSchema === undefined ? undefined : digest(canonicalJson(jsonSchema)),
         });
     }
     const standard = isRecord(schema) ? schema["~standard"] : undefined;
@@ -20,8 +18,7 @@ export function describeSchema(schema) {
             kind: "schema",
             standard: "standard-schema-v1",
             vendor: typeof standard.vendor === "string" ? standard.vendor : "unknown",
-            version: typeof standard.version === "number" ||
-                typeof standard.version === "string"
+            version: typeof standard.version === "number" || typeof standard.version === "string"
                 ? standard.version
                 : undefined,
         });

package/dist/contract-types.d.ts

@@ -1,5 +1,5 @@
-import type { JsonValue } from "./contract-json";
-import type { ProviderDefinition } from "./types";
+import type { JsonValue } from "./contract-json.js";
+import type { ProviderDefinition } from "./types.js";
 export declare const PROVIDER_CONTRACT_SCHEMA_VERSION = "2026-06-23";
 export interface ProviderContractSnapshot {
     readonly schemaVersion: typeof PROVIDER_CONTRACT_SCHEMA_VERSION;

package/dist/contract.d.ts

@@ -1,6 +1,6 @@
-import { canonicalJson, type JsonPrimitive, type JsonValue } from "./contract-json";
-import { PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot } from "./contract-types";
-import type { ProviderDefinition } from "./types";
+import { canonicalJson, type JsonPrimitive, type JsonValue } from "./contract-json.js";
+import { PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot } from "./contract-types.js";
+import type { ProviderDefinition } from "./types.js";
 export { canonicalJson, type JsonPrimitive, type JsonValue, PROVIDER_CONTRACT_SCHEMA_VERSION, type ProviderContractOperation, type ProviderContractSnapshot, };
 export declare function extractProviderContract(provider: ProviderDefinition): ProviderContractSnapshot;
 export declare function digestProviderContract(snapshot: ProviderContractSnapshot): string;

package/dist/contract.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { canonicalJson, compactObject, copyRecordWithout, toJsonValue, } from "./contract-json";
-import { describeSchema, serializeSmsMatcher } from "./contract-serialization";
-import { PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract-types";
+import { canonicalJson, compactObject, copyRecordWithout, toJsonValue, } from "./contract-json.js";
+import { describeSchema, serializeSmsMatcher } from "./contract-serialization.js";
+import { PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract-types.js";
 export { canonicalJson, PROVIDER_CONTRACT_SCHEMA_VERSION, };
 export function extractProviderContract(provider) {
     const auth = extractAuth(provider.auth);
@@ -27,9 +27,7 @@ export function extractProviderContract(provider) {
         operations: Object.entries(provider.operations)
             .sort(([leftId], [rightId]) => leftId.localeCompare(rightId))
             .map(([operationId, operation]) => extractOperation(operationId, operation)),
-        ...(provider.allowedHosts
-            ? { allowedHosts: [...provider.allowedHosts].sort() }
-            : {}),
+        ...(provider.allowedHosts ? { allowedHosts: [...provider.allowedHosts].sort() } : {}),
         ...(stealth === undefined ? {} : { stealth }),
         ...(proxy === undefined ? {} : { proxy }),
         ...(stt === undefined ? {} : { stt }),

package/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types";
+import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, 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 {
@@ -41,6 +41,13 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
     id: string;
     version: string;
     runtime: "standard" | "shared" | "browser";
+    /**
+     * Optional deployment overrides, passed through verbatim onto the returned
+     * provider definition. The SDK types this field but does not deep-validate
+     * it — the APIFuse registry builder owns deployment validation and
+     * resolves omitted fields against the runtime deployment profiles.
+     */
+    deployment?: ProviderDeploymentOverrides;
     allowedHosts?: string[];
     stealth?: {
         profile: string;

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", "nodemaven", "decodo", "custom"];
 const VALID_PROVIDER_PROXY_AFFINITIES = [
     "request",
     "operation",
@@ -30,25 +17,25 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
 ];
 const VALID_PROVIDER_STT_MODES = ["optional", "required"];
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
+const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+// Per-vendor provider-declared credential secrets. A required-mode chain must
+// declare every secret of every credentialed vendor it names, so a missing
+// credential fails at build/validation time rather than during a live outage: a
+// declared-but-uncredentialed fallback leg is a silently dead SPOF, which is
+// exactly the failure class the multi-vendor chain exists to remove. Vendors
+// absent from this map (e.g. `custom`/`decodo`, whose credentials come from the
+// `APIFUSE__PROXY__URL` bring-your-own escape hatch, not provider secrets) impose
+// no declaration requirement.
+const VENDOR_REQUIRED_SECRETS = {
+    smartproxy: [SMARTPROXY_APP_KEY_SECRET],
+    nodemaven: [NODEMAVEN_USERNAME_SECRET, NODEMAVEN_PASSWORD_SECRET],
+};
 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 +96,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`, {
@@ -167,15 +151,23 @@ function validateProviderProxy(config) {
             fix: `Use proxy: { mode: "required", provider: "smartproxy", geo: { country: "KR" }, session: { affinity: "connection", lifetimeMinutes: 30 } }`,
         });
     }
-    rejectUnknownFields(proxy, new Set(["mode", "provider", "geo", "session"]), "proxy");
+    rejectUnknownFields(proxy, new Set(["mode", "provider", "providers", "geo", "session"]), "proxy");
     assertLiteralField(proxy.mode, "proxy.mode", VALID_PROVIDER_PROXY_MODES, config.id);
     if (proxy.provider !== undefined) {
         assertLiteralField(proxy.provider, "proxy.provider", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
     }
+    if (proxy.providers !== undefined) {
+        if (!Array.isArray(proxy.providers) || proxy.providers.length === 0) {
+            throw new ValidationError(`Provider "${config.id}" has invalid proxy.providers: must be a non-empty array of proxy vendors.`, {
+                fix: `Use proxy.providers: ["smartproxy", "nodemaven"] to declare an ordered fallback chain.`,
+            });
+        }
+        for (const vendor of proxy.providers) {
+            assertLiteralField(vendor, "proxy.providers[]", 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 +184,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,31 +194,62 @@ 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.`);
         }
     }
-    if (proxy.mode === "required" && proxy.provider === "smartproxy") {
-        const hasSmartproxySecret = config.secrets?.some((secret) => secret.name === SMARTPROXY_APP_KEY_SECRET && secret.required !== false);
-        if (!hasSmartproxySecret) {
-            throw new ValidationError(`Provider "${config.id}" requires Smartproxy egress but does not declare ${SMARTPROXY_APP_KEY_SECRET}.`, {
-                fix: `Add secrets: [{ name: "${SMARTPROXY_APP_KEY_SECRET}", required: true }] to the provider.`,
-            });
+    // Every credentialed vendor in a required-mode chain must declare its
+    // provider secret(s) so a missing credential fails at build/validation time,
+    // not during a live outage. This covers the fallback legs too (not just the
+    // first vendor): a declared-but-uncredentialed nodemaven fallback would leave
+    // the chain silently down to a single vendor, reintroducing the SPOF the chain
+    // removes.
+    const vendorChain = proxy.providers && proxy.providers.length > 0
+        ? proxy.providers
+        : proxy.provider
+            ? [proxy.provider]
+            : [];
+    if (proxy.mode === "required") {
+        for (const vendor of vendorChain) {
+            const requiredSecrets = VENDOR_REQUIRED_SECRETS[vendor];
+            if (!requiredSecrets)
+                continue;
+            for (const secretName of requiredSecrets) {
+                // Match the canonical runtime gate (assertRequiredSecretsPresent /
+                // listMissingRequiredSecrets), which enforces only `required === true`
+                // declarations. A declaration that omits `required` (defaulting to
+                // optional) is skipped at runtime, so accepting it here would pass
+                // validation while leaving the credential unenforced until proxy
+                // resolution during a live request — the fail-open gap this check exists
+                // to close.
+                const declared = config.secrets?.some((secret) => secret.name === secretName && secret.required === true);
+                if (!declared) {
+                    throw new ValidationError(`Provider "${config.id}" requires ${vendor} egress but does not declare ${secretName}.`, {
+                        fix: `Add secrets: [{ name: "${secretName}", required: true }] to the provider (every vendor in a required proxy chain must declare its credential secrets).`,
+                    });
+                }
+            }
         }
     }
+    // `decodo`/`custom` are deprecated vendor values (string-union members, so the
+    // @deprecated symbol gate can't catch them — warn at validation time instead).
+    const deprecatedVendors = vendorChain.filter((vendor) => vendor === "decodo" || vendor === "custom");
+    if (deprecatedVendors.length > 0) {
+        console.warn(`[provider-sdk] Provider "${config.id}" uses deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}. Use "smartproxy"/"nodemaven", or the APIFUSE__PROXY__URL bring-your-own escape hatch.`);
+    }
 }
 function validateProviderStt(config) {
     const stt = config.stt;
     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 +268,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 +284,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 +322,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 +347,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 +491,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 +526,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 +634,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 +684,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 +762,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 +788,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 +807,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 +832,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 +850,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 +865,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 +888,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 +940,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 +964,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 +1050,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 +1128,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 +1180,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 +1210,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 +1248,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 +1282,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 +1312,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 +1349,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 +1362,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;
@@ -39,6 +39,9 @@ export declare class TransportError extends ProviderError {
     readonly upstreamStatus?: number;
     constructor(message: string, options?: TransportErrorOptions);
 }
+export declare function isProviderError(value: unknown): value is ProviderError;
+export declare function isSessionExpiredError(value: unknown): value is SessionExpiredError;
+export declare function isTransportError(value: unknown): value is TransportError;
 export declare class ProviderSecretError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);
 }