@apifuse/provider-sdk 2.1.0-beta.12 → 2.1.0-beta.14

package/dist/contract.js

@@ -122,6 +122,7 @@ function extractHealthCheck(value) {
         return undefined;
     return compactObject({
         interval: value.interval,
+        schedule: toJsonValue(value.schedule),
         timeoutMs: value.timeoutMs,
         degradedThresholdMs: value.degradedThresholdMs,
         requiresConnection: value.requiresConnection,

package/dist/define.d.ts

@@ -1,4 +1,4 @@
-import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, 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, ProviderHealthMonitorConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderReviewed, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, SchemaLike, SmsOtpMatcherDefinition, StealthPlatform } from "./types";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
 interface ProviderImplementationProfile {
@@ -88,7 +88,10 @@ export declare function defineOperation<TInput extends SchemaLike, TOutput exten
 export declare function defineStreamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(operation: StreamOperationConfig<TInput, TOutput>): OperationDefinition<TInput, TOutput>;
 export declare function every(interval: string, options?: {
     jitter?: string;
+    randomize?: HealthScheduleRandomization;
 }): HealthJourneySchedule;
+export declare function centered(maxOffset: string): HealthScheduleRandomization;
+export declare function delayed(maxDelay: string): HealthScheduleRandomization;
 export declare function defineSmsOtpMatcher(config: Omit<SmsOtpMatcherDefinition, "extractOtp">): SmsOtpMatcherDefinition;
 export declare function defineHealthJourney(config: HealthJourneyDefinition): HealthJourneyDefinition;
 export declare function defineProvider<TOperations extends Record<string, ProviderOperation>, TConfig extends ProviderConfig<TOperations>>(config: TConfig & AuthStartNoInputGuard<TConfig>): ProviderDefinition & {

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",
@@ -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);

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, CookieJar, 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, 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 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, 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(),
     };
 }

package/dist/runtime/browser.js

@@ -3,6 +3,106 @@ import { ProviderError } from "../errors";
 const require = createRequire(import.meta.url);
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 const SELECTOR_POLL_INTERVAL_MS = 100;
+const RESOURCE_POLICY_ROUTE_PATTERN = "**/*";
+const DEFAULT_RESOURCE_METHODS = ["GET", "HEAD"];
+function toResourceBody(body) {
+    if (body === undefined || typeof body === "string" || Buffer.isBuffer(body)) {
+        return body;
+    }
+    if (body instanceof ArrayBuffer) {
+        return Buffer.from(new Uint8Array(body));
+    }
+    return Buffer.from(body);
+}
+function isResourceMethod(method) {
+    return method === "GET" || method === "HEAD";
+}
+async function toResourceRequest(request) {
+    const method = request.method().toUpperCase();
+    if (!isResourceMethod(method)) {
+        return null;
+    }
+    return {
+        headers: await request.allHeaders(),
+        method,
+        resourceType: request.resourceType(),
+        url: request.url(),
+    };
+}
+function toCdpResourceRequest(params) {
+    if (!isRecord(params)) {
+        return null;
+    }
+    const requestId = params.requestId;
+    const rawRequest = params.request;
+    if (typeof requestId !== "string" || !isRecord(rawRequest)) {
+        return null;
+    }
+    const url = rawRequest.url;
+    const method = String(rawRequest.method ?? "").toUpperCase();
+    if (typeof url !== "string" || !isResourceMethod(method)) {
+        return null;
+    }
+    return {
+        requestId,
+        request: {
+            headers: toCdpResourceHeaders(rawRequest.headers),
+            method,
+            resourceType: typeof params.resourceType === "string" ? params.resourceType : undefined,
+            url,
+        },
+    };
+}
+function getCdpPausedRequestId(params) {
+    if (!isRecord(params) || typeof params.requestId !== "string") {
+        return null;
+    }
+    return params.requestId;
+}
+function toCdpResourceHeaders(value) {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const headers = {};
+    for (const [name, headerValue] of Object.entries(value)) {
+        if (typeof headerValue === "string") {
+            headers[name] = headerValue;
+        }
+    }
+    return headers;
+}
+function matchesResourceRoute(match, request) {
+    if (typeof match === "string") {
+        return request.url === match;
+    }
+    if (match instanceof RegExp) {
+        return match.test(request.url);
+    }
+    return match(request);
+}
+function toCdpFulfillParams(requestId, decision) {
+    const body = toResourceBody(decision.body);
+    return {
+        ...(body === undefined
+            ? {}
+            : { body: Buffer.from(body).toString("base64") }),
+        ...(decision.headers === undefined
+            ? {}
+            : {
+                responseHeaders: Object.entries(decision.headers).map(([name, value]) => ({ name, value })),
+            }),
+        requestId,
+        responseCode: decision.status ?? 200,
+    };
+}
+async function fulfillResourceRoute(route, decision) {
+    const body = toResourceBody(decision.body);
+    await route.fulfill({
+        ...(body === undefined ? {} : { body }),
+        ...(decision.headers === undefined ? {} : { headers: decision.headers }),
+        status: decision.status ?? 200,
+    });
+}
 function getDefaultCdpPoolUrl(env = process.env) {
     return env.APIFUSE__CDP_POOL__URL;
 }
@@ -256,6 +356,38 @@ class PlaywrightBrowserPage {
     async close() {
         await this.page.close();
     }
+    async withResourcePolicy(policy, run) {
+        const allowedMethods = new Set(policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS);
+        const handler = async (route) => {
+            const request = await toResourceRequest(route.request());
+            if (!request || !allowedMethods.has(request.method)) {
+                await route.abort("blockedbyclient");
+                return;
+            }
+            for (const resourceRoute of policy.routes) {
+                if (!matchesResourceRoute(resourceRoute.match, request)) {
+                    continue;
+                }
+                const decision = await resourceRoute.handle(request);
+                switch (decision.action) {
+                    case "fulfill":
+                        await fulfillResourceRoute(route, decision);
+                        return;
+                    case "block":
+                        await route.abort("blockedbyclient");
+                        return;
+                }
+            }
+            await route.abort("blockedbyclient");
+        };
+        await this.page.route(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+        try {
+            return await run();
+        }
+        finally {
+            await this.page.unroute(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+        }
+    }
 }
 class PlaywrightBrowserClient {
     options;
@@ -737,6 +869,77 @@ class CdpPoolBrowserPage {
             await this.pageClient.close();
         }
     }
+    async withResourcePolicy(policy, run) {
+        const allowedMethods = new Set(policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS);
+        const handlePausedRequest = (params) => {
+            void this.handleResourcePolicyPausedRequest(params, policy, allowedMethods);
+        };
+        const unsubscribe = this.pageClient.on("Fetch.requestPaused", handlePausedRequest);
+        try {
+            await this.pageClient.send("Fetch.enable", {
+                patterns: [{ requestStage: "Request", urlPattern: "*" }],
+            });
+        }
+        catch (error) {
+            unsubscribe();
+            throw new ProviderError("CDP browser target does not support BrowserPage.withResourcePolicy()", {
+                cause: error instanceof Error ? error : undefined,
+                code: "BROWSER_RUNTIME_UNSUPPORTED",
+                fix: "Use a Chromium CDP target with the Fetch domain enabled, or use the local Playwright browser runtime.",
+            });
+        }
+        try {
+            return await run();
+        }
+        finally {
+            unsubscribe();
+            await this.pageClient.send("Fetch.disable");
+        }
+    }
+    async handleResourcePolicyPausedRequest(params, policy, allowedMethods) {
+        const requestId = getCdpPausedRequestId(params);
+        if (requestId === null) {
+            return;
+        }
+        try {
+            const parsed = toCdpResourceRequest(params);
+            if (!parsed || !allowedMethods.has(parsed.request.method)) {
+                await this.failCdpResourceRequest(requestId);
+                return;
+            }
+            for (const resourceRoute of policy.routes) {
+                if (!matchesResourceRoute(resourceRoute.match, parsed.request)) {
+                    continue;
+                }
+                const decision = await resourceRoute.handle(parsed.request);
+                switch (decision.action) {
+                    case "fulfill":
+                        await this.pageClient.send("Fetch.fulfillRequest", toCdpFulfillParams(parsed.requestId, decision));
+                        return;
+                    case "block":
+                        await this.failCdpResourceRequest(parsed.requestId);
+                        return;
+                }
+            }
+            await this.failCdpResourceRequest(parsed.requestId);
+        }
+        catch {
+            await this.failCdpResourceRequest(requestId);
+        }
+    }
+    async failCdpResourceRequest(requestId) {
+        try {
+            await this.pageClient.send("Fetch.failRequest", {
+                errorReason: "BlockedByClient",
+                requestId,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                return;
+            }
+        }
+    }
     async initialize() {
         if (this.initialized) {
             return;