@apifuse/provider-sdk 2.1.0-beta.0 → 2.1.0-beta.10

package/src/errors.ts

@@ -1,7 +1,12 @@
+import type { ProviderErrorCategory } from "./observability";
+
 export type ProviderErrorOptions = {
 	fix?: string;
 	code?: string;
+	details?: unknown;
 	cause?: Error;
+	category?: ProviderErrorCategory;
+	retryable?: boolean;
 };
 
 export class ProviderError extends Error {
@@ -23,6 +28,10 @@ export class ProviderError extends Error {
 	get code(): string | undefined {
 		return this.options?.code;
 	}
+
+	get details(): unknown {
+		return this.options?.details;
+	}
 }
 
 export class SDKError extends ProviderError {
@@ -39,6 +48,21 @@ export class AuthError extends ProviderError {
 	}
 }
 
+export class SessionExpiredError extends AuthError {
+	constructor(
+		message = "Provider session expired",
+		options?: ProviderErrorOptions,
+	) {
+		super(message, {
+			code: "reauth_required",
+			category: "credential_expired",
+			retryable: false,
+			...options,
+		});
+		this.name = "SessionExpiredError";
+	}
+}
+
 export type ValidationErrorOptions = ProviderErrorOptions & {
 	zodError?: unknown;
 };
@@ -55,15 +79,18 @@ export class ValidationError extends ProviderError {
 
 export type TransportErrorOptions = ProviderErrorOptions & {
 	status?: number;
+	upstreamStatus?: number;
 };
 
 export class TransportError extends ProviderError {
 	readonly status?: number;
+	readonly upstreamStatus?: number;
 
 	constructor(message: string, options?: TransportErrorOptions) {
 		super(message, options);
 		this.name = "TransportError";
 		this.status = options?.status;
+		this.upstreamStatus = options?.upstreamStatus ?? options?.status;
 	}
 }
 

package/src/i18n/catalog.ts

@@ -0,0 +1,277 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { AuthTurn } from "../types";
+import {
+	getProviderLocalePath,
+	isProviderLocaleValue,
+	type ProviderLocale,
+	type ProviderLocaleCatalog,
+	type ProviderLocaleKey,
+	type ProviderLocaleValue,
+	providerLocaleKey,
+} from "./keys";
+
+export type ProviderLocaleCatalogMap = Record<
+	ProviderLocale,
+	ProviderLocaleCatalog
+>;
+
+export interface LoadProviderLocaleCatalogsOptions {
+	providerDir: string;
+	locales: readonly ProviderLocale[];
+}
+
+export interface ProviderLocaleValidationIssue {
+	locale: ProviderLocale;
+	key: string;
+	message: string;
+	severity: "error" | "warning";
+}
+
+export interface ProviderLocaleValidationResult {
+	ok: boolean;
+	issues: ProviderLocaleValidationIssue[];
+}
+
+export function loadProviderLocaleCatalogs(
+	options: LoadProviderLocaleCatalogsOptions,
+): ProviderLocaleCatalogMap {
+	const catalogs: ProviderLocaleCatalogMap = {};
+	for (const locale of options.locales) {
+		const filePath = join(options.providerDir, "locales", `${locale}.json`);
+		catalogs[locale] = JSON.parse(readFileSync(filePath, "utf8"));
+	}
+	return catalogs;
+}
+
+export function resolveProviderLocaleValue(
+	catalogs: ProviderLocaleCatalogMap,
+	key: ProviderLocaleKey | string,
+	locale: ProviderLocale,
+	fallbackLocale: ProviderLocale = "en",
+): ProviderLocaleValue | undefined {
+	providerLocaleKey(key);
+	return (
+		getProviderLocalePath(catalogs[locale] ?? {}, key) ??
+		getProviderLocalePath(catalogs[fallbackLocale] ?? {}, key)
+	);
+}
+
+function asStringValue(
+	value: ProviderLocaleValue | undefined,
+): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		!Array.isArray(value) &&
+		Object.values(value).every((entry) => typeof entry === "string")
+	);
+}
+
+function localizeAuthInputSchema(
+	expectedInput: Record<string, unknown> | undefined,
+	options: {
+		catalogs: ProviderLocaleCatalogMap;
+		locale: ProviderLocale;
+		fallbackLocale: ProviderLocale;
+	},
+): Record<string, unknown> | undefined {
+	if (!expectedInput) return undefined;
+	const schema = isRecord(expectedInput.schema)
+		? expectedInput.schema
+		: expectedInput;
+	const localizedSchema = localizeAuthSchemaObject(schema, options);
+	if (localizedSchema === schema) return undefined;
+	return isRecord(expectedInput.schema)
+		? { ...expectedInput, schema: localizedSchema }
+		: localizedSchema;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function localizeAuthSchemaObject(
+	schema: Record<string, unknown>,
+	options: {
+		catalogs: ProviderLocaleCatalogMap;
+		locale: ProviderLocale;
+		fallbackLocale: ProviderLocale;
+	},
+): Record<string, unknown> {
+	const properties = isRecord(schema.properties)
+		? schema.properties
+		: undefined;
+	if (!properties) return schema;
+
+	let changed = false;
+	const localizedProperties = Object.fromEntries(
+		Object.entries(properties).map(([fieldName, property]) => {
+			if (!isRecord(property)) return [fieldName, property];
+			const nameKey =
+				typeof property.nameKey === "string" ? property.nameKey : undefined;
+			const descriptionKey =
+				typeof property.descriptionKey === "string"
+					? property.descriptionKey
+					: undefined;
+			const title = nameKey
+				? asStringValue(
+						resolveProviderLocaleValue(
+							options.catalogs,
+							nameKey,
+							options.locale,
+							options.fallbackLocale,
+						),
+					)
+				: undefined;
+			const description = descriptionKey
+				? asStringValue(
+						resolveProviderLocaleValue(
+							options.catalogs,
+							descriptionKey,
+							options.locale,
+							options.fallbackLocale,
+						),
+					)
+				: undefined;
+			if (!title && !description) return [fieldName, property];
+			changed = true;
+			return [
+				fieldName,
+				{
+					...property,
+					...(title ? { title } : {}),
+					...(description ? { description } : {}),
+				},
+			];
+		}),
+	);
+
+	return changed ? { ...schema, properties: localizedProperties } : schema;
+}
+
+export function localizeAuthTurn(
+	turn: AuthTurn,
+	options: {
+		catalogs: ProviderLocaleCatalogMap;
+		locale: ProviderLocale;
+		fallbackLocale?: ProviderLocale;
+	},
+): AuthTurn {
+	const fallbackLocale = options.fallbackLocale ?? "en";
+	const hint = turn.hintKey
+		? asStringValue(
+				resolveProviderLocaleValue(
+					options.catalogs,
+					turn.hintKey,
+					options.locale,
+					fallbackLocale,
+				),
+			)
+		: undefined;
+	const expectedInput = localizeAuthInputSchema(turn.expectedInput, {
+		catalogs: options.catalogs,
+		locale: options.locale,
+		fallbackLocale,
+	});
+	const fieldErrorKeys = turn.data?.fieldErrorKeys;
+	const fieldErrors = isStringRecord(fieldErrorKeys)
+		? Object.fromEntries(
+				Object.entries(fieldErrorKeys).flatMap(([fieldName, key]) => {
+					const message = asStringValue(
+						resolveProviderLocaleValue(
+							options.catalogs,
+							key,
+							options.locale,
+							fallbackLocale,
+						),
+					);
+					return message ? [[fieldName, message]] : [];
+				}),
+			)
+		: undefined;
+
+	if (!hint && !fieldErrors && !expectedInput) return turn;
+
+	return {
+		...turn,
+		...(hint ? { hint } : {}),
+		...(expectedInput ? { expectedInput } : {}),
+		...(fieldErrors
+			? {
+					data: {
+						...(turn.data ?? {}),
+						fieldErrors,
+					},
+				}
+			: {}),
+	};
+}
+
+export function validateProviderLocaleCatalogs(options: {
+	catalogs: ProviderLocaleCatalogMap;
+	requiredLocales: readonly ProviderLocale[];
+	requiredKeys: readonly (ProviderLocaleKey | string)[];
+}): ProviderLocaleValidationResult {
+	const issues: ProviderLocaleValidationIssue[] = [];
+	const uniqueKeys = Array.from(
+		new Set(
+			options.requiredKeys.map((key) => {
+				providerLocaleKey(key);
+				return key;
+			}),
+		),
+	);
+
+	for (const locale of options.requiredLocales) {
+		const catalog = options.catalogs[locale];
+		if (!catalog) {
+			issues.push({
+				locale,
+				key: "*",
+				message: `Missing provider locale catalog for ${locale}`,
+				severity: "error",
+			});
+			continue;
+		}
+
+		for (const key of uniqueKeys) {
+			const value = getProviderLocalePath(catalog, key);
+			if (value === undefined) {
+				issues.push({
+					locale,
+					key,
+					message: `Missing provider locale key ${key} in ${locale}`,
+					severity: "error",
+				});
+				continue;
+			}
+			if (!isProviderLocaleValue(value)) {
+				issues.push({
+					locale,
+					key,
+					message: `Provider locale key ${key} must resolve to a string or string array`,
+					severity: "error",
+				});
+				continue;
+			}
+			for (const text of Array.isArray(value) ? value : [value]) {
+				if (text.trim().length === 0 || /\bTODO\b/i.test(text)) {
+					issues.push({
+						locale,
+						key,
+						message: `Provider locale key ${key} in ${locale} is empty or placeholder text`,
+						severity: "error",
+					});
+				}
+			}
+		}
+	}
+
+	return { ok: issues.every((issue) => issue.severity !== "error"), issues };
+}

package/src/i18n/index.ts

@@ -0,0 +1,2 @@
+export * from "./catalog";
+export * from "./keys";

package/src/i18n/keys.ts

@@ -0,0 +1,64 @@
+import type { ProviderLocaleKey } from "../types";
+
+export type { ProviderLocale, ProviderLocaleKey } from "../types";
+
+const PROVIDER_LOCALE_KEY_RE =
+	/^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)*|\.[0-9]+)*$/;
+
+export function providerLocaleKey(key: string): ProviderLocaleKey {
+	assertProviderLocaleKey(key);
+	return key;
+}
+
+export function isProviderLocaleKey(
+	value: unknown,
+): value is ProviderLocaleKey {
+	return typeof value === "string" && PROVIDER_LOCALE_KEY_RE.test(value);
+}
+
+export function assertProviderLocaleKey(
+	value: unknown,
+): asserts value is ProviderLocaleKey {
+	if (!isProviderLocaleKey(value)) {
+		throw new Error(
+			`Provider locale key must be a dot path such as "meta.description" or "operations.search.description"; received ${JSON.stringify(value)}`,
+		);
+	}
+}
+
+export function qualifyProviderLocaleKey(
+	providerId: string,
+	key: ProviderLocaleKey | string,
+): string {
+	assertProviderLocaleKey(key);
+	return `providers.${providerId}.${key}`;
+}
+
+export function getProviderLocalePath(
+	catalog: ProviderLocaleCatalog,
+	key: ProviderLocaleKey | string,
+): ProviderLocaleValue | undefined {
+	assertProviderLocaleKey(key);
+	let cursor: unknown = catalog;
+	for (const segment of key.split(".")) {
+		if (!isRecord(cursor)) return undefined;
+		cursor = cursor[segment];
+	}
+	return isProviderLocaleValue(cursor) ? cursor : undefined;
+}
+
+export type ProviderLocaleValue = string | readonly string[];
+export type ProviderLocaleCatalog = Record<string, unknown>;
+
+export function isProviderLocaleValue(
+	value: unknown,
+): value is ProviderLocaleValue {
+	return (
+		typeof value === "string" ||
+		(Array.isArray(value) && value.every((entry) => typeof entry === "string"))
+	);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/index.ts

@@ -1,13 +1,7 @@
 // @apifuse/provider-sdk
 
-export { z } from "zod";
 export * from "./ceremonies";
-export {
-	type ClarifyResponse,
-	type CompositeContext,
-	type CompositeOperationDefinition,
-	defineCompositeOperation,
-} from "./composite";
+export * from "./choice-token";
 export type {
 	ApiFuseConfig,
 	BrowserConfig,
@@ -15,10 +9,29 @@ export type {
 	SessionConfig,
 } from "./config/loader";
 export { defineConfig, loadApiFuseConfig } from "./config/loader";
-export { defineOperation, defineProvider, type ProviderConfig } from "./define";
+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 type { DevServerOptions } from "./dev";
 export { createDevServer, startDevServer } from "./dev";
 export * from "./errors";
+export * from "./i18n";
 export {
 	type LintDiagnostic,
 	lintOperation,
@@ -29,6 +42,18 @@ export * from "./recipes/rest-api";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow";
 export type { BrowserClientOptions } from "./runtime/browser";
 export { BrowserClient, createBrowserClient } from "./runtime/browser";
+export {
+	createBypassProviderCache,
+	createProviderCache,
+	type ProviderCacheOptions,
+	resetProviderCacheForTests,
+} from "./runtime/cache";
+export {
+	type CreateProviderChoiceContextOptions,
+	createProviderChoiceContext,
+	createTestProviderChoiceContext,
+	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+} from "./runtime/choice";
 export {
 	type CreateCredentialContextOptions,
 	createCredentialContext,
@@ -45,23 +70,56 @@ export {
 } from "./runtime/instrumentation";
 export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate";
 export { getProviderBaseUrl } from "./runtime/provider";
-export { createTlsClient } from "./runtime/tls";
+export {
+	createUnsupportedProviderRuntimeState,
+	UnsupportedProviderStateError,
+} from "./runtime/state";
+export { createStealthClient } from "./runtime/stealth";
+export {
+	APIFUSE__STT__BACKEND_ENV,
+	APIFUSE__STT__CLOUDFLARE_API_TOKEN_ENV,
+	APIFUSE__STT__MODEL_ENV,
+	createSttClientFromEnv,
+	createUnsupportedSttClient,
+	extractVerificationCode,
+	resolveSttPrompt,
+} from "./runtime/stt";
 export {
 	type CreateTraceContextOptions,
 	createTraceContext,
 	type Span,
 	type TraceContext,
 } from "./runtime/trace";
+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 { createServerApp, type ServeOptions, serve } from "./server";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles";
+export * from "./stream";
 export type {
 	ApiFuseResponse,
 	AuthConfig,
 	AuthContext,
 	AuthFlowDefinition,
-	AuthFlowHandler,
+	AuthFlowInputHandler,
+	AuthFlowStartHandler,
 	AuthMode,
 	AuthTurn,
+	Bcp47Locale,
 	BrowserEngine,
 	BrowserOptions,
 	ConnectionMode,
@@ -69,6 +127,7 @@ export type {
 	ContextScratchpad,
 	CredentialContext,
 	CredentialDeclaration,
+	E164PhoneNumber,
 	EnvContext,
 	FlowContext,
 	FlowContextStore,
@@ -77,35 +136,135 @@ export type {
 	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,
-	TlsClient,
-	TlsFetchOptions,
-	TlsResponse,
-	TlsSession,
+	StealthResponse,
+	StealthSession,
+	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 { PROBE_INTERVALS } from "./types";
 export * from "./utils/date";
 export * from "./utils/parse";
 export * from "./utils/text";