@apifuse/provider-sdk 2.1.0-beta.2 → 2.1.0-beta.21

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,140 @@
-export { z } from "zod";
-
+export {
+	AuthAbortError,
+	credentialsAuthChallenge,
+	createAuthFlowHelpers,
+	defineCredentialsAuth,
+} from "./auth";
+export type {
+	CredentialsAuthChallengeDefinition,
+	CredentialsAuthChallengeRequest,
+	CredentialsAuthCompleteResult,
+	CredentialsAuthCredential,
+	CredentialsAuthField,
+	CredentialsAuthFields,
+	CredentialsAuthFieldType,
+	CredentialsAuthInput,
+	CredentialsAuthLoginResult,
+	DefineCredentialsAuthOptions,
+	DefinedCredentialsAuth,
+} from "./auth";
 export { createFormCeremony } from "./ceremonies";
-export { defineOperation, defineProvider } from "./define";
-export { AuthError, ProviderError, ValidationError } from "./errors";
+export {
+	assertFreshProviderChoiceIssuedAt,
+	createProviderChoiceToken,
+	ProviderChoiceTokenError,
+	type ProviderChoiceTokenErrorReason,
+	type ProviderChoiceTokenPayload,
+	parseProviderChoiceToken,
+} from "./choice-token";
+export {
+	centered,
+	delayed,
+	defineHealthJourney,
+	defineOperation,
+	defineProvider,
+	defineSmsOtpMatcher,
+	every,
+} from "./define";
+export {
+	AuthError,
+	ProviderError,
+	SessionExpiredError,
+	TransportError,
+	ValidationError,
+} from "./errors";
+export {
+	getProviderLocalePath,
+	providerLocaleKey,
+	qualifyProviderLocaleKey,
+} from "./i18n";
+export {
+	type CreateProviderChoiceContextOptions,
+	createProviderChoiceContext,
+	createTestProviderChoiceContext,
+	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+} from "./runtime/choice";
+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 {
+	AuthAbortData,
+	AuthAbortRetry,
+	AuthFlowTerminalContext,
+	AuthMode,
+	AuthSafeData,
+	AuthSafeJson,
 	FlowContext,
+	HealthCheckAssertionContext,
+	HealthCheckCase,
+	HealthCheckSuite,
+	HealthCheckUnsupported,
+	HealthJourneyDefinition,
+	HealthJourneyEventContext,
+	HealthJourneyManualTriggerPolicy,
+	HealthJourneyRunContext,
+	HealthJourneyRunResult,
+	HealthScheduleRandomization,
+	HttpRetryOptions,
+	HttpRetrySummary,
 	InferSchemaOutput,
+	OperationApprovalPolicy,
+	OperationContractMetadata,
 	OperationDefinition,
+	OperationDocMeta,
+	OperationErrorCode,
+	OperationInputExample,
+	OperationLifecycle,
+	OperationObservabilityConfig,
+	OperationObservabilitySensitiveConfig,
+	OperationRelationships,
+	OperationRiskClass,
+	OperationSensitivePath,
+	OperationToolRouterMetadata,
+	OperationTransport,
+	ProviderAccessVisibility,
+	ProviderChoiceBindingOptions,
+	ProviderChoiceContext,
+	ProviderChoiceIssueOptions,
+	ProviderChoiceParseOptions,
 	ProviderContext,
+	ProviderDefinition,
+	ProviderLocale,
+	ProviderLocaleKey,
+	ProviderLocaleKeyInput,
+	ProviderLogoProfile,
+	ProviderProxyPolicy,
+	ProviderPublicConnectionMode,
+	ProviderPublicProfile,
+	ProviderRuntimeState,
+	ProviderStateDurationString,
+	ProviderStateNamespace,
+	ProviderSupportLevel,
 	SchemaLike,
+	SmsOtpMatcherDefinition,
 	StandardSchemaV1,
+	StateCasResult,
+	StateNamespaceOptions,
+	StateValue,
+	StateWriteOptions,
+} from "./types";
+export {
+	HttpRetryAfterPolicy,
+	HttpRetryDelayStrategy,
+	HttpRetryJitter,
+	HttpRetryPreset,
+	HttpRetryUnsafeMethodPolicy,
 } from "./types";

