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

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>;
@@ -374,6 +353,14 @@ function validateProviderShape(config: unknown): void {
 			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" &&
@@ -1116,6 +1103,7 @@ function validateOperationTransports(
 
 const HEALTH_CHECK_SUITE_FIELDS = new Set([
 	"interval",
+	"schedule",
 	"timeoutMs",
 	"degradedThresholdMs",
 	"cases",
@@ -1463,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,
@@ -1561,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",
@@ -1734,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,
@@ -1749,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`;
@@ -1767,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;
@@ -1993,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(
@@ -2244,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

@@ -1,5 +1,6 @@
 // @apifuse/provider-sdk
 
+export * from "./auth";
 export * from "./ceremonies";
 export * from "./choice-token";
 export type {
@@ -20,6 +21,8 @@ export {
 	type ProviderContractSnapshot,
 } from "./contract";
 export {
+	centered,
+	delayed,
 	defineHealthJourney,
 	defineOperation,
 	defineProvider,
@@ -122,6 +125,12 @@ export type {
 	Bcp47Locale,
 	BrowserEngine,
 	BrowserOptions,
+	BrowserResourceBody,
+	BrowserResourceDecision,
+	BrowserResourceMethod,
+	BrowserResourcePolicy,
+	BrowserResourceRequest,
+	BrowserResourceRoute,
 	ConnectionMode,
 	ContextDeclaration,
 	CookieJar,
@@ -145,6 +154,7 @@ export type {
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
 	HealthJourneySchedule,
+	HealthScheduleRandomization,
 	HealthJourneySmsContext,
 	HealthJourneyStep,
 	HttpClient,

package/src/lint.ts

@@ -22,8 +22,12 @@ type ProviderAuthLike = {
 		abort?: unknown;
 		refresh?: unknown;
 	};
+	exchange?: unknown;
 };
 
+const AUTH_OPERATION_ID_PATTERN =
+	/^(?:auth[-_])?(?:login|exchange|continue|refresh|callback)(?:[-_]|$)/i;
+
 type ProviderContractMetaLike = {
 	publicSchemaFieldNames?: "normalized";
 };
@@ -127,6 +131,10 @@ function lintReviewed(
 	];
 }
 
+function isProviderAuthLike(value: unknown): value is ProviderAuthLike {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
 function hasReusableSecretKeys(keys: readonly string[] | undefined): boolean {
 	if (!keys) {
 		return false;
@@ -215,6 +223,15 @@ function lintAuthModel(provider: {
 		});
 	}
 
+	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",
@@ -1006,6 +1023,22 @@ export function lintProvider(
 		...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/src/provider.ts

@@ -1,3 +1,22 @@
+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,
@@ -8,6 +27,8 @@ export {
 	parseProviderChoiceToken,
 } from "./choice-token";
 export {
+	centered,
+	delayed,
 	defineHealthJourney,
 	defineOperation,
 	defineProvider,
@@ -50,7 +71,12 @@ export {
 	z,
 } from "./schema";
 export type {
+	AuthAbortData,
+	AuthAbortRetry,
+	AuthFlowTerminalContext,
 	AuthMode,
+	AuthSafeData,
+	AuthSafeJson,
 	FlowContext,
 	HealthCheckAssertionContext,
 	HealthCheckCase,
@@ -61,6 +87,7 @@ export type {
 	HealthJourneyManualTriggerPolicy,
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
+	HealthScheduleRandomization,
 	HttpRetryOptions,
 	HttpRetrySummary,
 	InferSchemaOutput,

package/src/runtime/auth-flow.ts

@@ -1,4 +1,5 @@
 import { ContextAccessError } from "../errors";
+import { createAuthFlowHelpers } from "../auth";
 import type {
 	ContextScratchpad,
 	EnvContext,
@@ -70,5 +71,6 @@ export function createFlowContext(options: {
 		env: options.env,
 		context: createScratchpad(options.allowedKeys, options.initialContext),
 		stt: options.stt ?? createUnsupportedSttClient(),
+		auth: createAuthFlowHelpers(),
 	};
 }