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

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.14
+
+- Release candidate for main commit 6eb132be6abf34ad9a70bfe28c6d26b36348ff4a.
+
 ## 2.1.0-beta.13
 
 - Release candidate for main commit d7b12716f54781df3e40206144c167844a485f8f.

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) {
@@ -560,6 +533,7 @@ function validateOperationTransports(providerId, operations) {
 }
 const HEALTH_CHECK_SUITE_FIELDS = new Set([
     "interval",
+    "schedule",
     "timeoutMs",
     "degradedThresholdMs",
     "cases",
@@ -781,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,
@@ -842,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",
@@ -958,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.`);
@@ -967,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")
@@ -985,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;
@@ -1145,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();
@@ -1283,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

@@ -4,7 +4,7 @@ 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";
@@ -34,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, 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, 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

@@ -4,7 +4,7 @@ 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/provider.d.ts

@@ -2,10 +2,10 @@ export { AuthAbortError, credentialsAuthChallenge, createAuthFlowHelpers, define
 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 { AuthAbortData, AuthAbortRetry, AuthFlowTerminalContext, AuthMode, AuthSafeData, AuthSafeJson, 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,7 +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/types.d.ts

@@ -268,8 +268,16 @@ export interface HealthJourneySchedule {
     kind: "interval";
     /** ISO 8601 duration, for example PT8H. */
     interval: Iso8601Duration;
+    randomize?: HealthScheduleRandomization;
     jitter?: Iso8601Duration;
 }
+export type HealthScheduleRandomization = {
+    mode: "centered";
+    maxOffset: Iso8601Duration;
+} | {
+    mode: "delayed";
+    maxDelay: Iso8601Duration;
+};
 export interface HealthJourneyStep {
     id: string;
     description?: string;
@@ -511,6 +519,9 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
 export interface HealthCheckSuite<TInput = unknown, TOutput = unknown> {
     /** Polling interval for the suite. All cases share this cadence. */
     interval: ProbeInterval;
+    schedule?: {
+        randomize?: HealthScheduleRandomization;
+    };
     /** Per-case timeout in milliseconds. Default: 30000. */
     timeoutMs?: number;
     /** Default degradation threshold for cases in this suite. Default: runtime threshold. */

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.1.0-beta.13",
+	"version": "2.1.0-beta.14",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/contract.ts

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

package/src/define.ts

@@ -1,3 +1,5 @@
+import ms from "ms";
+
 import { ProviderError, ValidationError } from "./errors";
 import { safeParseSchemaSync } from "./schema";
 import type {
@@ -10,6 +12,7 @@ import type {
 	HealthCheckUnsupported,
 	HealthJourneyDefinition,
 	HealthJourneySchedule,
+	HealthScheduleRandomization,
 	InferSchemaOutput,
 	OperationDefinition,
 	OperationHandlerResult,
@@ -118,49 +121,25 @@ 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: unknown): value is string {
 	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: string): number {
+	return parsePositiveMsDuration(value) ?? 0;
+}
+
+function parsePositiveMsDuration(value: string): number | undefined {
+	const trimmed = value.trim();
+	if (!MS_DURATION_PATTERN.test(trimmed)) return undefined;
+	const parsed = ms(
+		(trimmed.startsWith("+") ? trimmed.slice(1) : trimmed) as ms.StringValue,
+	);
+	if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+	return parsed;
 }
 
 type ProviderOperation = OperationDefinition<SchemaLike, SchemaLike>;
@@ -1124,6 +1103,7 @@ function validateOperationTransports(
 
 const HEALTH_CHECK_SUITE_FIELDS = new Set([
 	"interval",
+	"schedule",
 	"timeoutMs",
 	"degradedThresholdMs",
 	"cases",
@@ -1471,6 +1451,35 @@ function validateHealthCheckSuite(
 				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,
@@ -1569,7 +1578,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",
@@ -1742,6 +1756,54 @@ function isoDurationMs(value: string): number {
 	);
 }
 
+function scheduleRandomizationMs(
+	randomize: unknown,
+	fieldPath: string,
+): number {
+	const mode = Reflect.get(randomize as object, "mode");
+	switch (mode) {
+		case "centered": {
+			const maxOffset = Reflect.get(randomize as object, "maxOffset");
+			assertIsoDuration(maxOffset, `${fieldPath}.maxOffset`);
+			return isoDurationMs(maxOffset);
+		}
+		case "delayed": {
+			const maxDelay = Reflect.get(randomize as object, "maxDelay");
+			assertIsoDuration(maxDelay, `${fieldPath}.maxDelay`);
+			return isoDurationMs(maxDelay);
+		}
+		default:
+			throw new ValidationError(
+				`${fieldPath}.mode must be "centered" or "delayed".`,
+			);
+	}
+}
+
+function validateScheduleRandomization(
+	randomize: unknown,
+	fieldPath: string,
+	intervalMs: number,
+): void {
+	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: unknown,
 	fieldPath: string,
@@ -1757,13 +1819,21 @@ function normalizeIntervalDuration(input: string): string {
 	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") return `PT${amount}M`;
 		if (unit === "h") return `PT${amount}H`;
@@ -1775,18 +1845,34 @@ function normalizeIntervalDuration(input: string): string {
 
 export function every(
 	interval: string,
-	options: { jitter?: string } = {},
+	options: { jitter?: string; randomize?: HealthScheduleRandomization } = {},
 ): HealthJourneySchedule {
+	if (options.jitter !== undefined && options.randomize !== undefined) {
+		throw new ValidationError(
+			`Schedule cannot define both jitter and randomize. Use randomize instead.`,
+		);
+	}
 	const schedule: HealthJourneySchedule = {
 		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: string): HealthScheduleRandomization {
+	return { mode: "centered", maxOffset: normalizeIntervalDuration(maxOffset) };
+}
+
+export function delayed(maxDelay: string): HealthScheduleRandomization {
+	return { mode: "delayed", maxDelay: normalizeIntervalDuration(maxDelay) };
+}
+
 function countCapturingGroups(pattern: RegExp): number {
 	let count = 0;
 	const source = pattern.source;
@@ -2001,15 +2087,29 @@ function validateHealthJourneySchedule(
 		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(
@@ -2252,7 +2352,9 @@ export function defineProvider<
 	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" },
+			{
+				fix: "Add at least one operation to the operations object",
+			},
 		);
 	validateOperationIds(config.id, config.operations);
 	validateOperationAnnotations(config.id, config.operations);

package/src/index.ts

@@ -21,6 +21,8 @@ export {
 	type ProviderContractSnapshot,
 } from "./contract";
 export {
+	centered,
+	delayed,
 	defineHealthJourney,
 	defineOperation,
 	defineProvider,
@@ -152,6 +154,7 @@ export type {
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
 	HealthJourneySchedule,
+	HealthScheduleRandomization,
 	HealthJourneySmsContext,
 	HealthJourneyStep,
 	HttpClient,

package/src/provider.ts

@@ -27,6 +27,8 @@ export {
 	parseProviderChoiceToken,
 } from "./choice-token";
 export {
+	centered,
+	delayed,
 	defineHealthJourney,
 	defineOperation,
 	defineProvider,
@@ -85,6 +87,7 @@ export type {
 	HealthJourneyManualTriggerPolicy,
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
+	HealthScheduleRandomization,
 	HttpRetryOptions,
 	HttpRetrySummary,
 	InferSchemaOutput,

package/src/types.ts

@@ -331,9 +331,20 @@ export interface HealthJourneySchedule {
 	kind: "interval";
 	/** ISO 8601 duration, for example PT8H. */
 	interval: Iso8601Duration;
+	randomize?: HealthScheduleRandomization;
 	jitter?: Iso8601Duration;
 }
 
+export type HealthScheduleRandomization =
+	| {
+			mode: "centered";
+			maxOffset: Iso8601Duration;
+	  }
+	| {
+			mode: "delayed";
+			maxDelay: Iso8601Duration;
+	  };
+
 export interface HealthJourneyStep {
 	id: string;
 	description?: string;
@@ -612,6 +623,9 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
 export interface HealthCheckSuite<TInput = unknown, TOutput = unknown> {
 	/** Polling interval for the suite. All cases share this cadence. */
 	interval: ProbeInterval;
+	schedule?: {
+		randomize?: HealthScheduleRandomization;
+	};
 	/** Per-case timeout in milliseconds. Default: 30000. */
 	timeoutMs?: number;
 	/** Default degradation threshold for cases in this suite. Default: runtime threshold. */