@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.2

package/dist/define.js

@@ -1,3 +1,4 @@
+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";
@@ -50,51 +51,23 @@ const VALID_OPERATION_TRANSPORT_KINDS = [
 ];
 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_UNITS = new Set([
-    "years",
-    "year",
-    "yrs",
-    "yr",
-    "y",
-    "weeks",
-    "week",
-    "w",
-    "days",
-    "day",
-    "d",
-    "hours",
-    "hour",
-    "hrs",
-    "hr",
-    "h",
-    "minutes",
-    "minute",
-    "mins",
-    "min",
-    "m",
-    "seconds",
-    "second",
-    "secs",
-    "sec",
-    "s",
-    "milliseconds",
-    "millisecond",
-    "msecs",
-    "msec",
-    "ms",
-]);
 const MS_DURATION_PATTERN = /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))\s*([a-zA-Z]+)?$/;
 function isPositiveMsDurationString(value) {
     if (typeof value !== "string")
         return false;
-    const match = value.trim().match(MS_DURATION_PATTERN);
-    if (!match)
-        return false;
-    const amount = Number(match[1]);
-    if (!Number.isFinite(amount) || amount <= 0)
-        return false;
-    const unit = match[2]?.toLowerCase();
-    return unit === undefined || MS_DURATION_UNITS.has(unit);
+    return parsePositiveMsDuration(value) !== undefined;
+}
+function msDurationMs(value) {
+    return parsePositiveMsDuration(value) ?? 0;
+}
+function parsePositiveMsDuration(value) {
+    const trimmed = value.trim();
+    if (!MS_DURATION_PATTERN.test(trimmed))
+        return undefined;
+    const parsed = ms((trimmed.startsWith("+") ? trimmed.slice(1) : trimmed));
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return undefined;
+    return parsed;
 }
 /** Define one provider operation with schema-driven handler inference. */
 export function defineOperation(operation) {
@@ -141,6 +114,11 @@ function validateProviderShape(config) {
         "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`, {
+            fix: "Use the single canonical auth interface: auth.flow. Gateway calls auth.flow.start/continue/poll/abort/refresh only and persists complete turn data.credential as-is, so put login/token/session exchange inside auth.flow.continue.",
+        });
+    }
     if (auth &&
         typeof auth === "object" &&
         "flow" in auth &&
@@ -555,6 +533,7 @@ function validateOperationTransports(providerId, operations) {
 }
 const HEALTH_CHECK_SUITE_FIELDS = new Set([
     "interval",
+    "schedule",
     "timeoutMs",
     "degradedThresholdMs",
     "cases",
@@ -642,26 +621,26 @@ function assertBoundedIntegerMs(value, fieldPath, options) {
         });
     }
 }
