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

package/src/observability.ts

@@ -1,4 +1,5 @@
-export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-05-26";
+// Mirrors packages/provider-observability in the platform monorepo (SoT).
+export const PROVIDER_OBSERVABILITY_TAXONOMY_VERSION = "2026-08-07";
 
 export const PROVIDER_ERROR_CATEGORIES = [
 	"ok",
@@ -7,6 +8,7 @@ export const PROVIDER_ERROR_CATEGORIES = [
 	"upstream_http",
 	"upstream_rate_limited",
 	"upstream_auth",
+	"upstream_rejected",
 	"upstream_schema_drift",
 	"proxy_pool",
 	"anti_bot_blocked",
@@ -16,6 +18,9 @@ export const PROVIDER_ERROR_CATEGORIES = [
 	"output_validation",
 	"provider_error",
 	"internal_error",
+	"dependency_unavailable",
+	"unsupported_transport",
+	"client_cancelled",
 	"unclassified",
 ] as const;
 
@@ -26,6 +31,9 @@ export function categoryForStatus(status: number): ProviderErrorCategory {
 	if (status === 408 || status === 504) return "timeout";
 	if (status === 429) return "upstream_rate_limited";
 	if (status === 401 || status === 403) return "upstream_auth";
+	// provider-error-contract: 409/410/422 are the deterministic
+	// upstream-rejection status class — not a retryable upstream failure.
+	if (status === 409 || status === 410 || status === 422) return "upstream_rejected";
 	if (status >= 400) return "upstream_http";
 	return "unclassified";
 }
@@ -39,3 +47,45 @@ export function isRetryableCategory(category: ProviderErrorCategory): boolean {
 		category === "proxy_pool"
 	);
 }
+
+// Who stopped the request (honest-provider-error-contract). A deliberately
+// small public projection of the internal taxonomy:
+// - client: the request itself is fixable by the caller
+// - upstream_rule: the upstream service refused it under its own business
+//   rules (deterministic) or rate limits
+// - upstream_failure: the upstream service malfunctioned — retryable
+// - apifuse: an APIFuse-side fault (provider bug, platform dependency)
+export const PROVIDER_ERROR_SOURCES = [
+	"client",
+	"upstream_rule",
+	"upstream_failure",
+	"apifuse",
+] as const;
+
+export type ProviderErrorSource = (typeof PROVIDER_ERROR_SOURCES)[number];
+
+export function sourceForCategory(category: ProviderErrorCategory): ProviderErrorSource {
+	switch (category) {
+		case "input_validation":
+		case "credential_expired":
+		case "credential_unavailable":
+		case "client_cancelled":
+			return "client";
+		case "upstream_rejected":
+		case "upstream_rate_limited":
+			return "upstream_rule";
+		case "timeout":
+		case "network":
+		case "upstream_http":
+		case "upstream_auth":
+		case "upstream_schema_drift":
+		case "anti_bot_blocked":
+			return "upstream_failure";
+		default:
+			// ok never reaches error serialization; provider_error,
+			// internal_error, output_validation, proxy_pool,
+			// dependency_unavailable, unsupported_transport, unclassified are
+			// APIFuse-side faults.
+			return "apifuse";
+	}
+}

package/src/provider.ts

@@ -3,7 +3,7 @@ export {
 	credentialsAuthChallenge,
 	createAuthFlowHelpers,
 	defineCredentialsAuth,
-} from "./auth";
+} from "./auth.js";
 export type {
 	CredentialsAuthChallengeDefinition,
 	CredentialsAuthChallengeRequest,
@@ -16,8 +16,8 @@ export type {
 	CredentialsAuthLoginResult,
 	DefineCredentialsAuthOptions,
 	DefinedCredentialsAuth,
-} from "./auth";
-export { createFormCeremony } from "./ceremonies";
+} from "./auth.js";
+export { createFormCeremony } from "./ceremonies/index.js";
 export {
 	assertFreshProviderChoiceIssuedAt,
 	createProviderChoiceToken,
@@ -25,7 +25,7 @@ export {
 	type ProviderChoiceTokenErrorReason,
 	type ProviderChoiceTokenPayload,
 	parseProviderChoiceToken,
-} from "./choice-token";
+} from "./choice-token.js";
 export {
 	centered,
 	delayed,
@@ -34,9 +34,10 @@ export {
 	defineProvider,
 	defineSmsOtpMatcher,
 	every,
-} from "./define";
+} from "./define.js";
 export {
 	AuthError,
+	HttpRedirectError,
 	isProviderError,
 	isSessionExpiredError,
 	isTransportError,
@@ -44,18 +45,19 @@ export {
 	SessionExpiredError,
 	TransportError,
 	ValidationError,
-} from "./errors";
+} from "./errors.js";
 export {
 	getProviderLocalePath,
 	providerLocaleKey,
 	qualifyProviderLocaleKey,
-} from "./i18n";
+} from "./i18n/index.js";
 export {
 	type CreateProviderChoiceContextOptions,
 	createProviderChoiceContext,
 	createTestProviderChoiceContext,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-} from "./runtime/choice";
