@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.31

package/src/contract-serialization.ts

@@ -6,8 +6,8 @@ import {
 	isRecord,
 	type JsonValue,
 	toJsonValue,
-} from "./contract-json";
-import type { SchemaLike } from "./types";
+} from "./contract-json.js";
+import type { SchemaLike } from "./types.js";
 
 export function describeSchema(schema: SchemaLike): JsonValue {
 	if (isZodSchema(schema)) {
@@ -17,10 +17,7 @@ export function describeSchema(schema: SchemaLike): JsonValue {
 			vendor: "zod",
 			typeName: getSchemaTypeName(schema),
 			jsonSchema,
-			jsonSchemaHash:
-				jsonSchema === undefined
-					? undefined
-					: digest(canonicalJson(jsonSchema)),
+			jsonSchemaHash: jsonSchema === undefined ? undefined : digest(canonicalJson(jsonSchema)),
 		});
 	}
 	const standard = isRecord(schema) ? schema["~standard"] : undefined;
@@ -30,8 +27,7 @@ export function describeSchema(schema: SchemaLike): JsonValue {
 			standard: "standard-schema-v1",
 			vendor: typeof standard.vendor === "string" ? standard.vendor : "unknown",
 			version:
-				typeof standard.version === "number" ||
-				typeof standard.version === "string"
+				typeof standard.version === "number" || typeof standard.version === "string"
 					? standard.version
 					: undefined,
 		});
@@ -43,9 +39,7 @@ export function describeSchema(schema: SchemaLike): JsonValue {
 	});
 }
 
