@apifuse/provider-sdk 2.2.0-beta.12 → 2.2.0-beta.13

package/src/types.ts

@@ -824,6 +824,12 @@ export interface ProviderProxyPolicy {
 		affinity?: ProviderProxySessionAffinity;
 		lifetimeMinutes?: number;
 		poolSize?: number;
+		/**
+		 * Seconds before hard sticky expiry at which native connections receive
+		 * the `expiring` event so the provider can drain and reconnect cleanly.
+		 * Declared by the provider; the SDK does not assume a default cut point.
+		 */
+		drainLeadSeconds?: number;
 	};
 }
 
@@ -1000,6 +1006,11 @@ export interface HttpRetrySummary {
 export interface RequestOptions {
 	headers?: Record<string, string>;
 	params?: RequestParams;
+	/**
+	 * Query parameters whose values contain credentials or other secret material.
+	 * They are sent like `params`, but redacted from SDK errors, traces, and recorded fixtures.
+	 */
+	sensitiveParams?: Record<string, string>;
 	proxy?: string;
 	timeout?: number;
 	/**
@@ -1032,6 +1043,12 @@ export interface StealthFetchOptions extends RequestOptions {
 	method?: HttpMethod;
 	body?: string | Buffer;
 	redirect?: "follow" | "manual" | "error";
+	/**
+	 * Maximum decoded response-body bytes to buffer. When set, the stealth
+	 * transport aborts the response and throws `response_too_large` if the
+	 * declared or streamed body exceeds this limit.
+	 */
+	maxBodyBytes?: number;
 	/**
 	 * Offsets policy-managed proxy pool selection for caller-managed retries.
 	 * Use when a request receives an upstream challenge page rather than a
@@ -1232,6 +1249,171 @@ export interface HttpClient {
 	): Promise<AsyncIterable<SseMessage>>;
 }
 
+/** Request-scoped file reference accepted by provider operation inputs. */
+export interface ProviderFileRef {
+	readonly type: "request_file";
+	readonly id: string;
+	readonly filename: string;
+	readonly mime_type?: string;
+	readonly size: number;
+	readonly sha256?: string;
+}
+
+/** File body resolved from a request-scoped {@link ProviderFileRef}. */
+export type ProviderResolvedFile = Omit<ProviderFileRef, "mime_type"> & {
+	readonly mimeType?: string;
+	arrayBuffer(): Promise<ArrayBuffer>;
+	bytes(): Promise<Uint8Array>;
+	stream(): ReadableStream<Uint8Array>;
+};
+
+/** Resolver supplied by runtimes that accept request-scoped file inputs. */
+export interface ProviderFilesContext {
+	has(input: string | ProviderFileRef): boolean;
+	resolve(input: string | ProviderFileRef): Promise<ProviderResolvedFile>;
+}
+
+export type NativeTcpTlsMode = "required" | "allowed" | "disabled";
+
+export interface NativeTcpPortRange {
+	readonly start: number;
+	readonly end: number;
+}
+
+/** Static native TCP egress declared by a provider. */
+export interface NativeTcpEgressRule {
+	readonly host: string;
+	readonly ports: readonly number[];
+	readonly tls: NativeTcpTlsMode;
+}
+
+/**
+ * Bounded native TCP egress discovered through a declared bootstrap endpoint.
+ * Host suffixes are exact DNS suffixes, not wildcard patterns.
+ */
+export interface NativeTcpDynamicEgressRule {
+	readonly sourceHost?: string;
+	readonly sourceHostSuffixes?: readonly string[];
+	readonly sourcePorts?: readonly number[];
+	readonly sourcePortRanges?: readonly NativeTcpPortRange[];
+	readonly targetHostSuffixes: readonly string[];
+	readonly targetPorts?: readonly number[];
+	readonly targetPortRanges?: readonly NativeTcpPortRange[];
+	readonly tls: NativeTcpTlsMode;
+	readonly ttlMs?: number;
+	readonly maxGrants?: number;
+}
+
+/** Common TCP/TLS connection input supported by the native runtime. */
+export interface NativeNetworkConnectInput {
+	readonly host: string;
+	readonly port: number;
+	readonly serverName?: string;
+	readonly rejectUnauthorized?: boolean;
+	/**
+	 * Maximum time without a successful socket read before the connection is
+	 * closed. Opt-in; when absent, reads can remain pending indefinitely.
+	 */
+	readonly idleTimeoutMs?: number;
+	/** Maximum time allowed to establish the TCP/SOCKS/TLS connection. */
+	readonly timeoutMs?: number;
+	readonly signal?: AbortSignal;
+	/** Overrides the credential-derived sticky affinity key. */
+	readonly affinityKey?: string;
+}
+
+export type NativeNetworkConnectOptions = Omit<
+	NativeNetworkConnectInput,
+	"serverName" | "rejectUnauthorized"
+>;
+
+export type NativeTlsConnectOptions = NativeNetworkConnectInput;
+
+export interface NativeNetworkDynamicGrantOptions {
+	readonly sourceHost: string;
+	readonly sourcePort: number;
+	readonly host: string;
+	readonly port: number;
+	readonly tls: NativeTcpTlsMode;
+	readonly ttlMs?: number;
+}
+
+export interface NativeNetworkEgressGrant {
+	revoke(): void;
+}
+
+/** Consumer-facing alias used by native TCP providers. */
+export type NativeTcpEgressGrant = NativeNetworkEgressGrant;
+
+/** Resolved egress identity for a native connection routed through a proxy. */
+export interface NativeProxyEgressInfo {
+	readonly vendor: ProviderProxyProvider;
+	readonly sticky: boolean;
+	/** Vendor sticky session id (sid). Absent for rotating sessions. */
+	readonly sessionId?: string;
+	/** Hard expiry of the sticky binding, ISO 8601. */
+	readonly expiresAt?: string;
+}
+
+export type NativeProxyExpiringReason = "sticky_expiry";
+
+export interface NativeProxyExpiringEvent {
+	readonly expiresAt: string;
+	readonly leadSeconds: number;
+	readonly reason: NativeProxyExpiringReason;
+}
+
+/**
+ * Cooperative drain handler. The SDK awaits this before closing a socket whose
+ * sticky proxy binding is about to expire, then force-closes at hard expiry.
+ */
+export type NativeProxyDrainHandler = (
+	event: NativeProxyExpiringEvent,
+) => void | Promise<void>;
+
+/** Typed reason recorded when the SDK closes a native connection intentionally. */
+export interface NativeNetworkCloseReason {
+	readonly code: string;
+	readonly message: string;
+}
+
+/** Byte-oriented connection returned by the native TCP/TLS runtime. */
+export interface NativeNetworkConnection {
+	/** Present when the connection was routed through a proxy. */
+	readonly proxy?: NativeProxyEgressInfo;
+	/** Present after an SDK-planned close, such as sticky proxy expiry. */
+	readonly closeReason?: NativeNetworkCloseReason;
+	/** Register a cooperative drain handler for sticky-expiry reconnects. */
+	onExpiring?(handler: NativeProxyDrainHandler): void;
+	read(): Promise<Uint8Array | null>;
+	write(data: Uint8Array): Promise<void>;
+	close(): Promise<void>;
+}
+
+export interface NativeNetworkClient {
+	connectTcp(
+		input: NativeNetworkConnectOptions,
+	): Promise<NativeNetworkConnection>;
+	connectTls(input: NativeTlsConnectOptions): Promise<NativeNetworkConnection>;
+	grantTcpEgress(
+		input: NativeNetworkDynamicGrantOptions,
+	): NativeNetworkEgressGrant;
+}
+
+export interface NativeContext {
+	readonly network: NativeNetworkClient;
+}
+
+/** Consumer-facing alias for the native capability on provider contexts. */
+export type NativeProviderContext = NativeContext;
+
+export interface NativeProviderConfig {
+	readonly network?: {
+		readonly tcp?: readonly NativeTcpEgressRule[];
+		readonly dynamicTcp?: readonly NativeTcpDynamicEgressRule[];
+	};
+}
+
 export interface ProviderCacheKeyOptions {
 	/**
 	 * Additional field names to omit from stable key material. The SDK always
@@ -1649,6 +1831,8 @@ export interface FlowContext {
 	tenantId: string;
 	providerId: string;
 	http: HttpClient;
+	/** Present when the selected runtime supplies native network capabilities. */
+	readonly native?: NativeProviderContext;
 	stealth: StealthClient;
 	env: EnvContext;
 	credential?: CredentialContext;
@@ -1768,6 +1952,10 @@ export interface ProviderContext {
 	credential: CredentialContext;
 	request?: ProviderRequestContext;
 	http: HttpClient;
+	/** Present for requests carrying runtime-resolvable file references. */
+	readonly files?: ProviderFilesContext;
+	/** Present when the selected runtime supplies native network capabilities. */
+	readonly native?: NativeProviderContext;
 	cache: ProviderCache;
 	state: ProviderRuntimeState;
 	stealth: StealthClient;
@@ -1860,6 +2048,11 @@ export interface OperationDefinition<
 	fixtures?: {
 		request: InferSchemaOutput<TInput>;
 		response: InferSchemaOutput<TOutput>;
+		/**
+		 * KST calendar date when `response` evidence was captured. Date fields in
+		 * the response align with this date, not a resolved relative request date.
+		 */
+		recordedAt?: string;
 	};
 	upstream?: {
 		baseUrl?: string;
@@ -1923,6 +2116,7 @@ export interface ProviderDefinition {
 	 */
 	deployment?: ProviderDeploymentOverrides;
 	allowedHosts?: string[];
+	native?: NativeProviderConfig;
 	stealth?: {
 		profile: string;
 		platform: StealthPlatform;