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

package/dist/cli/templates/provider/AGENTS.md.tpl

@@ -4,8 +4,8 @@ You are building an APIFuse provider. APIFuse turns messy upstream APIs into
 normalized, typed, evidence-backed public APIs. A provider that merely proxies
 the upstream is a failed provider, even if every check passes.
 
-This file is the core contract. Detailed procedures live in `skills/` — load
-the matching skill BEFORE working on that area (index at the bottom).
+This file is the core contract. Detailed procedures live in `.agents/skills/` —
+load the matching skill BEFORE working on that area (index at the bottom).
 
 ## Non-negotiable principles
 
@@ -75,13 +75,22 @@ bun run submit-check # structural score; a high score does NOT prove quality
 `submit-check` is a structural gate. Every principle above can be violated
 while scoring 95/100 — reviewers and CI audit for exactly these classes.
 
+## Managed prompt assets
+
+`AGENTS.md` and `.agents/skills/**` are generated by the SDK; `CLAUDE.md`,
+`.claude`, and `.codex` are symlinks onto them so every agent CLI reads the
+same contract. Do not hand-edit these files — regenerate them with
+`bun run sync-assets` (or `bunx apifuse sync-assets .`). `apifuse check` and
+`submit-check` enforce a freshness gate: stale or modified prompt assets
+(tracked in `.apifuse/prompt-assets.json`) block submission until re-synced.
+
 ## Skill index — load before working on:
 
 | Area | Load |
 | --- | --- |
-| Output schemas, mappers, field naming, timestamps, enums | `skills/normalization-standards/SKILL.md` |
-| Upstream request params, new endpoint wiring, field mapping | `skills/upstream-contract-verification/SKILL.md` |
-| Recording fixtures, writing tests against fixtures | `skills/fixtures-and-recording/SKILL.md` |
-| List operations, paging, totals, client-side filtering | `skills/pagination-and-counts/SKILL.md` |
-| healthCheck blocks, error classification, fail-closed guards | `skills/health-checks-and-fail-closed/SKILL.md` |
-| Upstream-specific known pitfalls for THIS bounty | `skills/upstream-notes/` (read every file) |
+| Output schemas, mappers, field naming, timestamps, enums | `.agents/skills/normalization-standards/SKILL.md` |
+| Upstream request params, new endpoint wiring, field mapping | `.agents/skills/upstream-contract-verification/SKILL.md` |
+| Recording fixtures, writing tests against fixtures | `.agents/skills/fixtures-and-recording/SKILL.md` |
+| List operations, paging, totals, client-side filtering | `.agents/skills/pagination-and-counts/SKILL.md` |
+| healthCheck blocks, error classification, fail-closed guards | `.agents/skills/health-checks-and-fail-closed/SKILL.md` |
+| Upstream-specific known pitfalls for THIS bounty | `.agents/skills/upstream-notes/` (read every file) |

package/dist/config/loader.d.ts

@@ -1,5 +1,9 @@
-import Redis from "ioredis";
-import type { ProviderProxyPolicy, TraceConfig } from "../types";
+import { Redis } from "ioredis";
+import type { ProviderProxyPolicy, TraceConfig } from "../types.js";
+import { type ProxyProtocol } from "../runtime/proxy-nodemaven.js";
+export type { ProxyProtocol } from "../runtime/proxy-nodemaven.js";
+/** Proxy vendors the SDK resolves natively (as opposed to the static env path). */
+export type ProxyVendorName = "smartproxy" | "nodemaven";
 export declare const SMARTPROXY_APP_KEY_ENV = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 export declare const SMARTPROXY_MAX_LIFETIME_MINUTES = 2000;
 export declare const DEFAULT_SMARTPROXY_POOL_SIZE = 20;