-export function serializeSmsMatcher(
-	value: Record<string, unknown>,
-): Record<string, unknown> {
+export function serializeSmsMatcher(value: Record<string, unknown>): Record<string, unknown> {
 	const code = value.code;
 	if (!isRecord(code)) return value;
 	const pattern = code.pattern;
@@ -70,14 +64,12 @@ 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 zodJsonSchema(schema: ZodType): JsonValue {
+	const jsonSchema = toJsonValue(z.toJSONSchema(schema));
+	if (jsonSchema === undefined) {
+		throw new TypeError("z.toJSONSchema() returned a non-JSON value");
 	}
+	return jsonSchema;
 }
 
 function getSchemaTypeName(schema: SchemaLike): string | undefined {

package/src/contract-types.ts

@@ -1,5 +1,5 @@
-import type { JsonValue } from "./contract-json";
-import type { ProviderDefinition } from "./types";
+import type { JsonValue } from "./contract-json.js";
+import type { ProviderDefinition } from "./types.js";
 
 export const PROVIDER_CONTRACT_SCHEMA_VERSION = "2026-06-23";
 
@@ -13,6 +13,7 @@ export interface ProviderContractSnapshot {
 	readonly allowedHosts?: readonly string[];
 	readonly stealth?: JsonValue;
 	readonly proxy?: JsonValue;
+	readonly ocr?: JsonValue;
 	readonly stt?: JsonValue;
 	readonly browser?: JsonValue;
 	readonly auth?: JsonValue;

package/src/contract.ts

@@ -6,13 +6,13 @@ import {
 	type JsonPrimitive,
 	type JsonValue,
 	toJsonValue,
-} from "./contract-json";
-import { describeSchema, serializeSmsMatcher } from "./contract-serialization";
+} from "./contract-json.js";
+import { describeSchema, serializeSmsMatcher } from "./contract-serialization.js";
 import {
 	PROVIDER_CONTRACT_SCHEMA_VERSION,
 	type ProviderContractOperation,
 	type ProviderContractSnapshot,
-} from "./contract-types";
+} from "./contract-types.js";
 import type {
 	HealthCheckSuite,
 	HealthCheckUnsupported,
@@ -20,7 +20,7 @@ import type {
 	OperationDefinition,
 	OperationTransport,
 	ProviderDefinition,
-} from "./types";
+} from "./types.js";
 
 export {
 	canonicalJson,
@@ -31,12 +31,11 @@ export {
 	type ProviderContractSnapshot,
 };
 
-export function extractProviderContract(
-	provider: ProviderDefinition,
-): ProviderContractSnapshot {
+export function extractProviderContract(provider: ProviderDefinition): ProviderContractSnapshot {
 	const auth = extractAuth(provider.auth);
 	const stealth = toJsonValue(provider.stealth);
 	const proxy = toJsonValue(provider.proxy);
+	const ocr = toJsonValue(provider.ocr);
 	const stt = toJsonValue(provider.stt);
 	const browser = toJsonValue(provider.browser);
 	const reviewed = toJsonValue(provider.reviewed);
@@ -57,14 +56,11 @@ export function extractProviderContract(
 		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() }
-			: {}),
+			.map(([operationId, operation]) => extractOperation(operationId, operation)),
+		...(provider.allowedHosts ? { allowedHosts: [...provider.allowedHosts].sort() } : {}),
 		...(stealth === undefined ? {} : { stealth }),
 		...(proxy === undefined ? {} : { proxy }),
+		...(ocr === undefined ? {} : { ocr }),
 		...(stt === undefined ? {} : { stt }),
 		...(browser === undefined ? {} : { browser }),
 		...(auth === undefined ? {} : { auth }),
@@ -78,9 +74,7 @@ export function extractProviderContract(
 	};
 }
 
-export function digestProviderContract(
-	snapshot: ProviderContractSnapshot,
-): string {
+export function digestProviderContract(snapshot: ProviderContractSnapshot): string {
 	return createHash("sha256").update(canonicalJson(snapshot)).digest("hex");
 }
 
@@ -105,9 +99,7 @@ function extractOperation(
 	const upstream = toJsonValue(operation.upstream);
 	const hints = toJsonValue(operation.hints);
 	const healthCheck = extractHealthCheck(operation.healthCheck);
-	const healthCheckUnsupported = extractHealthCheckUnsupported(
-		operation.healthCheckUnsupported,
-	);
+	const healthCheckUnsupported = extractHealthCheckUnsupported(operation.healthCheckUnsupported);
 
 	return {
 		id: operationId,
@@ -149,9 +141,7 @@ function extractAuth(value: ProviderDefinition["auth"]): JsonValue | undefined {
 	});
 }
 
-function extractTransport(
-	value: OperationTransport | undefined,
-): JsonValue | undefined {
+function extractTransport(value: OperationTransport | undefined): JsonValue | undefined {
 	if (!value) return undefined;
 	if (value.kind !== "sse") return toJsonValue(value);
 	return compactObject({
@@ -164,9 +154,7 @@ function extractTransport(
 	});
 }
 
-function extractHealthCheck(
-	value: HealthCheckSuite | undefined,
-): JsonValue | undefined {
+function extractHealthCheck(value: HealthCheckSuite | undefined): JsonValue | undefined {
 	if (!value) return undefined;
 	return compactObject({
 		interval: value.interval,
@@ -204,9 +192,7 @@ function extractHealthJourney(value: HealthJourneyDefinition): JsonValue {
 		cooldown: value.cooldown,
 		smsMatchers: toJsonValue(
 			value.smsMatchers?.map((matcher) =>
-				serializeSmsMatcher(
-					copyRecordWithout(matcher, new Set(["extractOtp"])),
-				),
+				serializeSmsMatcher(copyRecordWithout(matcher, new Set(["extractOtp"]))),
 			),
 		),
 		requiredSecrets: toJsonValue(value.requiredSecrets),

package/src/declaration-validation.ts

@@ -0,0 +1,202 @@
+import { describeSchema } from "./contract-serialization.js";
+import { ProviderError } from "./errors.js";
+import type {
+	HealthJourneyDefinition,
+	ProviderDefinition,
+	ProviderProxyPolicy,
+	ProviderProxyProvider,
+} from "./types.js";
+
+export const DECLARATION_INVALID_CODE = "DECLARATION_INVALID";
+
+export const DECLARATION_RULE_IDS = {
+	challengeShape: "credentials-challenge-shape",
+	journeyExecutable: "health-journey-executable",
+	schemaSerializable: "operation-schema-serializable",
+	proxyExplicitPolicy: "proxy-explicit-policy",
+	proxyVendorExclusive: "proxy-vendor-fields-exclusive",
+	proxyNoMixedVendors: "proxy-no-mixed-vendors",
+	proxySmartproxyGeo: "proxy-smartproxy-country-only",
+	operationUpstreamProxy: "operation-upstream-proxy-unsupported",
+} as const;
+
+export type DeclarationRuleId =
+	(typeof DECLARATION_RULE_IDS)[keyof typeof DECLARATION_RULE_IDS];
+
+export type DeclarationViolation = {
+	ruleId: DeclarationRuleId;
+	path: string;
+	message: string;
+	fix: string;
+};
+
+export function declarationInvalidError(
+	violations: readonly DeclarationViolation[],
+): ProviderError {
+	const summary = violations
+		.map((violation) => `${violation.path} [${violation.ruleId}]: ${violation.message}`)
+		.join("\n");
+	return new ProviderError(
+		`Provider declaration is invalid (${violations.length} violation${violations.length === 1 ? "" : "s"}).${summary ? `\n${summary}` : ""}`,
+		{
+			code: DECLARATION_INVALID_CODE,
+			details: { violations: [...violations] },
+			fix: "Apply every violation's fix hint, then validate the declaration again.",
+		},
+	);
+}
+
+/** Enforces declaration rules whose runtime behavior would otherwise fail open. */
+export function validateFailClosedDeclaration(provider: ProviderDefinition): void {
+	const violations: DeclarationViolation[] = [];
+	validateHealthDeclaration(provider, violations);
+	validateSchemaDeclaration(provider, violations);
+	validateProxyDeclaration(provider, violations);
+	validateOperationDeclaration(provider, violations);
+	if (violations.length > 0) throw declarationInvalidError(violations);
+}
+
+function validateHealthDeclaration(
+	provider: ProviderDefinition,
+	violations: DeclarationViolation[],
+): void {
+	for (const [index, journey] of (provider.healthJourneys ?? []).entries()) {
+		if (!journey || typeof journey !== "object") continue;
+		if (typeof journey.run !== "function") {
+			const journeyPath = healthJourneyPath(journey, index);
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.journeyExecutable,
+				path: `${journeyPath}.run`,
+				message: "coversOperations cannot provide health coverage without executable run logic.",
+				fix: `Add an async run(ctx) implementation to ${journeyPath}.`,
+			});
+		}
+	}
+
+	// NOTE: healthCheck.cases[].enabled is intentionally NOT validated here.
+	// self-test.ts reports a gated case as status "skipped" with skipReason
+	// "disabled", so the skip is visible in results rather than silent — it is a
+	// supported conditional-execution feature, not a class-1 silent no-op.
+}
+
+function healthJourneyPath(journey: HealthJourneyDefinition, index: number): string {
+	return typeof journey.id === "string" && journey.id.length > 0
+		? `healthJourneys.${journey.id}`
+		: `healthJourneys[${index}]`;
+}
+
+function validateSchemaDeclaration(
+	provider: ProviderDefinition,
+	violations: DeclarationViolation[],
+): void {
+	for (const [operationId, operation] of Object.entries(provider.operations ?? {})) {
+		const schemaEntries: Array<[string, unknown]> = [
+			[`operations.${operationId}.input`, operation.input],
+			[`operations.${operationId}.output`, operation.output],
+		];
+		// SSE event schemas reach contract extraction the same way input/output do,
+		// so a transform-bearing event schema would abort extraction at runtime while
+		// passing declaration checks. Validate them under the same rule.
+		const transport = operation.transport;
+		if (transport?.kind === "sse") {
+			for (const [eventName, eventSchema] of Object.entries(transport.events ?? {})) {
+				schemaEntries.push([
+					`operations.${operationId}.transport.events.${eventName}`,
+					eventSchema,
+				]);
+			}
+		}
+		for (const [path, schema] of schemaEntries) {
+			try {
+				describeSchema(schema as Parameters<typeof describeSchema>[0]);
+			} catch (error) {
+				const reason = error instanceof Error ? error.message : String(error);
+				violations.push({
+					ruleId: DECLARATION_RULE_IDS.schemaSerializable,
+					path,
+					message: `schema conversion to JSON Schema failed: ${reason}`,
+					fix: `Replace unsupported constructs in ${path} so z.toJSONSchema() succeeds.`,
+				});
+			}
+		}
+	}
+}
+
+const MANAGED_PROXY_VENDORS = new Set<ProviderProxyProvider>(["smartproxy", "nodemaven"]);
+const STATIC_PROXY_VENDORS = new Set<ProviderProxyProvider>(["custom", "decodo"]);
+
+function validateProxyDeclaration(
+	provider: ProviderDefinition,
+	violations: DeclarationViolation[],
+): void {
+	if (provider.proxy === true) {
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.proxyExplicitPolicy,
+			path: "proxy",
+			message: "proxy: true does not require resolvable proxy egress.",
+			fix: 'Replace proxy: true with an explicit policy such as proxy: { mode: "required", providers: ["smartproxy"] }.',
+		});
+		return;
+	}
+	if (!provider.proxy || typeof provider.proxy !== "object") return;
+
+	const policy = provider.proxy as ProviderProxyPolicy;
+	const hasProvider = policy.provider !== undefined;
+	const hasProviders = policy.providers !== undefined;
+	if (hasProvider && hasProviders) {
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.proxyVendorExclusive,
+			path: "proxy",
+			message: "provider and providers are ambiguous when declared together.",
+			fix: "Keep either proxy.provider or proxy.providers, and remove the other field.",
+		});
+	}
+
+	const vendors = declaredProxyVendors(policy);
+	if (
+		vendors.some((vendor) => MANAGED_PROXY_VENDORS.has(vendor)) &&
+		vendors.some((vendor) => STATIC_PROXY_VENDORS.has(vendor))
+	) {
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.proxyNoMixedVendors,
+			path: hasProviders ? "proxy.providers" : "proxy.provider",
+			message: "managed and deprecated static proxy vendors cannot share a chain.",
+			fix: "Use only smartproxy/nodemaven vendors, or only deprecated static markers, in one policy.",
+		});
+	}
+
+	if (vendors.includes("smartproxy")) {
+		for (const field of ["subdivision", "city"] as const) {
+			if (policy.geo?.[field] === undefined) continue;
+			const path = `proxy.geo.${field}`;
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.proxySmartproxyGeo,
+				path,
+				message: `smartproxy cannot honor ${field}-level geo targeting.`,
+				fix: `Remove ${path} or use a vendor chain that can honor it.`,
+			});
+		}
+	}
+}
+
+function declaredProxyVendors(policy: ProviderProxyPolicy): ProviderProxyProvider[] {
+	const vendors = [...(policy.providers ?? [])];
+	if (policy.provider !== undefined) vendors.push(policy.provider);
+	return vendors;
+}
+
+function validateOperationDeclaration(
+	provider: ProviderDefinition,
+	violations: DeclarationViolation[],
+): void {
+	for (const [operationId, operation] of Object.entries(provider.operations ?? {})) {
+		if (!operation.upstream?.proxy) continue;
+		const path = `operations.${operationId}.upstream.proxy`;
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.operationUpstreamProxy,
+			path,
+			message: "operation-level proxy policy is not wired into operation execution.",
+			fix: `Remove ${path} and declare the effective policy at provider.proxy.`,
+		});
+	}
+}