@apifuse/provider-sdk 2.1.0-beta.3 → 2.1.0-beta.4

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 {
@@ -55,15 +64,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,121 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+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)
+	);
+}
+
+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,7 +1,7 @@
 // @apifuse/provider-sdk
 
-export { z } from "zod";
 export * from "./ceremonies";
+export * from "./choice-token";
 export type {
 	ApiFuseConfig,
 	BrowserConfig,
@@ -9,10 +9,19 @@ export type {
 	SessionConfig,
 } from "./config/loader";
 export { defineConfig, loadApiFuseConfig } from "./config/loader";
-export { defineOperation, defineProvider, type ProviderConfig } from "./define";
+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,
@@ -23,6 +32,12 @@ 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 CreateCredentialContextOptions,
 	createCredentialContext,
@@ -39,15 +54,46 @@ 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,
@@ -56,6 +102,7 @@ export type {
 	AuthFlowHandler,
 	AuthMode,
 	AuthTurn,
+	Bcp47Locale,
 	BrowserEngine,
 	BrowserOptions,
 	ConnectionMode,
@@ -63,6 +110,7 @@ export type {
 	ContextScratchpad,
 	CredentialContext,
 	CredentialDeclaration,
+	E164PhoneNumber,
 	EnvContext,
 	FlowContext,
 	FlowContextStore,
@@ -71,38 +119,131 @@ 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,
 	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";