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

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),
+	});
+}