+	PROVIDER_RUNTIME_CHOICE_WORD_ISSUANCE_ENV,
+} from "./runtime/choice.js";
 export {
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
@@ -72,7 +74,7 @@ export {
 	type SensitivePath,
 	sensitive,
 	z,
-} from "./schema";
+} from "./schema.js";
 export type {
 	AuthAbortData,
 	AuthAbortRetry,
@@ -91,14 +93,38 @@ export type {
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
 	HealthScheduleRandomization,
+	HttpRedirectFailureReason,
+	HttpRedirectPolicy,
+	HttpRedirectPolicyMode,
 	HttpRetryOptions,
 	HttpRetrySummary,
 	InferSchemaOutput,
+	NativeContext,
+	NativeNetworkClient,
+	NativeNetworkCloseReason,
+	NativeNetworkConnection,
+	NativeNetworkConnectInput,
+	NativeNetworkConnectOptions,
+	NativeNetworkDynamicGrantOptions,
+	NativeNetworkEgressGrant,
+	NativeProviderConfig,
+	NativeProviderContext,
+	NativeProxyDrainHandler,
+	NativeProxyEgressInfo,
+	NativeProxyExpiringEvent,
+	NativeProxyExpiringReason,
+	NativeTcpDynamicEgressRule,
+	NativeTcpEgressGrant,
+	NativeTcpEgressRule,
+	NativeTcpPortRange,
+	NativeTcpTlsMode,
+	NativeTlsConnectOptions,
 	OperationApprovalPolicy,
 	OperationContractMetadata,
 	OperationDefinition,
 	OperationDocMeta,
 	OperationErrorCode,
+	ProviderErrorStatus,
 	OperationInputExample,
 	OperationLifecycle,
 	OperationObservabilityConfig,
@@ -110,34 +136,63 @@ export type {
 	OperationTransport,
 	ProviderAccessVisibility,
 	ProviderChoiceBindingOptions,
+	ProviderChoiceConsumeMode,
+	ProviderChoiceConsumeResult,
 	ProviderChoiceContext,
+	ProviderChoiceExplicitParseResult,
 	ProviderChoiceIssueOptions,
 	ProviderChoiceParseOptions,
 	ProviderContext,
 	ProviderDefinition,
+	ProviderDeploymentOverrides,
+	ProviderFileRef,
+	ProviderFilesContext,
 	ProviderLocale,
 	ProviderLocaleKey,
 	ProviderLocaleKeyInput,
 	ProviderLogoProfile,
 	ProviderProxyPolicy,
+	ProxiedOAuthConfig,
 	ProviderPublicConnectionMode,
 	ProviderPublicProfile,
+	ProviderResolvedFile,
 	ProviderRuntimeState,
 	ProviderStateDurationString,
 	ProviderStateNamespace,
 	ProviderSupportLevel,
+	RedirectRunReason,
 	SchemaLike,
 	SmsOtpMatcherDefinition,
 	StandardSchemaV1,
 	StateCasResult,
 	StateNamespaceOptions,
+	StateNamespaceScope,
 	StateValue,
 	StateWriteOptions,
-} from "./types";
+} from "./types.js";
+export {
+	NativeEgressGrantExpiredError,
+	NativeEgressNotDeclaredError,
+	NativeIdleTimeoutError,
+	NativeNetworkError,
+	NativeProxyExpiredError,
+} from "./runtime/native-network-errors.js";
+export type {
+	NativeGatewayProxy,
+	NativeGatewayProxyResolutionInput,
+	NativeGatewayProxySkipReason,
+	NativeGatewayProxySynthesizer,
+	NativeGatewayProxySynthesisResult,
+	NativeGatewayProxySynthesisInput,
+	NativeNetworkClientOptions,
+	NativeNetworkErrorCode,
+	VendorCredentialLookup,
+	VendorCredentialResolver,
+} from "./runtime/native-network.js";
 export {
 	HttpRetryAfterPolicy,
 	HttpRetryDelayStrategy,
 	HttpRetryJitter,
 	HttpRetryPreset,
 	HttpRetryUnsafeMethodPolicy,
-} from "./types";
+} from "./types.js";

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

@@ -1,6 +1,6 @@
 import type { ZodType } from "zod";
 
