@apifuse/provider-sdk 2.1.0-beta.5 → 2.1.0-beta.8

package/src/contract-json.ts

@@ -0,0 +1,75 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue =
+	| JsonPrimitive
+	| readonly JsonValue[]
+	| { readonly [key: string]: JsonValue };
+
+export function canonicalJson(value: unknown): string {
+	return JSON.stringify(canonicalize(toJsonValue(value) ?? null));
+}
+
+export function toJsonValue(value: unknown): JsonValue | undefined {
+	if (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "boolean"
+	) {
+		return value;
+	}
+	if (typeof value === "number") {
+		return Number.isFinite(value) ? value : undefined;
+	}
+	if (Array.isArray(value)) {
+		return value.flatMap((item) => {
+			const json = toJsonValue(item);
+			return json === undefined ? [] : [json];
+		});
+	}
+	if (!isRecord(value)) return undefined;
+	return compactObject(
+		Object.fromEntries(
+			Object.entries(value).flatMap(([key, item]) => {
+				const json = toJsonValue(item);
+				return json === undefined ? [] : [[key, json]];
+			}),
+		),
+	);
+}
+
+export function compactObject(
+	value: Record<string, JsonValue | undefined>,
+): JsonValue {
+	return Object.fromEntries(
+		Object.entries(value).filter((entry): entry is [string, JsonValue] => {
+			const [, item] = entry;
+			return item !== undefined;
+		}),
+	);
+}
+
+export function copyRecordWithout(
+	value: unknown,
+	ignoredKeys: ReadonlySet<string>,
+): Record<string, unknown> {
+	if (!isRecord(value)) return {};
+	return Object.fromEntries(
+		Object.entries(value).filter(([key]) => !ignoredKeys.has(key)),
+	);
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function canonicalize(value: JsonValue): JsonValue {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (!isRecord(value)) return value;
+	return Object.fromEntries(
+		Object.entries(value)
+			.sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
+			.flatMap(([key, item]) => {
+				const json = toJsonValue(item);
+				return json === undefined ? [] : [[key, canonicalize(json)]];
+			}),
+	);
+}

package/src/contract-serialization.ts

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { type ZodType, z } from "zod";
+import {
+	canonicalJson,
+	compactObject,
+	isRecord,
+	type JsonValue,
+	toJsonValue,
+} from "./contract-json";
+import type { SchemaLike } from "./types";
+
+export function describeSchema(schema: SchemaLike): JsonValue {
+	if (isZodSchema(schema)) {
+		const jsonSchema = zodJsonSchema(schema);
+		return compactObject({
+			kind: "schema",
+			vendor: "zod",
+			typeName: getSchemaTypeName(schema),
+			jsonSchema,
+			jsonSchemaHash:
+				jsonSchema === undefined
+					? undefined
+					: digest(canonicalJson(jsonSchema)),
+		});
+	}
+	const standard = isRecord(schema) ? schema["~standard"] : undefined;
+	if (isRecord(standard)) {
+		return compactObject({
+			kind: "schema",
+			standard: "standard-schema-v1",
+			vendor: typeof standard.vendor === "string" ? standard.vendor : "unknown",
+			version:
+				typeof standard.version === "number" ||
+				typeof standard.version === "string"
+					? standard.version
+					: undefined,
+		});
+	}
+	return compactObject({
+		kind: "schema",
+		vendor: "zod",
+		typeName: getSchemaTypeName(schema),
+	});
+}
+
+export function serializeSmsMatcher(
+	value: Record<string, unknown>,
+): Record<string, unknown> {
+	const code = value.code;
+	if (!isRecord(code)) return value;
+	const pattern = code.pattern;
+	if (!(pattern instanceof RegExp)) return value;
+	return {
+		...value,
+		code: {
+			...code,
+			pattern: {
+				source: pattern.source,
+				flags: pattern.flags,
+			},
+		},
+	};
+}
+
+function digest(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function isZodSchema(schema: SchemaLike): schema is ZodType {
+	return schema instanceof z.ZodType;
+}
+
+function zodJsonSchema(schema: ZodType): JsonValue | undefined {
+	try {
+		const jsonSchema = z.toJSONSchema(schema);
+		return toJsonValue(jsonSchema);
+	} catch (error) {
+		if (error instanceof Error) return undefined;
+		throw error;
+	}
+}
+
+function getSchemaTypeName(schema: SchemaLike): string | undefined {
+	if (!isRecord(schema)) return undefined;
+	const def = schema._def;
+	if (!isRecord(def)) return undefined;
+	const typeName = def.typeName ?? def.type;
+	return typeof typeName === "string" ? typeName : undefined;
+}

package/src/contract-types.ts

@@ -0,0 +1,52 @@
+import type { JsonValue } from "./contract-json";
+import type { ProviderDefinition } from "./types";
+
+export const PROVIDER_CONTRACT_SCHEMA_VERSION = "2026-06-23";
+
+export interface ProviderContractSnapshot {
+	readonly schemaVersion: typeof PROVIDER_CONTRACT_SCHEMA_VERSION;
+	readonly provider: {
+		readonly id: string;
+		readonly version: string;
+		readonly runtime: ProviderDefinition["runtime"];
+	};
+	readonly allowedHosts?: readonly string[];
+	readonly stealth?: JsonValue;
+	readonly proxy?: JsonValue;
+	readonly stt?: JsonValue;
+	readonly browser?: JsonValue;
+	readonly auth?: JsonValue;
+	readonly reviewed?: JsonValue;
+	readonly access?: JsonValue;
+	readonly secrets?: JsonValue;
+	readonly credential?: JsonValue;
+	readonly context?: JsonValue;
+	readonly meta: JsonValue;
+	readonly healthMonitor?: JsonValue;
+	readonly healthJourneys?: readonly JsonValue[];
+	readonly operations: readonly ProviderContractOperation[];
+}
+
+export interface ProviderContractOperation {
+	readonly id: string;
+	readonly descriptionKey?: JsonValue;
+	readonly docs?: JsonValue;
+	readonly whenToUseKeys?: JsonValue;
+	readonly whenNotToUseKeys?: JsonValue;
+	readonly derivations?: JsonValue;
+	readonly inputExamples?: JsonValue;
+	readonly annotations?: JsonValue;
+	readonly contract?: JsonValue;
+	readonly tags?: JsonValue;
+	readonly relatedOperations?: JsonValue;
+	readonly toolRouter?: JsonValue;
+	readonly observability?: JsonValue;
+	readonly transport?: JsonValue;
+	readonly inputSchema: JsonValue;
+	readonly outputSchema: JsonValue;
+	readonly fixtures?: JsonValue;
+	readonly upstream?: JsonValue;
+	readonly hints?: JsonValue;
+	readonly healthCheck?: JsonValue;
+	readonly healthCheckUnsupported?: JsonValue;
+}

package/src/contract.ts

@@ -0,0 +1,215 @@
+import { createHash } from "node:crypto";
+import {
+	canonicalJson,
+	compactObject,
+	copyRecordWithout,
+	type JsonPrimitive,
+	type JsonValue,
+	toJsonValue,
+} from "./contract-json";
+import { describeSchema, serializeSmsMatcher } from "./contract-serialization";
+import {
+	PROVIDER_CONTRACT_SCHEMA_VERSION,
+	type ProviderContractOperation,
+	type ProviderContractSnapshot,
+} from "./contract-types";
+import type {
+	HealthCheckSuite,
+	HealthCheckUnsupported,
+	HealthJourneyDefinition,
+	OperationDefinition,
+	OperationTransport,
+	ProviderDefinition,
+} from "./types";
+
+export {
+	canonicalJson,
+	type JsonPrimitive,
+	type JsonValue,
+	PROVIDER_CONTRACT_SCHEMA_VERSION,
+	type ProviderContractOperation,
+	type ProviderContractSnapshot,
+};
+
+export function extractProviderContract(
+	provider: ProviderDefinition,
+): ProviderContractSnapshot {
+	const auth = extractAuth(provider.auth);
+	const stealth = toJsonValue(provider.stealth);
+	const proxy = toJsonValue(provider.proxy);
+	const stt = toJsonValue(provider.stt);
+	const browser = toJsonValue(provider.browser);
+	const reviewed = toJsonValue(provider.reviewed);
+	const access = toJsonValue(provider.access);
+	const secrets = toJsonValue(provider.secrets);
+	const credential = toJsonValue(provider.credential);
+	const context = toJsonValue(provider.context);
+	const healthMonitor = toJsonValue(provider.healthMonitor);
+	const healthJourneys = provider.healthJourneys?.map(extractHealthJourney);
+
+	return {
+		schemaVersion: PROVIDER_CONTRACT_SCHEMA_VERSION,
+		provider: {
+			id: provider.id,
+			version: provider.version,
+			runtime: provider.runtime,
+		},
+		meta: toJsonValue(provider.meta) ?? null,
+		operations: Object.entries(provider.operations)
+			.sort(([leftId], [rightId]) => leftId.localeCompare(rightId))
+			.map(([operationId, operation]) =>
+				extractOperation(operationId, operation),
+			),
+		...(provider.allowedHosts
+			? { allowedHosts: [...provider.allowedHosts].sort() }
+			: {}),
+		...(stealth === undefined ? {} : { stealth }),
+		...(proxy === undefined ? {} : { proxy }),
+		...(stt === undefined ? {} : { stt }),
+		...(browser === undefined ? {} : { browser }),
+		...(auth === undefined ? {} : { auth }),
+		...(reviewed === undefined ? {} : { reviewed }),
+		...(access === undefined ? {} : { access }),
+		...(secrets === undefined ? {} : { secrets }),
+		...(credential === undefined ? {} : { credential }),
+		...(context === undefined ? {} : { context }),
+		...(healthMonitor === undefined ? {} : { healthMonitor }),
+		...(healthJourneys === undefined ? {} : { healthJourneys }),
+	};
+}
+
+export function digestProviderContract(
+	snapshot: ProviderContractSnapshot,
+): string {
+	return createHash("sha256").update(canonicalJson(snapshot)).digest("hex");
+}
+
+function extractOperation(
+	operationId: string,
+	operation: OperationDefinition,
+): ProviderContractOperation {
+	const descriptionKey = toJsonValue(operation.descriptionKey);
+	const docs = toJsonValue(operation.docs);
+	const whenToUseKeys = toJsonValue(operation.whenToUseKeys);
+	const whenNotToUseKeys = toJsonValue(operation.whenNotToUseKeys);
+	const derivations = toJsonValue(operation.derivations);
+	const inputExamples = toJsonValue(operation.inputExamples);
+	const annotations = toJsonValue(operation.annotations);
+	const contract = toJsonValue(operation.contract);
+	const tags = toJsonValue(operation.tags);
+	const relatedOperations = toJsonValue(operation.relatedOperations);
+	const toolRouter = toJsonValue(operation.toolRouter);
+	const observability = toJsonValue(operation.observability);
+	const transport = extractTransport(operation.transport);
+	const fixtures = toJsonValue(operation.fixtures);
+	const upstream = toJsonValue(operation.upstream);
+	const hints = toJsonValue(operation.hints);
+	const healthCheck = extractHealthCheck(operation.healthCheck);
+	const healthCheckUnsupported = extractHealthCheckUnsupported(
+		operation.healthCheckUnsupported,
+	);
+
+	return {
+		id: operationId,
+		inputSchema: describeSchema(operation.input),
+		outputSchema: describeSchema(operation.output),
+		...(descriptionKey === undefined ? {} : { descriptionKey }),
+		...(docs === undefined ? {} : { docs }),
+		...(whenToUseKeys === undefined ? {} : { whenToUseKeys }),
+		...(whenNotToUseKeys === undefined ? {} : { whenNotToUseKeys }),
+		...(derivations === undefined ? {} : { derivations }),
+		...(inputExamples === undefined ? {} : { inputExamples }),
+		...(annotations === undefined ? {} : { annotations }),
+		...(contract === undefined ? {} : { contract }),
+		...(tags === undefined ? {} : { tags }),
+		...(relatedOperations === undefined ? {} : { relatedOperations }),
+		...(toolRouter === undefined ? {} : { toolRouter }),
+		...(observability === undefined ? {} : { observability }),
+		...(transport === undefined ? {} : { transport }),
+		...(fixtures === undefined ? {} : { fixtures }),
+		...(upstream === undefined ? {} : { upstream }),
+		...(hints === undefined ? {} : { hints }),
+		...(healthCheck === undefined ? {} : { healthCheck }),
+		...(healthCheckUnsupported === undefined ? {} : { healthCheckUnsupported }),
+	};
+}
+
+function extractAuth(value: ProviderDefinition["auth"]): JsonValue | undefined {
+	if (!value) return undefined;
+	return compactObject({
+		mode: value.mode,
+		flow: value.flow
+			? compactObject({
+					start: true,
+					continue: true,
+					poll: value.flow.poll === undefined ? undefined : true,
+					abort: value.flow.abort === undefined ? undefined : true,
+				})
+			: undefined,
+	});
+}
+
+function extractTransport(
+	value: OperationTransport | undefined,
+): JsonValue | undefined {
+	if (!value) return undefined;
+	if (value.kind !== "sse") return toJsonValue(value);
+	return compactObject({
+		...copyRecordWithout(value, new Set(["events"])),
+		events: Object.fromEntries(
+			Object.entries(value.events)
+				.sort(([leftId], [rightId]) => leftId.localeCompare(rightId))
+				.map(([eventName, schema]) => [eventName, describeSchema(schema)]),
+		),
+	});
+}
+
+function extractHealthCheck(
+	value: HealthCheckSuite | undefined,
+): JsonValue | undefined {
+	if (!value) return undefined;
+	return compactObject({
+		interval: value.interval,
+		timeoutMs: value.timeoutMs,
+		degradedThresholdMs: value.degradedThresholdMs,
+		requiresConnection: value.requiresConnection,
+		cases: value.cases.map((item) =>
+			compactObject({
+				name: item.name,
+				description: item.description,
+				input: toJsonValue(item.input),
+				degradedThresholdMs: item.degradedThresholdMs,
+				timeoutMs: item.timeoutMs,
+				expectedStatus: item.expectedStatus,
+			}),
+		),
+	});
+}
+
+function extractHealthCheckUnsupported(
+	value: HealthCheckUnsupported | undefined,
+): JsonValue | undefined {
+	return toJsonValue(value);
+}
+
+function extractHealthJourney(value: HealthJourneyDefinition): JsonValue {
+	return compactObject({
+		id: value.id,
+		title: value.title,
+		description: value.description,
+		schedule: toJsonValue(value.schedule),
+		coversOperations: toJsonValue(value.coversOperations),
+		timeout: value.timeout,
+		cooldown: value.cooldown,
+		smsMatchers: toJsonValue(
+			value.smsMatchers?.map((matcher) =>
+				serializeSmsMatcher(
+					copyRecordWithout(matcher, new Set(["extractOtp"])),
+				),
+			),
+		),
+		requiredSecrets: toJsonValue(value.requiredSecrets),
+		manualTrigger: toJsonValue(value.manualTrigger),
+		steps: toJsonValue(value.steps),
+	});
+}

package/src/define.ts

@@ -230,6 +230,18 @@ type WebSocketOperationConfig<
 		| Promise<Response | ReadableStream<Uint8Array>>;
 };
 
+type AuthStartNoInputGuard<TConfig> = TConfig extends {
+	auth?: { flow?: { start: infer TStart } };
+}
+	? TStart extends (...args: infer TArgs) => unknown
+		? TArgs extends [unknown]
+			? unknown
+			: {
+					"auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+				}
+		: unknown
+	: unknown;
+
 export interface ProviderConfig<
 	TOperations extends Record<string, ProviderOperation>,
 > {
@@ -362,6 +374,23 @@ function validateProviderShape(config: unknown): void {
 			VALID_AUTH_MODES,
 			String(config.id),
 		);
+	if (
+		auth &&
+		typeof auth === "object" &&
+		"flow" in auth &&
+		auth.flow &&
+		typeof auth.flow === "object" &&
+		"start" in auth.flow &&
+		typeof auth.flow.start === "function" &&
+		auth.flow.start.length > 1
+	) {
+		throw new ProviderError(
+			`Provider "${String(config.id)}" auth.flow.start must not declare an input parameter`,
+			{
+				fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
+			},
+		);
+	}
 	const access = config.access;
 	if (access !== undefined) {
 		if (!access || typeof access !== "object" || Array.isArray(access)) {
@@ -1096,6 +1125,7 @@ const HEALTH_CHECK_CASE_FIELDS = new Set([
 	"name",
 	"description",
 	"input",
+	"prepareInput",
 	"assertions",
 	"degradedThresholdMs",
 	"timeoutMs",
@@ -1371,6 +1401,10 @@ function validateHealthCheckCase(
 				fix: `Set ${fieldPath}.assertions to (ctx) => { ... } that throws on failure.`,
 			},
 		);
+	if (c.prepareInput !== undefined && typeof c.prepareInput !== "function")
+		throw new ValidationError(
+			`Provider "${providerId}" ${fieldPath}.prepareInput must be a function.`,
+		);
 	if (
 		c.degradedThresholdMs !== undefined &&
 		(typeof c.degradedThresholdMs !== "number" ||
@@ -2198,13 +2232,14 @@ function validateOperationFixtures(
 
 export function defineProvider<
 	TOperations extends Record<string, ProviderOperation>,
+	TConfig extends ProviderConfig<TOperations>,
 >(
-	config: ProviderConfig<TOperations>,
+	config: TConfig & AuthStartNoInputGuard<TConfig>,
 ): ProviderDefinition & { operations: OperationMapConfig<TOperations> } {
 	validateProviderShape(config);
 	if (!CONNECTOR_ID_REGEX.test(config.id))
 		throw new ProviderError(`Invalid provider id: "${config.id}"`, {
-			fix: 'Use lowercase alphanumeric with dashes, e.g., "airkorea-realtime"',
+			fix: 'Use lowercase alphanumeric with dashes, e.g., "korea-air-quality"',
 		});
 	if (Object.keys(config.operations).length === 0)
 		throw new ProviderError(

package/src/errors.ts

@@ -48,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;
 };

package/src/i18n/catalog.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import type { AuthTurn } from "../types";
 import {
 	getProviderLocalePath,
 	isProviderLocaleValue,
@@ -57,6 +58,161 @@ export function resolveProviderLocaleValue(
 	);
 }
 
+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[];