package/src/public-schema-field-lint.ts

@@ -0,0 +1,237 @@
+import type { ZodType } from "zod";
+
+import type { LintDiagnostic } from "./lint";
+
+type SchemaLike = ZodType & {
+	def?: Record<string, unknown>;
+	_def?: Record<string, unknown>;
+	shape?: Record<string, SchemaLike> | (() => Record<string, SchemaLike>);
+	element?: SchemaLike;
+	items?: SchemaLike[];
+	options?: SchemaLike[] | Set<SchemaLike> | Map<string, SchemaLike>;
+	innerType?: SchemaLike;
+	sourceType?: () => SchemaLike;
+	unwrap?: () => SchemaLike;
+	in?: SchemaLike;
+	out?: SchemaLike;
+	left?: SchemaLike;
+	right?: SchemaLike;
+};
+
+const ESTABLISHED_APIFUSE_PROTOCOL_FIELDS = new Set(["externalRef"]);
+
+const UPSTREAM_FIELD_REPLACEMENTS = new Map<string, string>([
+	["display", "limit"],
+	["start", "offset"],
+	["sort", "sort_by"],
+	["lprice", "lowest_price"],
+	["hprice", "highest_price"],
+	["mallName", "mall_name"],
+	["productId", "product_id"],
+	["productType", "product_type_code"],
+	["lastBuildDate", "upstream_generated_at"],
+	["meta", "summary"],
+]);
+
+function isSchema(value: unknown): value is SchemaLike {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		"safeParse" in value &&
+		typeof value.safeParse === "function"
+	);
+}
+
+function getSchemaDef(schema: SchemaLike): Record<string, unknown> {
+	const def = schema.def ?? schema._def;
+	return def && typeof def === "object" ? def : {};
+}
+
+function isSchemaRecord(value: unknown): value is Record<string, SchemaLike> {
+	if (!value || typeof value !== "object") {
+		return false;
+	}
+	return Object.values(value).every(isSchema);
+}
+
+function getObjectShape(schema: SchemaLike): Record<string, SchemaLike> {
+	const rawShape =
+		typeof schema.shape === "function" ? schema.shape() : schema.shape;
+	if (isSchemaRecord(rawShape)) {
+		return rawShape;
+	}
+
+	const defShape = getSchemaDef(schema).shape;
+	if (typeof defShape === "function") {
+		const resolved = defShape();
+		return isSchemaRecord(resolved) ? resolved : {};
+	}
+	return isSchemaRecord(defShape) ? defShape : {};
+}
+
+function appendSchemaChildren(
+	children: SchemaLike[],
+	value: unknown,
+): SchemaLike[] {
+	if (isSchema(value)) {
+		children.push(value);
+		return children;
+	}
+	if (Array.isArray(value)) {
+		children.push(...value.filter(isSchema));
+		return children;
+	}
+	if (value instanceof Set) {
+		children.push(...Array.from(value).filter(isSchema));
+		return children;
+	}
+	if (value instanceof Map) {
+		children.push(...Array.from(value.values()).filter(isSchema));
+		return children;
+	}
+	return children;
+}
+
+function safeSourceType(schema: SchemaLike): SchemaLike | undefined {
+	try {
+		return schema.sourceType?.();
+	} catch {
+		return undefined;
+	}
+}
+
+function safeUnwrap(schema: SchemaLike): SchemaLike | undefined {
+	try {
+		return schema.unwrap?.();
+	} catch {
+		return undefined;
+	}
+}
+
+function getTransparentChildSchemas(schema: SchemaLike): SchemaLike[] {
+	const def = getSchemaDef(schema);
+	const children: SchemaLike[] = [];
+	for (const value of [
+		schema.element,
+		schema.items,
+		schema.options,
+		schema.innerType,
+		safeSourceType(schema),
+		safeUnwrap(schema),
+		schema.in,
+		schema.out,
+		schema.left,
+		schema.right,
+		def.schema,
+		def.innerType,
+		def.type,
+		def.valueType,
+		def.item,
+		def.items,
+		def.rest,
+		def.catchall,
+		def.option,
+		def.options,
+		def.pipe,
+		def.payload,
+		def.sourceType,
+		def.left,
+		def.right,
+	]) {
+		appendSchemaChildren(children, value);
+	}
+	return children;
+}
+
+function recommendedReplacement(fieldName: string): string | undefined {
+	if (/^category\d+$/.test(fieldName)) {
+		return "category_path";
+	}
+	if (UPSTREAM_FIELD_REPLACEMENTS.has(fieldName)) {
+		return UPSTREAM_FIELD_REPLACEMENTS.get(fieldName);
+	}
+	if (/[a-z][A-Z]/.test(fieldName)) {
+		return fieldName.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+	}
+	return undefined;
+}
+
+function collectPublicSchemaFieldDiagnostics(
+	providerId: string,
+	operationId: string,
+	schema: unknown,
+	basePath: string,
+	seen = new Set<SchemaLike>(),
+): LintDiagnostic[] {
+	if (!isSchema(schema) || seen.has(schema)) {
+		return [];
+	}
+
+	seen.add(schema);
+	const diagnostics: LintDiagnostic[] = [];
+	for (const [fieldName, child] of Object.entries(getObjectShape(schema))) {
+		const fieldPath = `${basePath}.${fieldName}`;
+		const replacement = ESTABLISHED_APIFUSE_PROTOCOL_FIELDS.has(fieldName)
+			? undefined
+			: recommendedReplacement(fieldName);
+		if (replacement) {
+			diagnostics.push({
+				rule: "public-schema-upstream-field",
+				level: "error",
+				field: fieldPath,
+				message: `Provider "${providerId}" operation "${operationId}" public schema field "${fieldPath}" uses upstream-shaped field "${fieldName}"; use APIFuse field "${replacement}" instead.`,
+			});
+		}
+		diagnostics.push(
+			...collectPublicSchemaFieldDiagnostics(
+				providerId,
+				operationId,
+				child,
+				fieldPath,
+				seen,
+			),
+		);
+	}
+
+	for (const child of getTransparentChildSchemas(schema)) {
+		const childPath = schema.element === child ? `${basePath}[]` : basePath;
+		diagnostics.push(
+			...collectPublicSchemaFieldDiagnostics(
+				providerId,
+				operationId,
+				child,
+				childPath,
+				seen,
+			),
+		);
+	}
+
+	return diagnostics;
+}
+
+export function lintPublicSchemaFieldNames(
+	providerId: string | undefined,
+	operationId: string,
+	input: unknown,
+	output: unknown,
+	enforce: boolean,
+): LintDiagnostic[] {
+	if (!providerId || !enforce) {
+		return [];
+	}
+
+	return [
+		...collectPublicSchemaFieldDiagnostics(
+			providerId,
+			operationId,
+			input,
+			"input",
+		),
+		...collectPublicSchemaFieldDiagnostics(
+			providerId,
+			operationId,
+			output,
+			"output",
+		),
+	];
+}

