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

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

@@ -35,16 +35,123 @@ export {
 	defineSmsOtpMatcher,
 	every,
 } from "./define.js";
+export type {
+	OperationDefinitionFor,
+	ProviderBuilder,
+	ProviderContextOf,
+	ProviderDeclaration,
+	ProviderDefinitionFor,
+} from "./define.js";
+export type { JsonPrimitive, JsonValue } from "./contract-json.js";
+export {
+	AssertionExpressionSchema,
+	AssertionPredicateSchema,
+	AssertStepSchema,
+	BoundedJsonPathSchema,
+	CandidateBlockSchema,
+	CandidatePolicySchema,
+	CredentialRefDeclarationSchema,
+	defineHealthScenario,
+	HealthScenarioSchema,
+	HealthStepSchema,
+	ExtractStepSchema,
+	FindFirstSchema,
+	GuardStepSchema,
+	JournalPolicySchema,
+	JsonTemplateSchema,
+	ManualTriggerPolicySchema,
+	OperandSchema,
+	OperationStepSchema,
+	QuantifierSchema,
+	ReferenceSchema,
+	RetryPolicySchema,
+	SafeRegexSchema,
+	ScopedAssertionExpressionSchema,
+	ScopedAssertionPredicateSchema,
+	ScopedItemReferenceSchema,
+	ScopedOperandSchema,
+	StepReferenceSchema,
+	RelativeDateNodeSchema,
+	ValueTypeSchema,
+} from "./health-scenario.js";
+export type {
+	AssertionExpression,
+	AssertionPredicate,
+	AttemptReference,
+	AssertResult,
+	AssertStep,
+	BoundedJsonPath,
+	CandidateBlock,
+	CandidatePolicy,
+	CandidateReference,
+	CredentialReference,
+	CredentialRefDeclaration,
+	EstablishedConnectionReference,
+	ExtractStep,
+	FindFirst,
+	GuardAttribution,
+	GuardReasonCode,
+	GuardResult,
+	GuardStep,
+	HealthScenario,
+	HealthStep,
+	JsonTemplate,
+	JournalPolicy,
+	ManualTriggerPolicy,
+	NonEmpty,
+	OperationResult,
+	OperationStep,
+	Operand,
+	Quantifier,
+	ReferenceNode,
+	Reference,
+	RelativeDateNode,
+	RetryPolicy,
+	SafeRegex,
+	ScopedAssertionExpression,
+	ScopedAssertionPredicate,
+	ScopedItemReference,
+	ScopedOperand,
+	StepBase,
+	StepReference,
+	ExtractResult,
+	ValueType,
+} from "./health-scenario.js";
 export {
 	AuthError,
+	HttpRedirectError,
 	isProviderError,
 	isSessionExpiredError,
 	isTransportError,
 	ProviderError,
+	type ProviderErrorObservability,
 	SessionExpiredError,
 	TransportError,
 	ValidationError,
 } from "./errors.js";
