@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.50

package/src/contract-serialization.ts

@@ -64,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

@@ -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;
@@ -29,17 +30,23 @@ export interface ProviderContractSnapshot {
 
 export interface ProviderContractOperation {
 	readonly id: string;
+	readonly connectionMode?: JsonValue;
+	readonly connectionExternalRefParam?: JsonValue;
+	readonly riskClass: JsonValue;
+	readonly approval?: JsonValue;
+	readonly timeoutMs?: JsonValue;
+	readonly titleKey?: JsonValue;
 	readonly descriptionKey?: JsonValue;
-	readonly docs?: JsonValue;
+	readonly summaryKey?: JsonValue;
+	readonly markdownKey?: JsonValue;
 	readonly whenToUseKeys?: JsonValue;
 	readonly whenNotToUseKeys?: JsonValue;
-	readonly derivations?: JsonValue;
-	readonly inputExamples?: JsonValue;
-	readonly annotations?: JsonValue;
+	readonly normalizationNotesKeys?: JsonValue;
+	readonly errorCodes?: JsonValue;
+	readonly examples?: JsonValue;
 	readonly contract?: JsonValue;
 	readonly tags?: JsonValue;
 	readonly relatedOperations?: JsonValue;
-	readonly toolRouter?: JsonValue;
 	readonly observability?: JsonValue;
 	readonly transport?: JsonValue;
 	readonly inputSchema: JsonValue;

package/src/contract.ts

@@ -35,6 +35,7 @@ export function extractProviderContract(provider: ProviderDefinition): ProviderC
 	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);
@@ -59,6 +60,7 @@ export function extractProviderContract(provider: ProviderDefinition): ProviderC
 		...(provider.allowedHosts ? { allowedHosts: [...provider.allowedHosts].sort() } : {}),
 		...(stealth === undefined ? {} : { stealth }),
 		...(proxy === undefined ? {} : { proxy }),
+		...(ocr === undefined ? {} : { ocr }),
 		...(stt === undefined ? {} : { stt }),
 		...(browser === undefined ? {} : { browser }),
 		...(auth === undefined ? {} : { auth }),
@@ -80,17 +82,22 @@ function extractOperation(
 	operationId: string,
 	operation: OperationDefinition,
 ): ProviderContractOperation {
+	const connectionMode = toJsonValue(operation.connectionMode);
+	const connectionExternalRefParam = toJsonValue(operation.connectionExternalRefParam);
+	const approval = toJsonValue(operation.approval);
+	const timeoutMs = toJsonValue(operation.timeoutMs);
+	const titleKey = toJsonValue(operation.titleKey);
 	const descriptionKey = toJsonValue(operation.descriptionKey);
-	const docs = toJsonValue(operation.docs);
+	const summaryKey = toJsonValue(operation.summaryKey);
+	const markdownKey = toJsonValue(operation.markdownKey);
 	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 normalizationNotesKeys = toJsonValue(operation.normalizationNotesKeys);
+	const errorCodes = toJsonValue(operation.errorCodes);
+	const examples = toJsonValue(operation.examples);
 	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);
@@ -103,17 +110,23 @@ function extractOperation(
 		id: operationId,
 		inputSchema: describeSchema(operation.input),
 		outputSchema: describeSchema(operation.output),
+		...(connectionMode === undefined ? {} : { connectionMode }),
+		...(connectionExternalRefParam === undefined ? {} : { connectionExternalRefParam }),
+		riskClass: operation.riskClass,
+		...(approval === undefined ? {} : { approval }),
+		...(timeoutMs === undefined ? {} : { timeoutMs }),
+		...(titleKey === undefined ? {} : { titleKey }),
 		...(descriptionKey === undefined ? {} : { descriptionKey }),
-		...(docs === undefined ? {} : { docs }),
+		...(summaryKey === undefined ? {} : { summaryKey }),
+		...(markdownKey === undefined ? {} : { markdownKey }),
 		...(whenToUseKeys === undefined ? {} : { whenToUseKeys }),
 		...(whenNotToUseKeys === undefined ? {} : { whenNotToUseKeys }),
-		...(derivations === undefined ? {} : { derivations }),
-		...(inputExamples === undefined ? {} : { inputExamples }),
-		...(annotations === undefined ? {} : { annotations }),
+		...(normalizationNotesKeys === undefined ? {} : { normalizationNotesKeys }),
+		...(errorCodes === undefined ? {} : { errorCodes }),
+		...(examples === undefined ? {} : { examples }),
 		...(contract === undefined ? {} : { contract }),
 		...(tags === undefined ? {} : { tags }),
 		...(relatedOperations === undefined ? {} : { relatedOperations }),
-		...(toolRouter === undefined ? {} : { toolRouter }),
 		...(observability === undefined ? {} : { observability }),
 		...(transport === undefined ? {} : { transport }),
 		...(fixtures === undefined ? {} : { fixtures }),
@@ -165,6 +178,7 @@ function extractHealthCheck(value: HealthCheckSuite | undefined): JsonValue | un
 				name: item.name,
 				description: item.description,
 				input: toJsonValue(item.input),
+				scenario: toJsonValue(item.scenario),
 				degradedThresholdMs: item.degradedThresholdMs,
 				timeoutMs: item.timeoutMs,
 				expectedStatus: item.expectedStatus,

package/src/declaration-validation.ts

@@ -0,0 +1,330 @@
+import { describeSchema } from "./contract-serialization.js";
+import { ProviderError } from "./errors.js";
+import { HealthScenarioSchema } from "./health-scenario.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",
+	journeyRunScenarioExclusive: "health-journey-run-scenario-exclusive",
+	journeyScenarioValid: "health-journey-scenario-valid",
+	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",
+	pinnedWireFieldPathValid: "public-schema-pinned-wire-field-valid",
+} 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);
+	validatePinnedWireFieldPaths(provider, violations);
+	validateSchemaDeclaration(provider, violations);
+	validateProxyDeclaration(provider, violations);
+	validateOperationDeclaration(provider, violations);
+	if (violations.length > 0) throw declarationInvalidError(violations);
+}
+
+type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "meta" | "proxy">;
+type OperationDeclarationRulesInput = Pick<ProviderDefinition, "operations">;
+
+/** Enforces fail-closed rules that only depend on the provider declaration. */
+export function validateFailClosedProviderDeclaration(
+	provider: ProviderDeclarationRulesInput,
+): void {
+	const violations: DeclarationViolation[] = [];
+	collectProviderDeclarationViolations(provider, violations);
+	if (violations.length > 0) throw declarationInvalidError(violations);
+}
+
+/** Enforces fail-closed rules that depend on the operation implementation. */
+export function validateFailClosedOperationDeclaration(
+	provider: OperationDeclarationRulesInput,
+): void {
+	const violations: DeclarationViolation[] = [];
+	collectOperationDeclarationViolations(provider, violations);
+	if (violations.length > 0) throw declarationInvalidError(violations);
+}
+
+function collectProviderDeclarationViolations(
+	provider: ProviderDeclarationRulesInput,
+	violations: DeclarationViolation[],
+): void {
+	validateHealthDeclaration(provider, violations);
+	validatePinnedWireFieldPaths(provider, violations);
+	validateProxyDeclaration(provider, violations);
+}
+
+function validatePinnedWireFieldPaths(
+	provider: ProviderDeclarationRulesInput,
+	violations: DeclarationViolation[],
+): void {
+	const pins = provider.meta?.contract?.pinnedWireFieldPaths;
+	if (pins === undefined) return;
+
+	if (!Array.isArray(pins)) {
+		violations.push({
+			ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+			path: "meta.contract.pinnedWireFieldPaths",
+			message: "pinned wire field paths must be an array.",
+			fix: "Declare a readonly array of { path, reason } entries.",
+		});
+		return;
+	}
+
+	const seenPaths = new Set<string>();
+	for (const [index, pin] of pins.entries()) {
+		const entryPath = `meta.contract.pinnedWireFieldPaths[${index}]`;
+		if (!pin || typeof pin !== "object" || Array.isArray(pin)) {
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+				path: entryPath,
+				message: "each pinned wire field path must be an object.",
+				fix: `Replace ${entryPath} with { path: "operations.<operation-id>.<field-path>", reason: "<non-empty reason>" }.`,
+			});
+			continue;
+		}
+
+		const path = "path" in pin ? pin.path : undefined;
+		const reason = "reason" in pin ? pin.reason : undefined;
+		if (typeof path !== "string" || path.trim().length === 0) {
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+				path: `${entryPath}.path`,
+				message: "path must be a non-empty string.",
+				fix: `Set ${entryPath}.path to the exact public-schema-upstream-field diagnostic path.`,
+			});
+		} else if (seenPaths.has(path)) {
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+				path: `${entryPath}.path`,
+				message: `duplicate pinned wire field path ${JSON.stringify(path)}.`,
+				fix: `Keep exactly one declaration for ${JSON.stringify(path)}.`,
+			});
+		} else {
+			seenPaths.add(path);
+		}
+
+		if (typeof reason !== "string" || reason.trim().length === 0) {
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.pinnedWireFieldPathValid,
+				path: `${entryPath}.reason`,
+				message: "reason must be a non-empty string.",
+				fix: `Document why renaming the exact wire field would break the upstream contract.`,
+			});
+		}
+	}
+}
+
+function collectOperationDeclarationViolations(
+	provider: OperationDeclarationRulesInput,
+	violations: DeclarationViolation[],
+): void {
+	validateSchemaDeclaration(provider, violations);
+	validateOperationDeclaration(provider, violations);
+}
+
+function validateHealthDeclaration(
+	provider: ProviderDeclarationRulesInput,
+	violations: DeclarationViolation[],
+): void {
+	for (const [index, journey] of (provider.healthJourneys ?? []).entries()) {
+		if (!journey || typeof journey !== "object") continue;
+		const hasRun = journey.run !== undefined;
+		const hasScenario = journey.scenario !== undefined;
+		if (hasRun && hasScenario) {
+			const journeyPath = healthJourneyPath(journey, index);
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.journeyRunScenarioExclusive,
+				path: journeyPath,
+				message: "A health journey must declare exactly one of run or scenario, not both.",
+				fix: `Remove either ${journeyPath}.run or ${journeyPath}.scenario.`,
+			});
+		}
+		if (!hasRun && !hasScenario) {
+			const journeyPath = healthJourneyPath(journey, index);
+			violations.push({
+				ruleId: DECLARATION_RULE_IDS.journeyExecutable,
+				path: `${journeyPath}.run`,
+				message:
+					"coversOperations cannot provide health coverage without run or a declarative scenario.",
+				fix: `Add an async run(ctx) implementation or a valid scenario to ${journeyPath}.`,
+			});
+		}
+		if (hasScenario) {
+			const parsed = HealthScenarioSchema.safeParse(journey.scenario);
+			if (!parsed.success) {
+				const journeyPath = healthJourneyPath(journey, index);
+				violations.push({
+					ruleId: DECLARATION_RULE_IDS.journeyScenarioValid,
+					path: `${journeyPath}.scenario`,
+					message: "scenario must conform to HealthScenario.",
+					fix: "Build the scenario with defineHealthScenario().",
+				});
+			}
+		}
+	}
+
+	// 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: OperationDeclarationRulesInput,
+	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: ProviderDeclarationRulesInput,
+	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: OperationDeclarationRulesInput,
+	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.`,
+		});
+	}
+}