-import type { LintDiagnostic } from "./lint";
+import type { LintDiagnostic } from "./lint.js";
 
 type SchemaLike = ZodType & {
 	def?: Record<string, unknown>;
@@ -55,8 +55,7 @@ function isSchemaRecord(value: unknown): value is Record<string, SchemaLike> {
 }
 
 function getObjectShape(schema: SchemaLike): Record<string, SchemaLike> {
-	const rawShape =
-		typeof schema.shape === "function" ? schema.shape() : schema.shape;
+	const rawShape = typeof schema.shape === "function" ? schema.shape() : schema.shape;
 	if (isSchemaRecord(rawShape)) {
 		return rawShape;
 	}
@@ -69,10 +68,7 @@ function getObjectShape(schema: SchemaLike): Record<string, SchemaLike> {
 	return isSchemaRecord(defShape) ? defShape : {};
 }
 
-function appendSchemaChildren(
-	children: SchemaLike[],
-	value: unknown,
-): SchemaLike[] {
+function appendSchemaChildren(children: SchemaLike[], value: unknown): SchemaLike[] {
 	if (isSchema(value)) {
 		children.push(value);
 		return children;
@@ -183,26 +179,14 @@ function collectPublicSchemaFieldDiagnostics(
 			});
 		}
 		diagnostics.push(
-			...collectPublicSchemaFieldDiagnostics(
-				providerId,
-				operationId,
-				child,
-				fieldPath,
-				seen,
-			),
+			...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,
-			),
+			...collectPublicSchemaFieldDiagnostics(providerId, operationId, child, childPath, seen),
 		);
 	}
 
@@ -221,17 +205,7 @@ export function lintPublicSchemaFieldNames(
 	}
 
 	return [
-		...collectPublicSchemaFieldDiagnostics(
-			providerId,
-			operationId,
-			input,
-			"input",
-		),
-		...collectPublicSchemaFieldDiagnostics(
-			providerId,
-			operationId,
-			output,
-			"output",
-		),
+		...collectPublicSchemaFieldDiagnostics(providerId, operationId, input, "input"),
+		...collectPublicSchemaFieldDiagnostics(providerId, operationId, output, "output"),
 	];
 }

package/src/recipes/gov-api.ts

@@ -1,4 +1,4 @@
-import { unwrapEnvelope } from "../utils/parse";
+import { unwrapEnvelope } from "../utils/parse.js";
 
 function getResultCode(raw: unknown): string | undefined {
 	if (!raw || typeof raw !== "object") {
@@ -33,10 +33,7 @@ export function checkResultCode(
  * Replace placeholder values with null
  * e.g., nullIfPlaceholder('해당없음', ['해당없음', '-', '']) → null
  */
-export function nullIfPlaceholder(
-	v: unknown,
-	patterns: string[],
-): unknown | null {
+export function nullIfPlaceholder(v: unknown, patterns: string[]): unknown | null {
 	if (v === null || v === undefined) {
 		return null;
 	}

package/src/runtime/auth-flow.ts

@@ -1,14 +1,17 @@
-import { ContextAccessError } from "../errors";
-import { createAuthFlowHelpers } from "../auth";
+import { ContextAccessError } from "../errors.js";
+import { createAuthFlowHelpers } from "../auth.js";
 import type {
 	ContextScratchpad,
 	EnvContext,
 	FlowContext,
 	HttpClient,
+	OcrContext,
 	StealthClient,
 	SttContext,
-} from "../types";
-import { createUnsupportedSttClient } from "./stt";
+} from "../types.js";
+import { createUnsupportedOcrClient } from "./ocr.js";
+import { createUnsupportedResolverClient } from "./resolver-shared.js";
+import { createUnsupportedSttClient } from "./stt.js";
 
 function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
 	return new Set(allowedKeys.filter((key) => key.trim().length > 0));
@@ -16,9 +19,7 @@ function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {
 
 function assertAllowedKey(allowedKeys: Set<string>, key: string): void {
 	if (!allowedKeys.has(key)) {
-		throw new ContextAccessError(
-			`Context key "${key}" is not declared in context.keys.`,
-		);
+		throw new ContextAccessError(`Context key "${key}" is not declared in context.keys.`);
 	}
 }
 
@@ -50,6 +51,7 @@ export function createScratchpad(
 }
 
 export function createFlowContext(options: {
+	flowId?: string;
 	http: HttpClient;
 	stealth: StealthClient;
 	env: EnvContext;
@@ -59,9 +61,11 @@ export function createFlowContext(options: {
 	externalRef?: string;
 	allowedKeys: string[];
 	initialContext?: Record<string, unknown>;
+	ocr?: OcrContext;
 	stt?: SttContext;
 }): FlowContext {
 	return {
+		flowId: options.flowId,
 		connectionId: options.connectionId,
 		externalRef: options.externalRef,
 		tenantId: options.tenantId,
@@ -70,7 +74,9 @@ export function createFlowContext(options: {
 		stealth: options.stealth,
 		env: options.env,
 		context: createScratchpad(options.allowedKeys, options.initialContext),
+		ocr: options.ocr ?? createUnsupportedOcrClient(),
 		stt: options.stt ?? createUnsupportedSttClient(),
+		resolver: createUnsupportedResolverClient("Resolver is not available in auth flow context"),
 		auth: createAuthFlowHelpers(),
 	};
 }