+export {
+	createProviderEnvironment,
+	createInProcessProviderEngine,
+	ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES,
+	ENGINE_OWNED_TELEMETRY_ENV_NAMES,
+	isEngineOwnedEnvName,
+	isEngineOwnedProxyCredentialName,
+	isEngineOwnedTelemetryEnvName,
+	PROVIDER_CAPABILITY_KEYS,
+	PROVIDER_ENGINE_PROTOCOL_VERSION,
+	readEngineProxyCredentials,
+} from "./engine.js";
+export type {
+	ProviderCapabilityKey,
+	ProviderEngine,
+	ProviderEngineAttachmentInput,
+	ProviderEngineBindingCandidates,
+	ProviderEngineCapabilitySurface,
+	ProviderEngineRequest,
+	ProviderEngineResidentSurface,
+	ProviderEngineSession,
+	ProviderEngineTransport,
+} from "./engine.js";
 export {
 	getProviderLocalePath,
 	providerLocaleKey,
@@ -91,50 +198,101 @@ export type {
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
 	HealthScheduleRandomization,
+	HttpRedirectFailureReason,
+	HttpRedirectPolicy,
+	HttpRedirectPolicyMode,
 	HttpRetryOptions,
 	HttpRetrySummary,
 	InferSchemaOutput,
+	NativeContext,
+	NativeNetworkClient,
+	NativeNetworkCloseReason,
+	NativeNetworkConnection,
+	NativeNetworkConnectInput,
+	NativeNetworkConnectOptions,
+	NativeNetworkDynamicGrantOptions,
+	NativeNetworkEgressGrant,
+	NativeProviderConfig,
+	NativeProxyDrainHandler,
+	NativeProxyEgressInfo,
+	NativeProxyExpiringEvent,
+	NativeProxyExpiringReason,
+	NativeTcpDynamicEgressRule,
+	NativeTcpEgressGrant,
+	NativeTcpEgressRule,
+	NativeTcpPortRange,
+	NativeTcpTlsMode,
+	NativeTlsConnectOptions,
 	OperationApprovalPolicy,
 	OperationContractMetadata,
 	OperationDefinition,
-	OperationDocMeta,
+	OperationExample,
 	OperationErrorCode,
-	OperationInputExample,
+	ProviderErrorStatus,
 	OperationLifecycle,
 	OperationObservabilityConfig,
 	OperationObservabilitySensitiveConfig,
 	OperationRelationships,
 	OperationRiskClass,
 	OperationSensitivePath,
-	OperationToolRouterMetadata,
 	OperationTransport,
 	ProviderAccessVisibility,
 	ProviderChoiceBindingOptions,
+	ProviderChoiceConsumeMode,
+	ProviderChoiceConsumeResult,
 	ProviderChoiceContext,
+	ProviderChoiceExplicitParseResult,
 	ProviderChoiceIssueOptions,
 	ProviderChoiceParseOptions,
 	ProviderContext,
+	ProviderContextFor,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
+	ProviderFileRef,
+	ProviderFilesContext,
 	ProviderLocale,
 	ProviderLocaleKey,
 	ProviderLocaleKeyInput,
 	ProviderLogoProfile,
 	ProviderProxyPolicy,
+	ProxiedOAuthConfig,
 	ProviderPublicConnectionMode,
 	ProviderPublicProfile,
+	ProviderResolvedFile,
+	ProviderRuntimeTarget,
 	ProviderRuntimeState,
 	ProviderStateDurationString,
 	ProviderStateNamespace,
 	ProviderSupportLevel,
+	RedirectRunReason,
 	SchemaLike,
 	SmsOtpMatcherDefinition,
 	StandardSchemaV1,
 	StateCasResult,
 	StateNamespaceOptions,
+	StateNamespaceScope,
 	StateValue,
 	StateWriteOptions,
 } 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,

package/src/runtime/auth-flow.ts

@@ -5,9 +5,13 @@ import type {
 	EnvContext,
 	FlowContext,
 	HttpClient,
+	OcrContext,
+	ProviderRuntimeState,
 	StealthClient,
 	SttContext,
 } 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> {
@@ -48,6 +52,7 @@ export function createScratchpad(
 }
 
 export function createFlowContext(options: {
+	flowId?: string;
 	http: HttpClient;
 	stealth: StealthClient;
 	env: EnvContext;
@@ -55,20 +60,27 @@ export function createFlowContext(options: {
 	providerId: string;
 	connectionId?: string;
 	externalRef?: string;
+	/** Host-agnostic: callers pass an already-scoped runtime state, which this helper forwards verbatim. */
+	state?: ProviderRuntimeState;
 	allowedKeys: string[];
 	initialContext?: Record<string, unknown>;
+	ocr?: OcrContext;
 	stt?: SttContext;
 }): FlowContext {
 	return {
+		flowId: options.flowId,
 		connectionId: options.connectionId,
 		externalRef: options.externalRef,
 		tenantId: options.tenantId,
 		providerId: options.providerId,
 		http: options.http,
+		state: options.state,
 		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(),
 	};
 }