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

package/src/lint.ts

@@ -1,5 +1,11 @@
 import type { ZodType } from "zod";
 
+import { lintPublicSchemaFieldNames } from "./public-schema-field-lint";
+import {
+	APIFUSE_DESCRIPTION_KEY_META_KEY,
+	APIFUSE_SENSITIVE_META_KEY,
+} from "./schema";
+
 type AuthModeLike =
 	| "none"
 	| "platform-managed"
@@ -17,10 +23,15 @@ type ProviderAuthLike = {
 	};
 };
 
+type ProviderContractMetaLike = {
+	publicSchemaFieldNames?: "normalized";
+};
+
 type SchemaLike = ZodType & {
 	description?: string;
 	def?: Record<string, unknown>;
 	_def?: Record<string, unknown>;
+	meta?: () => Record<string, unknown> | undefined;
 	shape?: Record<string, SchemaLike> | (() => Record<string, SchemaLike>);
 	element?: SchemaLike;
 	items?: SchemaLike[];
@@ -43,7 +54,7 @@ export interface LintDiagnostic {
 
 function lintAllowedHosts(
 	providerId: string | undefined,
-	allowedHosts: string[] | undefined,
+	allowedHosts: readonly string[] | undefined,
 ): LintDiagnostic[] {
 	const prefix = providerId ? `Provider "${providerId}"` : "Provider";
 
@@ -103,7 +114,7 @@ function lintReviewed(
 	];
 }
 
-function hasReusableSecretKeys(keys: string[] | undefined): boolean {
+function hasReusableSecretKeys(keys: readonly string[] | undefined): boolean {
 	if (!keys) {
 		return false;
 	}
@@ -143,12 +154,12 @@ function lintAuthModel(provider: {
 	id?: string;
 	auth?: ProviderAuthLike;
 	credential?: {
-		keys?: string[];
+		keys?: readonly string[];
 		storesReusableSecret?: boolean;
 		justification?: string;
 	};
 	context?: {
-		keys?: string[];
+		keys?: readonly string[];
 	};
 	authFlowSource?: string;
 }): LintDiagnostic[] {
@@ -359,7 +370,60 @@ function getChildSchemas(
 	}));
 }
 
-function collectMissingDescriptions(
+function uniqueFields(fields: string[]): string[] {
+	return Array.from(new Set(fields));
+}
+
+function isSensitiveSchema(schema: unknown): boolean {
+	if (!schema || typeof schema !== "object" || !("meta" in schema)) {
+		return false;
+	}
+	const meta = schema.meta;
+	if (typeof meta !== "function") return false;
+	const metadata = meta.call(schema);
+	return (
+		!!metadata &&
+		typeof metadata === "object" &&
+		Reflect.get(metadata, APIFUSE_SENSITIVE_META_KEY) === true
+	);
+}
+
+function getSchemaMetadata(schema: SchemaLike): Record<string, unknown> {
+	return schema.meta?.() ?? {};
+}
+
+function getSchemaDescriptionKey(schema: SchemaLike): string | undefined {
+	const value = Reflect.get(
+		getSchemaMetadata(schema),
+		APIFUSE_DESCRIPTION_KEY_META_KEY,
+	);
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+const SENSITIVE_FIELD_NAMES = new Set([
+	"apikey",
+	"authorization",
+	"cookie",
+	"secret",
+	"secrets",
+	"token",
+	"accesstoken",
+	"refreshtoken",
+	"password",
+	"passwd",
+	"otp",
+	"otpcode",
+	"phone",
+	"phonenumber",
+	"paymenturl",
+]);
+
+function isSensitiveFieldName(name: string): boolean {
+	const normalized = name.toLowerCase().replace(/[-_\s]/g, "");
+	return SENSITIVE_FIELD_NAMES.has(normalized);
+}
+
+function collectUnmarkedSensitiveFields(
 	schema: unknown,
 	basePath: string,
 	seen = new Set<SchemaLike>(),
@@ -367,13 +431,80 @@ function collectMissingDescriptions(
 	if (!isSchema(schema) || seen.has(schema)) {
 		return [];
 	}
+	seen.add(schema);
+	const out: string[] = [];
+	for (const [key, child] of Object.entries(getObjectShape(schema))) {
+		const childPath = basePath ? `${basePath}.${key}` : key;
+		if (isSensitiveFieldName(key) && !isSensitiveSchema(child)) {
+			out.push(childPath);
+		}
+		out.push(...collectUnmarkedSensitiveFields(child, childPath, seen));
+	}
+	for (const child of getChildSchemas(schema)) {
+		if (Object.hasOwn(getObjectShape(schema), child.key)) continue;
+		const isWrapperNode = [
+			"unwrap",
+			"innerType",
+			"sourceType",
+			"schema",
+			"type",
+			"in",
+			"out",
+			"option",
+			"pipe",
+			"payload",
+			"item",
+			"rest",
+			"catchall",
+			"keyType",
+			"valueType",
+		].includes(child.key);
+		const childPath =
+			child.key === "element" || child.key.startsWith("element.")
+				? `${basePath}[]`
+				: isWrapperNode || child.key.startsWith("pipe.")
+					? basePath
+					: basePath
+						? `${basePath}.${child.key}`
+						: child.key;
+		out.push(...collectUnmarkedSensitiveFields(child.schema, childPath, seen));
+	}
+	return out;
+}
+
+function collectSchemaDescriptionKeyDiagnostics(
+	schema: unknown,
+	basePath: string,
+	seen = new Set<SchemaLike>(),
+	requireCurrentDescription = true,
+): LintDiagnostic[] {
+	if (!isSchema(schema) || seen.has(schema)) {
+		return [];
+	}
 
 	seen.add(schema);
-	const missing: string[] = [];
+	const diagnostics: LintDiagnostic[] = [];
 	const currentPath = basePath || "schema";
+	const hasDescriptionKey = getSchemaDescriptionKey(schema) !== undefined;
 
-	if (!schema.description) {
-		missing.push(currentPath);
+	if (schema.description && !hasDescriptionKey) {
+		diagnostics.push({
+			rule: "schema-description-raw-prose",
+			level: "error",
+			field: currentPath,
+			message: `Schema field "${currentPath}" must use .describeKey() or describeKey() instead of raw static prose.`,
+		});
+	}
+
+	if (requireCurrentDescription && !hasDescriptionKey) {
+		diagnostics.push({
+			rule: "schema-description-key-required",
+			level: "error",
+			field: currentPath,
+			message: schema.description
+				? `Schema field "${currentPath}" has a raw description but is missing .describeKey() or describeKey() metadata.`
+				: `Schema field "${currentPath}" is missing .describeKey() or describeKey() metadata.`,
+		});
 	}
 
 	for (const child of getChildSchemas(schema)) {
@@ -383,30 +514,42 @@ function collectMissingDescriptions(
 			"sourceType",
 			"schema",
 			"type",
+			"in",
+			"out",
 			"option",
 			"pipe",
 			"payload",
 			"item",
 			"rest",
 			"catchall",
+			"keyType",
+			"valueType",
 		].includes(child.key);
+		const isStructuralNode =
+			isWrapperNode ||
+			child.key.startsWith("pipe.") ||
+			child.key === "element" ||
+			child.key.startsWith("element.");
 		const childPath = isWrapperNode
 			? currentPath
 			: currentPath === "schema"
 				? child.key
 				: /^\d+$/.test(child.key)
 					? `${currentPath}[${child.key}]`
-					: child.key.startsWith("element")
+					: child.key === "element" || child.key.startsWith("element.")
 						? `${currentPath}[]`
 						: `${currentPath}.${child.key}`;
-		missing.push(...collectMissingDescriptions(child.schema, childPath, seen));
+		diagnostics.push(
+			...collectSchemaDescriptionKeyDiagnostics(
+				child.schema,
+				childPath,
+				seen,
+				!isStructuralNode,
+			),
+		);
 	}
 
-	return missing;
-}
-
-function uniqueFields(fields: string[]): string[] {
-	return Array.from(new Set(fields));
+	return diagnostics;
 }
 
 function isComplexSchema(
@@ -438,60 +581,124 @@ function hasBidirectionalFixtures(fixtures: unknown): boolean {
 	return "request" in fixtures && "response" in fixtures;
 }
 
+function getOperationSource(operation: {
+	handler?: unknown;
+	source?: string;
+}): string {
+	if (operation.source) {
+		return operation.source;
+	}
+	return typeof operation.handler === "function"
+		? operation.handler.toString()
+		: "";
+}
+
+function lintStealthTransportUsage(provider: {
+	id?: string;
+	stealth?: unknown;
+	operations?: Record<string, { handler?: unknown; source?: string }>;
+}): LintDiagnostic[] {
+	if (provider.stealth || !provider.operations) {
+		return [];
+	}
+
+	const providerLabel = provider.id ? `Provider "${provider.id}"` : "Provider";
+	return Object.entries(provider.operations).flatMap(
+		([operationKey, operation]) => {
+			const source = getOperationSource(operation);
+			if (!/\bctx\.stealth\b/.test(source)) {
+				return [];
+			}
+			return [
+				{
+					rule: "stealth-config-required",
+					level: "error" as const,
+					field: `operations.${operationKey}`,
+					message: `${providerLabel} operation "${operationKey}" uses ctx.stealth but provider.stealth is not declared.`,
+				},
+			];
+		},
+	);
+}
+
 export function lintOperation(op: {
-	description: string;
+	description?: string;
+	descriptionKey?: string;
+	whenToUse?: readonly string[];
+	whenToUseKeys?: readonly string[];
+	whenNotToUse?: readonly string[];
+	whenNotToUseKeys?: readonly string[];
 	input: unknown;
 	output: unknown;
 	fixtures?: unknown;
-	inputExamples?: unknown[];
+	inputExamples?: readonly unknown[];
 	derivations?: Record<string, string>;
 }): LintDiagnostic[] {
 	const diagnostics: LintDiagnostic[] = [];
 	const description = op.description ?? "";
+	const hasDescriptionKey =
+		typeof op.descriptionKey === "string" && op.descriptionKey.length > 0;
 
-	if (description.length < 150) {
+	if (description.trim().length > 0 && !hasDescriptionKey) {
 		diagnostics.push({
-			rule: "description-min-length",
+			rule: "operation-description-raw-prose",
 			level: "error",
 			field: "description",
-			message: "Operation description must be at least 150 characters.",
+			message:
+				"Operation description must use descriptionKey instead of raw static prose.",
 		});
 	}
 
-	const lowerDescription = description.toLowerCase();
-	if (
-		!(lowerDescription.includes("use") && lowerDescription.includes("when"))
-	) {
+	if (!hasDescriptionKey && description.length < 150) {
 		diagnostics.push({
-			rule: "description-has-when-clause",
-			level: "warn",
+			rule: "description-min-length",
+			level: "error",
 			field: "description",
-			message: 'Operation description should include both "use" and "when".',
+			message: "Operation description must be at least 150 characters.",
 		});
 	}
 
-	for (const field of uniqueFields(
-		collectMissingDescriptions(op.input, "input"),
-	)) {
+	if ((op.whenToUse?.length ?? 0) > 0 && !(op.whenToUseKeys?.length ?? 0)) {
 		diagnostics.push({
-			rule: "all-fields-described",
+			rule: "operation-when-to-use-raw-prose",
 			level: "error",
-			field,
-			message: `Schema field "${field}" is missing a description.`,
+			field: "whenToUse",
+			message:
+				"Operation whenToUse must use whenToUseKeys instead of raw static prose.",
 		});
 	}
 
-	for (const field of uniqueFields(
-		collectMissingDescriptions(op.output, "output"),
-	)) {
+	if (
+		(op.whenNotToUse?.length ?? 0) > 0 &&
+		!(op.whenNotToUseKeys?.length ?? 0)
+	) {
 		diagnostics.push({
-			rule: "all-fields-described",
+			rule: "operation-when-not-to-use-raw-prose",
 			level: "error",
-			field,
-			message: `Schema field "${field}" is missing a description.`,
+			field: "whenNotToUse",
+			message:
+				"Operation whenNotToUse must use whenNotToUseKeys instead of raw static prose.",
 		});
 	}
 
+	const lowerDescription = description.toLowerCase();
+	if (
+		!hasDescriptionKey &&
+		!(lowerDescription.includes("use") && lowerDescription.includes("when"))
+	) {
+		diagnostics.push({
+			rule: "description-has-when-clause",
+			level: "warn",
+			field: "description",
+			message: 'Operation description should include both "use" and "when".',
+		});
+	}
+
+	diagnostics.push(
+		...collectSchemaDescriptionKeyDiagnostics(op.input, "input"),
+		...collectSchemaDescriptionKeyDiagnostics(op.output, "output"),
+	);
+
 	if (!hasBidirectionalFixtures(op.fixtures)) {
 		diagnostics.push({
 			rule: "fixtures-both-directions",
@@ -511,39 +718,73 @@ export function lintOperation(op: {
 		});
 	}
 
+	for (const field of uniqueFields(
+		collectUnmarkedSensitiveFields(op.input, "input"),
+	)) {
+		diagnostics.push({
+			rule: "sensitive-field-unmarked",
+			level: "warn",
+			field,
+			message: `Schema field "${field}" looks sensitive; mark it with fields.*(), field(..., { sensitive: true }), or sensitive(...).`,
+		});
+	}
+
+	for (const field of uniqueFields(
+		collectUnmarkedSensitiveFields(op.output, "output"),
+	)) {
+		diagnostics.push({
+			rule: "sensitive-field-unmarked",
+			level: "warn",
+			field,
+			message: `Schema field "${field}" looks sensitive; mark it with fields.*(), field(..., { sensitive: true }), or sensitive(...).`,
+		});
+	}
+
 	return diagnostics;
 }
 
 export function lintProvider(provider: {
 	id?: string;
-	allowedHosts?: string[];
+	allowedHosts?: readonly string[];
+	stealth?: unknown;
 	auth?: ProviderAuthLike;
 	credential?: {
-		keys?: string[];
+		keys?: readonly string[];
 		storesReusableSecret?: boolean;
 		justification?: string;
 	};
 	context?: {
-		keys?: string[];
+		keys?: readonly string[];
 	};
 	authFlowSource?: string;
 	operations?: Record<
 		string,
 		{
 			description?: string;
+			descriptionKey?: string;
+			whenToUse?: readonly string[];
+			whenToUseKeys?: readonly string[];
+			whenNotToUse?: readonly string[];
+			whenNotToUseKeys?: readonly string[];
 			input: unknown;
 			output: unknown;
 			fixtures?: unknown;
-			inputExamples?: unknown[];
+			inputExamples?: readonly unknown[];
 			derivations?: Record<string, string>;
+			handler?: unknown;
+			source?: string;
 		}
 	>;
+	meta?: {
+		contract?: ProviderContractMetaLike;
+	};
 	reviewed?: string;
 }): LintDiagnostic[] {
 	const diagnostics: LintDiagnostic[] = [
 		...lintAllowedHosts(provider.id, provider.allowedHosts),
 		...lintReviewed(provider.id, provider.reviewed),
 		...lintAuthModel(provider),
+		...lintStealthTransportUsage(provider),
 	];
 
 	if (!provider.operations) {
@@ -553,14 +794,28 @@ export function lintProvider(provider: {
 	diagnostics.push(
 		...Object.entries(provider.operations).flatMap(
 			([operationKey, operation]) =>
-				lintOperation({
-					description: operation.description ?? "",
-					input: operation.input,
-					output: operation.output,
-					fixtures: operation.fixtures,
-					inputExamples: operation.inputExamples,
-					derivations: operation.derivations,
-				}).map((diagnostic) => ({
+				[
+					...lintOperation({
+						description: operation.description ?? "",
+						descriptionKey: operation.descriptionKey,
+						whenToUse: operation.whenToUse,
+						whenToUseKeys: operation.whenToUseKeys,
+						whenNotToUse: operation.whenNotToUse,
+						whenNotToUseKeys: operation.whenNotToUseKeys,
+						input: operation.input,
+						output: operation.output,
+						fixtures: operation.fixtures,
+						inputExamples: operation.inputExamples,
+						derivations: operation.derivations,
+					}),
+					...lintPublicSchemaFieldNames(
+						provider.id,
+						operationKey,
+						operation.input,
+						operation.output,
+						provider.meta?.contract?.publicSchemaFieldNames === "normalized",
+					),
+				].map((diagnostic) => ({
 					...diagnostic,
 					field: diagnostic.field
 						? `operations.${operationKey}.${diagnostic.field}`

package/src/observability.ts

@@ -0,0 +1,41 @@
+export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-05-26";
+
+export const PROVIDER_ERROR_CATEGORIES = [
+	"ok",
+	"timeout",
+	"network",
+	"upstream_http",
+	"upstream_rate_limited",
+	"upstream_auth",
+	"upstream_schema_drift",
+	"proxy_pool",
+	"anti_bot_blocked",
+	"credential_expired",
+	"credential_unavailable",
+	"input_validation",
+	"output_validation",
+	"provider_error",
+	"internal_error",
+	"unclassified",
+] as const;
+
+export type ProviderErrorCategory = (typeof PROVIDER_ERROR_CATEGORIES)[number];
+
+export function categoryForStatus(status: number): ProviderErrorCategory {
+	if (status >= 200 && status < 400) return "ok";
+	if (status === 408 || status === 504) return "timeout";
+	if (status === 429) return "upstream_rate_limited";
+	if (status === 401 || status === 403) return "upstream_auth";
+	if (status >= 400) return "upstream_http";
+	return "unclassified";
+}
+
+export function isRetryableCategory(category: ProviderErrorCategory): boolean {
+	return (
+		category === "timeout" ||
+		category === "network" ||
+		category === "upstream_rate_limited" ||
+		category === "upstream_http" ||
+		category === "proxy_pool"
+	);
+}

package/src/provider.ts

@@ -1,13 +1,70 @@
-export { z } from "zod";
-
 export { createFormCeremony } from "./ceremonies";
-export { defineOperation, defineProvider } from "./define";
+export {
+	assertFreshProviderChoiceIssuedAt,
+	createProviderChoiceToken,
+	ProviderChoiceTokenError,
+	type ProviderChoiceTokenErrorReason,
+	type ProviderChoiceTokenPayload,
+	parseProviderChoiceToken,
+} from "./choice-token";
+export {
+	defineHealthJourney,
+	defineOperation,
+	defineProvider,
+	defineSmsOtpMatcher,
+	every,
+} from "./define";
 export { AuthError, ProviderError, ValidationError } from "./errors";
+export { providerLocaleKey, qualifyProviderLocaleKey } from "./i18n";
+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 type {
 	FlowContext,
+	HealthJourneyDefinition,
+	HealthJourneyEventContext,
+	HealthJourneyManualTriggerPolicy,
+	HealthJourneyRunContext,
+	HealthJourneyRunResult,
+	HttpRetryOptions,
+	HttpRetrySummary,
 	InferSchemaOutput,
 	OperationDefinition,
+	OperationObservabilityConfig,
+	OperationObservabilitySensitiveConfig,
+	OperationSensitivePath,
 	ProviderContext,
+	ProviderLocaleKeyInput,
+	ProviderProxyPolicy,
+	ProviderRuntimeState,
+	ProviderStateDurationString,
+	ProviderStateNamespace,
 	SchemaLike,
+	SmsOtpMatcherDefinition,
 	StandardSchemaV1,
+	StateCasResult,
+	StateNamespaceOptions,
+	StateValue,
+	StateWriteOptions,
+} from "./types";
+export {
+	HttpRetryAfterPolicy,
+	HttpRetryDelayStrategy,
+	HttpRetryJitter,
+	HttpRetryPreset,
+	HttpRetryUnsafeMethodPolicy,
 } from "./types";