-function validateProviderHealthMonitor(providerId, healthMonitor) {
+function validateProviderHealthMonitor(providerId, healthMonitor, field = "healthMonitor") {
     if (healthMonitor === undefined)
         return;
     if (!healthMonitor ||
         typeof healthMonitor !== "object" ||
         Array.isArray(healthMonitor))
-        throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor: must be an object.`, {
-            fix: `Set healthMonitor to { requiredSecrets?: string[]; serviceAccount?: string }`,
+        throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an object.`, {
+            fix: `Set ${field} to { requiredSecrets?: string[]; serviceAccount?: string }`,
         });
     const healthMonitorRecord = Object.fromEntries(Object.entries(healthMonitor));
-    rejectUnknownFields(healthMonitorRecord, PROVIDER_HEALTH_MONITOR_FIELDS, "healthMonitor");
+    rejectUnknownFields(healthMonitorRecord, PROVIDER_HEALTH_MONITOR_FIELDS, field);
     if (healthMonitorRecord.defaultProbeTimeoutMs !== undefined) {
-        assertBoundedIntegerMs(healthMonitorRecord.defaultProbeTimeoutMs, `Provider "${providerId}" healthMonitor.defaultProbeTimeoutMs`, {
+        assertBoundedIntegerMs(healthMonitorRecord.defaultProbeTimeoutMs, `Provider "${providerId}" ${field}.defaultProbeTimeoutMs`, {
             min: HEALTH_CHECK_TIMEOUT_MS_MIN,
             max: HEALTH_CHECK_TIMEOUT_MS_MAX,
             label: "timeout",
         });
     }
     if (healthMonitorRecord.defaultDegradedThresholdMs !== undefined) {
-        assertBoundedIntegerMs(healthMonitorRecord.defaultDegradedThresholdMs, `Provider "${providerId}" healthMonitor.defaultDegradedThresholdMs`, {
+        assertBoundedIntegerMs(healthMonitorRecord.defaultDegradedThresholdMs, `Provider "${providerId}" ${field}.defaultDegradedThresholdMs`, {
             min: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN,
             max: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
             label: "degraded threshold",
@@ -670,10 +649,10 @@ function validateProviderHealthMonitor(providerId, healthMonitor) {
     const requiredSecrets = healthMonitorRecord.requiredSecrets;
     if (requiredSecrets !== undefined) {
         if (!Array.isArray(requiredSecrets))
-            throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.requiredSecrets: must be string[].`);
+            throw new ValidationError(`Provider "${providerId}" has invalid ${field}.requiredSecrets: must be string[].`);
         for (const [index, secret] of requiredSecrets.entries()) {
             if (typeof secret !== "string" || secret.length === 0)
-                throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.requiredSecrets[${index}]: must be a non-empty string.`);
+                throw new ValidationError(`Provider "${providerId}" has invalid ${field}.requiredSecrets[${index}]: must be a non-empty string.`);
         }
     }
     const credentialInputs = healthMonitorRecord.credentialInputs;
@@ -681,17 +660,17 @@ function validateProviderHealthMonitor(providerId, healthMonitor) {
         if (!credentialInputs ||
             typeof credentialInputs !== "object" ||
             Array.isArray(credentialInputs)) {
-            throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.credentialInputs: must be an object mapping auth input fields to env var names.`);
+            throw new ValidationError(`Provider "${providerId}" has invalid ${field}.credentialInputs: must be an object mapping auth input fields to env var names.`);
         }
-        for (const [field, envVar] of Object.entries(credentialInputs)) {
-            if (field.trim().length === 0) {
-                throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.credentialInputs key: must be a non-empty auth input field.`);
+        for (const [inputField, envVar] of Object.entries(credentialInputs)) {
+            if (inputField.trim().length === 0) {
+                throw new ValidationError(`Provider "${providerId}" has invalid ${field}.credentialInputs key: must be a non-empty auth input field.`);
             }
             if (typeof envVar !== "string" || envVar.trim().length === 0) {
-                throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.credentialInputs.${field}: must be a non-empty env var name.`);
+                throw new ValidationError(`Provider "${providerId}" has invalid ${field}.credentialInputs.${inputField}: must be a non-empty env var name.`);
             }
             if (Array.isArray(requiredSecrets) && !requiredSecrets.includes(envVar)) {
-                throw new ValidationError(`Provider "${providerId}" healthMonitor.credentialInputs.${field} references ${envVar}, which must also be listed in healthMonitor.requiredSecrets.`);
+                throw new ValidationError(`Provider "${providerId}" ${field}.credentialInputs.${inputField} references ${envVar}, which must also be listed in ${field}.requiredSecrets.`);
             }
         }
     }
@@ -700,26 +679,26 @@ function validateProviderHealthMonitor(providerId, healthMonitor) {
         if (!probeOverrides ||
             typeof probeOverrides !== "object" ||
             Array.isArray(probeOverrides))
-            throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.probeOverrides: must be an object keyed by probe id.`);
+            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)
-                throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.probeOverrides key: must be a non-empty probe id.`);
+                throw new ValidationError(`Provider "${providerId}" has invalid ${field}.probeOverrides key: must be a non-empty probe id.`);
             if (!override || typeof override !== "object" || Array.isArray(override))
-                throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.probeOverrides["${probeId}"]: must be an object.`);
+                throw new ValidationError(`Provider "${providerId}" has invalid ${field}.probeOverrides["${probeId}"]: must be an object.`);
             const overrideRecord = Object.fromEntries(Object.entries(override));
-            rejectUnknownFields(overrideRecord, PROVIDER_HEALTH_MONITOR_PROBE_OVERRIDE_FIELDS, `healthMonitor.probeOverrides["${probeId}"]`);
+            rejectUnknownFields(overrideRecord, PROVIDER_HEALTH_MONITOR_PROBE_OVERRIDE_FIELDS, `${field}.probeOverrides["${probeId}"]`);
             const interval = overrideRecord.interval;
             if (interval !== undefined && !isPositiveMsDurationString(interval))
-                throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.probeOverrides["${probeId}"].interval: must be a positive ms-style duration string such as 30s, 5m, 8h, or 1 day.`);
+                throw new ValidationError(`Provider "${providerId}" has invalid ${field}.probeOverrides["${probeId}"].interval: must be a positive ms-style duration string such as 30s, 5m, 8h, or 1 day.`);
             if (overrideRecord.timeoutMs !== undefined) {
-                assertBoundedIntegerMs(overrideRecord.timeoutMs, `Provider "${providerId}" healthMonitor.probeOverrides["${probeId}"].timeoutMs`, {
+                assertBoundedIntegerMs(overrideRecord.timeoutMs, `Provider "${providerId}" ${field}.probeOverrides["${probeId}"].timeoutMs`, {
                     min: HEALTH_CHECK_TIMEOUT_MS_MIN,
                     max: HEALTH_CHECK_TIMEOUT_MS_MAX,
                     label: "timeout",
                 });
             }
             if (overrideRecord.degradedThresholdMs !== undefined) {
-                assertBoundedIntegerMs(overrideRecord.degradedThresholdMs, `Provider "${providerId}" healthMonitor.probeOverrides["${probeId}"].degradedThresholdMs`, {
+                assertBoundedIntegerMs(overrideRecord.degradedThresholdMs, `Provider "${providerId}" ${field}.probeOverrides["${probeId}"].degradedThresholdMs`, {
                     min: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN,
                     max: HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
                     label: "degraded threshold",
@@ -730,7 +709,7 @@ function validateProviderHealthMonitor(providerId, healthMonitor) {
     const serviceAccount = healthMonitorRecord.serviceAccount;
     if (serviceAccount !== undefined &&
         (typeof serviceAccount !== "string" || serviceAccount.length === 0))
-        throw new ValidationError(`Provider "${providerId}" has invalid healthMonitor.serviceAccount: must be a non-empty string.`);
+        throw new ValidationError(`Provider "${providerId}" has invalid ${field}.serviceAccount: must be a non-empty string.`);
 }
 function validateHealthCheckCase(providerId, operationName, caseValue, caseIndex) {
     const fieldPath = `operations.${operationName}.healthCheck.cases[${caseIndex}]`;
@@ -776,6 +755,21 @@ function validateHealthCheckSuite(providerId, operationName, suite) {
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.interval must be a positive ms-style duration string such as 30s, 5m, 8h, or 1 day.`, {
             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)) {
+            throw new ValidationError(`Provider "${providerId}" ${fieldPath}.schedule must be an object.`);
+        }
+        if (Reflect.get(s.schedule, "jitter") !== undefined) {
+            throw new ValidationError(`Provider "${providerId}" ${fieldPath}.schedule.jitter is not supported for operation healthCheck schedules. Use schedule.randomize instead.`);
+        }
+        rejectUnknownFields(s.schedule, new Set(["randomize"]), `${fieldPath}.schedule`);
+        const randomize = Reflect.get(s.schedule, "randomize");
+        if (randomize !== undefined) {
+            validateScheduleRandomization(randomize, `Provider "${providerId}" ${fieldPath}.schedule.randomize`, msDurationMs(s.interval));
+        }
+    }
     if (s.timeoutMs !== undefined) {
         assertBoundedIntegerMs(s.timeoutMs, `Provider "${providerId}" ${fieldPath}.timeoutMs`, {
             min: HEALTH_CHECK_TIMEOUT_MS_MIN,
@@ -837,7 +831,12 @@ const HEALTH_JOURNEY_FIELDS = new Set([
     "steps",
     "run",
 ]);
-const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set(["kind", "interval", "jitter"]);
+const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set([
+    "kind",
+    "interval",
+    "jitter",
+    "randomize",
+]);
 const HEALTH_JOURNEY_STEP_FIELDS = new Set([
     "id",
     "description",
@@ -953,6 +952,40 @@ function isoDurationMs(value) {
     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);
 }
+function scheduleRandomizationMs(randomize, fieldPath) {
+    const mode = Reflect.get(randomize, "mode");
+    switch (mode) {
+        case "centered": {
+            const maxOffset = Reflect.get(randomize, "maxOffset");
+            assertIsoDuration(maxOffset, `${fieldPath}.maxOffset`);
+            return isoDurationMs(maxOffset);
+        }
+        case "delayed": {
+            const maxDelay = Reflect.get(randomize, "maxDelay");
+            assertIsoDuration(maxDelay, `${fieldPath}.maxDelay`);
+            return isoDurationMs(maxDelay);
+        }
+        default:
+            throw new ValidationError(`${fieldPath}.mode must be "centered" or "delayed".`);
+    }
+}
+function validateScheduleRandomization(randomize, fieldPath, intervalMs) {
+    if (!randomize || typeof randomize !== "object" || Array.isArray(randomize)) {
+        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"]);
+    rejectUnknownFields(randomize, allowedFields, fieldPath);
+    const offsetMs = scheduleRandomizationMs(randomize, fieldPath);
+    if (offsetMs <= 0) {
+        throw new ValidationError(`${fieldPath} duration must be positive.`);
+    }
+    if (offsetMs >= intervalMs) {
+        throw new ValidationError(`${fieldPath} duration must be shorter than schedule interval.`);
+    }
+}
 function assertIsoCountry(value, fieldPath) {
     if (typeof value !== "string" || !ISO_COUNTRY_RE.test(value)) {
         throw new ValidationError(`${fieldPath} must be an ISO 3166-1 alpha-2 country code for example KR.`);
@@ -962,11 +995,18 @@ function normalizeIntervalDuration(input) {
     const trimmed = input.trim();
     const shorthand = /^(\d+)(s|m|h|d)$/i.exec(trimmed);
     if (shorthand) {
-        const amount = Number(shorthand[1]);
+        const durationMs = msDurationMs(trimmed);
+        const unit = shorthand[2]?.toLowerCase();
+        const amount = unit === "s"
+            ? durationMs / 1_000
+            : unit === "m"
+                ? durationMs / 60_000
+                : unit === "h"
+                    ? durationMs / 3_600_000
+                    : durationMs / 86_400_000;
         if (!Number.isInteger(amount) || amount <= 0) {
             throw new ValidationError(`Journey schedule interval must be a positive duration.`);
         }
-        const unit = shorthand[2]?.toLowerCase();
         if (unit === "s")
             return `PT${amount}S`;
         if (unit === "m")
@@ -980,15 +1020,27 @@ function normalizeIntervalDuration(input) {
     return trimmed;
 }
 export function every(interval, options = {}) {
+    if (options.jitter !== undefined && options.randomize !== undefined) {
+        throw new ValidationError(`Schedule cannot define both jitter and randomize. Use randomize instead.`);
+    }
     const schedule = {
         kind: "interval",
         interval: normalizeIntervalDuration(interval),
     };
+    if (options.randomize !== undefined) {
+        schedule.randomize = options.randomize;
+    }
     if (options.jitter !== undefined) {
         schedule.jitter = normalizeIntervalDuration(options.jitter);
     }
     return schedule;
 }
+export function centered(maxOffset) {
+    return { mode: "centered", maxOffset: normalizeIntervalDuration(maxOffset) };
+}
+export function delayed(maxDelay) {
+    return { mode: "delayed", maxDelay: normalizeIntervalDuration(maxDelay) };
+}
 function countCapturingGroups(pattern) {
     let count = 0;
     const source = pattern.source;
@@ -1140,9 +1192,18 @@ function validateHealthJourneySchedule(providerId, journeyId, schedule) {
     rejectUnknownFields(schedule, HEALTH_JOURNEY_SCHEDULE_FIELDS, fieldPath);
     if (Reflect.get(schedule, "kind") !== "interval")
         throw new ValidationError(`Provider "${providerId}" ${fieldPath}.kind must be "interval".`);
-    assertIsoDuration(Reflect.get(schedule, "interval"), `Provider "${providerId}" ${fieldPath}.interval`);
+    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) {
+        throw new ValidationError(`Provider "${providerId}" ${fieldPath} cannot define both jitter and randomize.`);
+    }
     if (Reflect.get(schedule, "jitter") !== undefined)
         assertIsoDuration(Reflect.get(schedule, "jitter"), `Provider "${providerId}" ${fieldPath}.jitter`);
+    if (randomize !== undefined) {
+        validateScheduleRandomization(randomize, `Provider "${providerId}" ${fieldPath}.randomize`, isoDurationMs(interval));
+    }
 }
 function validateHealthJourneys(providerId, operations, healthJourneys) {
     const covered = new Set();
@@ -1278,7 +1339,9 @@ export function defineProvider(config) {
             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" });
+        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);
@@ -1287,7 +1350,11 @@ export function defineProvider(config) {
     validateToolRouterMetadata(config.id, config.operations);
     const journeyCoveredOperations = validateHealthJourneys(config.id, config.operations, config.healthJourneys);
     validateOperationHealthChecks(config.id, config.operations, journeyCoveredOperations);
-    validateProviderHealthMonitor(config.id, config.healthMonitor);
+    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, config.operations);
     validateProviderProxy(config);
     validateProviderStt(config);
@@ -1314,7 +1381,10 @@ export function defineProvider(config) {
         context: config.context,
         meta: config.meta,
         operations: config.operations,
-        healthMonitor: config.healthMonitor,
+        // 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,
     };
 }

package/dist/index.d.ts

@@ -1,9 +1,10 @@
+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 { defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, type ProviderConfig, } from "./define";
+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";
@@ -33,7 +34,7 @@ export { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_REDACTION_MARKER, APIFUSE_SEN
 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, ConnectionMode, ContextDeclaration, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, 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, 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, StealthResponse, StealthSession, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types";
+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";

package/dist/index.js

@@ -1,9 +1,10 @@
 // @apifuse/provider-sdk
+export * from "./auth";
 export * from "./ceremonies";
 export * from "./choice-token";
 export { defineConfig, loadApiFuseConfig } from "./config/loader";
 export { canonicalJson, digestProviderContract, extractProviderContract, PROVIDER_CONTRACT_SCHEMA_VERSION, } from "./contract";
-export { defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, } from "./define";
+export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, defineStreamOperation, every, } from "./define";
 export { createDevServer, startDevServer } from "./dev";
 export * from "./errors";
 export * from "./i18n";

package/dist/lint.d.ts

@@ -8,6 +8,7 @@ type ProviderAuthLike = {
         abort?: unknown;
         refresh?: unknown;
     };
+    exchange?: unknown;
 };
 type ProviderContractMetaLike = {
     publicSchemaFieldNames?: "normalized";

package/dist/lint.js

@@ -1,5 +1,6 @@
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY, } from "./schema";
+const AUTH_OPERATION_ID_PATTERN = /^(?:auth[-_])?(?:login|exchange|continue|refresh|callback)(?:[-_]|$)/i;
 function lintAllowedHosts(providerId, allowedHosts) {
     const prefix = providerId ? `Provider "${providerId}"` : "Provider";
     if (!allowedHosts) {
@@ -49,6 +50,9 @@ function lintReviewed(providerId, reviewed) {
         },
     ];
 }
+function isProviderAuthLike(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
 function hasReusableSecretKeys(keys) {
     if (!keys) {
         return false;
@@ -99,6 +103,14 @@ function lintAuthModel(provider) {
             message: `${providerLabel} must define auth.flow.continue for ${authMode} auth mode.`,
         });
     }
+    if (isProviderAuthLike(provider.auth) && "exchange" in provider.auth) {
+        diagnostics.push({
+            rule: "auth-exchange-unsupported",
+            level: "error",
+            field: "auth.exchange",
+            message: `${providerLabel} must not define auth.exchange. The Provider SDK has one auth interface: auth.flow. Gateway only calls auth.flow.start/continue/poll/abort/refresh and persists complete turn data.credential as-is; put login/token/session exchange inside auth.flow.continue.`,
+        });
+    }
     if (authMode === "credentials" && credentialKeys.length === 0) {
         diagnostics.push({
             rule: "credential-keys-required-when-credentials-mode",
@@ -673,6 +685,21 @@ export function lintProvider(provider, options = {}) {
         ...lintPlaywrightDirectImports(provider),
         ...lintSelfHostedBrowserPatterns(provider, options),
     ];
+    if (provider.operations) {
+        const authMode = provider.auth?.mode;
+        if (authMode === "credentials" || authMode === "oauth2") {
+            for (const operationKey of Object.keys(provider.operations)) {
+                if (AUTH_OPERATION_ID_PATTERN.test(operationKey)) {
+                    diagnostics.push({
+                        rule: "auth-operation-unsupported",
+                        level: "error",
+                        field: `operations.${operationKey}`,
+                        message: `Provider "${provider.id ?? "unknown"}" operation "${operationKey}" looks like a login/token/session exchange endpoint. Authenticated providers must expose login through the single auth.flow interface because Gateway persists only auth.flow complete turn data.credential as the connection credential. Move this logic into auth.flow.continue instead of a provider operation.`,
+                    });
+                }
+            }
+        }
+    }
     if (!provider.operations) {
         return diagnostics;
     }

package/dist/provider.d.ts

@@ -1,9 +1,11 @@
+export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, defineCredentialsAuth, } from "./auth";
+export type { CredentialsAuthChallengeDefinition, CredentialsAuthChallengeRequest, CredentialsAuthCompleteResult, CredentialsAuthCredential, CredentialsAuthField, CredentialsAuthFields, CredentialsAuthFieldType, CredentialsAuthInput, CredentialsAuthLoginResult, DefineCredentialsAuthOptions, DefinedCredentialsAuth, } from "./auth";
 export { createFormCeremony } from "./ceremonies";
 export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, type ProviderChoiceTokenErrorReason, type ProviderChoiceTokenPayload, parseProviderChoiceToken, } from "./choice-token";
-export { defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define";
+export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define";
 export { AuthError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n";
 export { type CreateProviderChoiceContextOptions, createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice";
 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 type { AuthMode, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types";
+export type { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, FlowContext, HealthCheckAssertionContext, HealthCheckCase, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthScheduleRandomization, HttpRetryOptions, HttpRetrySummary, InferSchemaOutput, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDocMeta, OperationErrorCode, OperationInputExample, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationToolRouterMetadata, OperationTransport, ProviderAccessVisibility, ProviderChoiceBindingOptions, ProviderChoiceContext, ProviderChoiceIssueOptions, ProviderChoiceParseOptions, ProviderContext, ProviderDefinition, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderProxyPolicy, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderRuntimeState, ProviderStateDurationString, ProviderStateNamespace, ProviderSupportLevel, SchemaLike, SmsOtpMatcherDefinition, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateValue, StateWriteOptions, } from "./types";
 export { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "./types";

package/dist/provider.js

@@ -1,6 +1,7 @@
+export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, defineCredentialsAuth, } from "./auth";
 export { createFormCeremony } from "./ceremonies";
 export { assertFreshProviderChoiceIssuedAt, createProviderChoiceToken, ProviderChoiceTokenError, parseProviderChoiceToken, } from "./choice-token";
-export { defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define";
+export { centered, delayed, defineHealthJourney, defineOperation, defineProvider, defineSmsOtpMatcher, every, } from "./define";
 export { AuthError, ProviderError, SessionExpiredError, TransportError, ValidationError, } from "./errors";
 export { getProviderLocalePath, providerLocaleKey, qualifyProviderLocaleKey, } from "./i18n";
 export { createProviderChoiceContext, createTestProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "./runtime/choice";

package/dist/runtime/auth-flow.js

@@ -1,4 +1,5 @@
 import { ContextAccessError } from "../errors";
+import { createAuthFlowHelpers } from "../auth";
 import { createUnsupportedSttClient } from "./stt";
 function normalizeAllowedKeys(allowedKeys) {
     return new Set(allowedKeys.filter((key) => key.trim().length > 0));
@@ -40,5 +41,6 @@ export function createFlowContext(options) {
         env: options.env,
         context: createScratchpad(options.allowedKeys, options.initialContext),
         stt: options.stt ?? createUnsupportedSttClient(),
+        auth: createAuthFlowHelpers(),
     };
 }