@@ -42,12 +46,33 @@ export type ProxyResolutionOptions = {
     affinityKey?: string;
     /** Zero-based proxy-pool attempt index used by SDK transports for failover. */
     proxyAttempt?: number;
+    /**
+     * Tunnelling protocols the calling transport can use. When a resolved
+     * protocol is not in this set the resolver fails with
+     * `PROXY_PROTOCOL_UNSUPPORTED` instead of silently downgrading. Unset means
+     * permissive (both protocols allowed).
+     */
+    transportProtocols?: readonly ProxyProtocol[];
+    /**
+     * Explicit protocol override. Internal — for the verification harness and
+     * tests, or an advanced caller. Normal callers omit it and each vendor uses
+     * its own benchmarked default protocol (see VENDOR_DEFAULT_PROTOCOL). Not an
+     * env var and not a provider-policy field.
+     */
+    protocol?: ProxyProtocol;
+    /**
+     * Gateway pool "refresh" generation. Bumped by transports on pool refresh to
+     * derive a fresh gateway session set (ignored by allocation-style vendors,
+     * whose refresh is driven by cache invalidation).
+     */
+    proxyRefreshEpoch?: number;
     telemetry?: ProxyTelemetrySink;
 };
 export type ProxyCacheStatus = "memory_hit" | "redis_hit" | "allocator" | "soft_stale_refresh" | "lock_wait" | "redis_error" | "redis_corrupt" | "disabled";
 export type SmartproxyAllocatorBodyClass = "network_error" | "http_error" | "empty" | "json_without_proxies" | "text_without_proxies" | "usable_proxy_endpoints";
 export type ProxyResolutionTelemetryEvent = {
-    provider: "smartproxy";
+    provider: ProxyVendorName;
+    protocol?: ProxyProtocol;
     cacheStatus: ProxyCacheStatus;
     cacheHit: boolean;
     resolutionMs: number;
@@ -64,7 +89,7 @@ export type ProxyResolutionTelemetryEvent = {
     refreshes?: number;
 };
 export type ProxyAttemptTelemetryEvent = {
-    provider: "smartproxy";
+    provider: ProxyVendorName;
     attempt: number;
     poolIndex?: number;
     proxyHash?: string;
@@ -73,22 +98,43 @@ export type ProxyAttemptTelemetryEvent = {
     status?: number;
     durationMs?: number;
 };
+export type ProxyVendorFailoverTelemetryEvent = {
+    /** Vendor that failed or was skipped. */
+    vendor: ProxyVendorName;
+    /** Vendor tried next, or undefined when the chain is exhausted. */
+    nextVendor?: ProxyVendorName;
+    phase: "resolution" | "transport";
+    reason: "no_credentials" | "allocation_failed" | "pool_exhausted" | "protocol_unsupported";
+    attempt?: number;
+};
 export type ProxyTelemetrySink = {
     recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
     recordProxyAttempt?(event: ProxyAttemptTelemetryEvent): void;
+    recordProxyVendorFailover?(event: ProxyVendorFailoverTelemetryEvent): void;
 };
+export type ProxyResolutionSource = "explicit" | "env" | "config" | "smartproxy-allocator" | "nodemaven-gateway";
 export type ResolvedProxyConfig = {
     shouldWarn: boolean;
     url?: string;
-    source?: "explicit" | "env" | "config" | "smartproxy-allocator";
+    /** SDK-native vendor that supplied the URL, when applicable. */
+    vendor?: ProxyVendorName;
+    source?: ProxyResolutionSource;
+    protocol?: ProxyProtocol;
     diagnostics?: Record<string, string | number | boolean>;
 };
+export type ProxyResolutionErrorCode = "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED" | "PROXY_PROTOCOL_UNSUPPORTED";
 export declare class ProxyResolutionError extends Error {
-    readonly code: "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED";
+    readonly code: ProxyResolutionErrorCode;
     readonly telemetry?: ProxyResolutionTelemetryEvent;
-    constructor(code: "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED", message: string, options?: {
+    readonly vendor?: ProxyVendorName;
+    readonly vendorChain?: ProxyVendorName[];
+    readonly protocol?: ProxyProtocol;
+    constructor(code: ProxyResolutionErrorCode, message: string, options?: {
         cause?: unknown;
         telemetry?: ProxyResolutionTelemetryEvent;
+        vendor?: ProxyVendorName;
+        vendorChain?: ProxyVendorName[];
+        protocol?: ProxyProtocol;
     });
 }
 type ProxyRedisClient = Pick<Redis, "connect" | "del" | "eval" | "get" | "on" | "pttl" | "set" | "status">;
@@ -99,9 +145,131 @@ export declare function __setProxyRedisForTests(redis: ProxyRedisClient | undefi
 export declare function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs: number | undefined): void;
 export declare function resolveProxyConfig(options?: ProxyResolutionOptions): ResolvedProxyConfig;
 export declare function resolveProxyConfigAsync(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
+/**
+ * Resolve the proxy URL for a provider-owned consumer such as a CAPTCHA solver.
+ * Vendor allocation and failover remain owned by the SDK.
+ */
+export declare function resolveProxy(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
+/**
+ * Each vendor's default egress protocol, chosen from live KR benchmarks. HTTP
+ * CONNECT wins for nodemaven (socks5 adds ~500ms through the gateway) and ties
+ * for smartproxy, and is the only protocol ctx.http (Bun native fetch) supports.
+ * Override per call via ProxyResolutionOptions.protocol (harness/tests).
+ */
+export declare const VENDOR_DEFAULT_PROTOCOL: Readonly<Record<ProxyVendorName, ProxyProtocol>>;
+/**
+ * Guard the No-MITM invariant: a resolved proxy URL must use a tunnelling scheme
+ * (http CONNECT or socks5) so the client TLS handshake reaches the origin
+ * end-to-end. Anything else would intercept TLS and break fingerprinting.
+ */
+export declare function assertTunnelingScheme(url: string): void;
+export type ProxyVendorResolutionContext = {
+    readonly protocol: ProxyProtocol;
+    readonly poolIndex: number;
+    readonly refreshEpoch: number;
+    /** Explicit vendor credentials. Omit only on the legacy ambient-env path. */
+    readonly credentials?: Readonly<Record<string, string>>;
+    /** Disable non-policy env defaults for deterministic injected adapters. */
+    readonly ambientDefaults?: boolean;
+    /** Disable env-discovered Redis sharing for deterministic injected adapters. */
+    readonly sharedCache?: boolean;
+};
+export declare function resolveWithVendor(vendor: ProxyVendorName, policy: ProviderProxyPolicy, options: ProxyResolutionOptions, context: ProxyVendorResolutionContext): Promise<ResolvedProxyConfig>;
+/**
+ * Ordered list of SDK-native proxy vendors declared by the policy. `providers`
+ * takes precedence over the legacy singular `provider`; the platform default
+ * env is the final fallback. Non-registry names (decodo/custom) are dropped so
+ * an all-static chain falls through to the legacy env-URL path unchanged.
+ */
+export declare function resolveVendorChain(policy: ProviderProxyPolicy): ProxyVendorName[];
+/**
+ * Total attempt span across a policy's vendor chain — the sum of each vendor's
+ * pool size. Transports use this so successive attempts rotate a vendor's pool
+ * and then fail over to the next vendor via the flat attempt index. With one
+ * vendor this equals that vendor's pool size (today's behaviour).
+ */
+export declare function resolvePolicyProxyPoolSpan(policy: ProviderProxyPolicy): number;
+/**
+ * Absolute upper bound on a chain's attempt span — the sum of each vendor's
+ * *maximum* pool size. Unlike `resolvePolicyProxyPoolSpan` (the configured
+ * span), this backstop is independent of `session.poolSize`, so it never
+ * truncates a legitimately large pool below the point where the flat attempt
+ * index would cross into the next vendor (e.g. a 50-slot NodeMaven pool).
+ */
+export declare function maxPolicyProxyPoolSpan(policy: ProviderProxyPolicy): number;
+/**
+ * Transport-retry attempt cap for a policy-managed request. A transport failure
+ * rotates the flat attempt index onto the *next* endpoint (and, once the index
+ * passes the primary vendor's pool span, the *next vendor*), so the cap must be
+ * the chain's full pool span for failover to reach the fallback vendor — the
+ * per-endpoint retry budget (default 3) never gets there.
+ *
+ * The span only widens beyond the caller's retry budget when ALL hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — `HttpRetryOptions.attempts`
+ *    is the documented total-attempt ceiling and must be honoured verbatim;
+ *  - the method is safe/idempotent — an unsafe request must never be duplicated
+ *    across the pool even if some framework default would allow it;
+ *  - the policy resolves a non-empty *registry* vendor chain (smartproxy /
+ *    nodemaven). Static vendors (custom / decodo) and credential-less policies
+ *    resolve no allocator pool, so every attempt would hit the same endpoint
+ *    with no possible crossover — they keep the retry budget.
+ *
+ * The widened cap is bounded by the chain's true maximum span (sum of each
+ * vendor's max pool size), so a large NodeMaven pool (≤50) stays reachable and
+ * a pathological chain can never spin unbounded.
+ */
+/**
+ * True when a policy request is in *implicit chain-rotation* mode: successive
+ * transport attempts rotate the flat index across the concatenated vendor pool
+ * spans (and, past the primary vendor's span, into the fallback vendor). This is
+ * the ONLY mode in which the transport loop widens its attempt cap AND
+ * de-duplicates repeated endpoints — the two behaviours must share one predicate
+ * so they never diverge. It holds when ALL of the widening conditions hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — its `attempts` ceiling is
+ *    the documented contract and must be honoured verbatim against whatever
+ *    endpoint each attempt resolves (even a repeated one), so no de-duplication;
+ *  - the method is safe/idempotent — an unsafe request is never duplicated;
+ *  - the policy resolves a non-empty registry vendor chain (smartproxy /
+ *    nodemaven). Static vendors (custom / decodo) resolve the same URL every
+ *    attempt, so there is nothing to rotate or de-duplicate.
+ */
+export declare function policyRotatesTransportVendorChain(input: {
+    policy: ProviderProxyPolicy | undefined;
+    usesPolicyAllocator: boolean;
+    explicitRetry: boolean;
+    method: string;
+}): boolean;
+export declare function resolvePolicyTransportAttemptCap(input: {
+    policy: ProviderProxyPolicy | undefined;
+    usesPolicyAllocator: boolean;
+    retryAttempts: number;
+    explicitRetry: boolean;
+    method: string;
+}): number;
+/**
+ * A registry vendor chain (smartproxy/nodemaven) resolves a potentially
+ * *different* endpoint per flat attempt index, so a transport retry should
+ * advance across endpoints and de-duplicate once the chain stops yielding new
+ * ones. Static/custom/decodo policies (empty registry chain) resolve the *same*
+ * URL every attempt by design — retrying that same endpoint is intended, so the
+ * transport loop must not de-duplicate them.
+ */
+export declare function policyResolvesRegistryVendorChain(policy: ProviderProxyPolicy | undefined): boolean;
+/** Map a resolved proxy source label to the vendor that served it. */
+export declare function vendorFromResolvedSource(source: ResolvedProxyConfig["source"]): ProxyVendorName | undefined;
+/**
+ * Map a flat attempt index into (vendorIndex, poolIndex) by concatenating each
+ * vendor's pool space in chain order. With a single vendor this reduces to
+ * `attempt % poolSize`, preserving today's behaviour exactly.
+ */
+export declare function mapFlatAttempt(flat: number, sizes: readonly number[]): {
+    vendorIndex: number;
+    poolIndex: number;
+};
 export declare function clearProxyResolutionCache(): void;
 export declare function invalidateProxyResolutionCache(options?: ProxyResolutionOptions): boolean;
 export declare function invalidateProxyResolutionCacheAsync(options?: ProxyResolutionOptions): Promise<boolean>;
 export declare function defineConfig(config: ApiFuseConfig): ApiFuseConfig;
 export declare function loadApiFuseConfig(dir?: string): Promise<ApiFuseConfig>;
-export {};