package/src/runtime/auth-flow.ts

@@ -1,10 +1,14 @@
 import { ContextAccessError } from "../errors";
+import { createAuthFlowHelpers } from "../auth";
 import type {
 	ContextScratchpad,
 	EnvContext,
 	FlowContext,
 	HttpClient,
+	StealthClient,
+	SttContext,
 } from "../types";
+import { createUnsupportedSttClient } from "./stt";
 
 function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
 	return new Set(allowedKeys.filter((key) => key.trim().length > 0));
@@ -47,6 +51,7 @@ export function createScratchpad(
 
 export function createFlowContext(options: {
 	http: HttpClient;
+	stealth: StealthClient;
 	env: EnvContext;
 	tenantId: string;
 	providerId: string;
@@ -54,6 +59,7 @@ export function createFlowContext(options: {
 	externalRef?: string;
 	allowedKeys: string[];
 	initialContext?: Record<string, unknown>;
+	stt?: SttContext;
 }): FlowContext {
 	return {
 		connectionId: options.connectionId,
@@ -61,7 +67,10 @@ export function createFlowContext(options: {
 		tenantId: options.tenantId,
 		providerId: options.providerId,
 		http: options.http,
+		stealth: options.stealth,
 		env: options.env,
 		context: createScratchpad(options.allowedKeys, options.initialContext),
+		stt: options.stt ?? createUnsupportedSttClient(),
+		auth: createAuthFlowHelpers(),
 	};
 }