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

package/dist/cli/templates/provider/skills/upstream-contract-verification/SKILL.md.tpl

@@ -0,0 +1,45 @@
+---
+name: upstream-contract-verification
+description: How to establish evidence for upstream request params and response fields before coding. Load before wiring any new endpoint or mapping new fields.
+---
+
+# Upstream contract verification
+
+Most provider P0s come from guessed upstream contracts. Every param name and
+response field needs evidence BEFORE it ships.
+
+## Request parameters
+1. Start from the official spec document (data.go.kr 활용가이드, vendor API
+   docs). Copy exact names — casing and underscores matter
+   (`WGS84_LAT` ≠ `WGS84LAT`; the wrong one is often silently ignored).
+2. Confirm with ONE live call per endpoint. A param being ignored does not
+   produce an error — it produces plausible-looking wrong results, so compare:
+   - filtered vs unfiltered `totalCount` (identical → param ignored)
+   - a dense-area query returning 0 rows (→ param name/format wrong)
+3. Do NOT copy param names from a sibling endpoint or sibling API of the same
+   vendor without re-verifying. Same vendor ≠ same contract; endpoints drift.
+4. If a param only works together with another param (district requires
+   province), encode that dependency in the input schema with a clear error.
+   Test it: dependent-param-alone must be rejected, not silently national.
+
+## Response fields
+- Map exactly the field names present in your recorded live fixtures.
+- No speculative fallback chains (`row.distance ?? row.dist ?? row.Distance`).
+  If two shapes genuinely exist, you need a recorded fixture proving EACH
+  branch plus a row-level test per branch; otherwise map one name only.
+- Field presence varies by endpoint within the same vendor. Detail endpoints
+  often return more/differently-named fields than list endpoints — record
+  fixtures per endpoint, not per vendor.
+
+## When results look wrong
+- Same response body across different request payloads → the upstream is
+  ignoring your variation; stop tuning fields and re-check param names/auth.
+- Empty result for a query that must have data (city-center radius search,
+  major-district listing) → treat as a request bug. Never record it as a
+  fixture and never ship it.
+
+## Deliverables per endpoint
+- [ ] Spec reference (URL or doc name + section) noted in the PR/commit
+- [ ] One recorded live fixture proving request params take effect
+- [ ] Negative evidence checked: filtered count differs from unfiltered
+- [ ] Param dependencies enforced in the input schema with tests

package/dist/cli/templates/provider/skills/upstream-notes/README.md.tpl

@@ -0,0 +1,13 @@
+# Upstream notes
+
+Per-vendor / per-API-family pitfalls proven by live evidence. These are the
+highest-value files in this workspace: general principles are knowable, but
+"this API silently ignores param X" is only discoverable by getting burned.
+
+- Read EVERY file here before your first upstream call.
+- When you discover a new upstream quirk (silently ignored param, unit
+  surprise, undocumented value domain, error-shape oddity), ADD it here in
+  the same format — evidence line included. Reviewers treat contributed
+  upstream notes as part of submission quality.
+
+Format per entry: **Symptom → Cause → Rule → Evidence**.

package/dist/cli/templates/provider/start.ts.tpl

@@ -0,0 +1,5 @@
+import { serve } from "@apifuse/provider-sdk";
+
+import provider from "./index";
+
+await serve(provider, { port: Number(process.env.APIFUSE__RUNTIME__PORT) || 3000 });

package/dist/cli/templates/provider/upstream/README.md.tpl

@@ -0,0 +1,3 @@
+# Upstream
+
+Put upstream HTTP clients, auth ceremony helpers, request builders, and protocol-specific types here once the provider talks to the real upstream service.

package/dist/config/loader.d.ts

@@ -0,0 +1,107 @@
+import Redis from "ioredis";
+import type { ProviderProxyPolicy, TraceConfig } from "../types";
+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;
+export declare const SMARTPROXY_MAX_POOL_SIZE = 20;
+export declare const DEFAULT_PROXY_PROVIDER_ENV = "APIFUSE__PROXY__PROVIDER";
+export declare const DEFAULT_PROXY_COUNTRY_ENV = "APIFUSE__PROXY__DEFAULT_COUNTRY";
+export declare const DEFAULT_PROXY_LIFETIME_ENV = "APIFUSE__PROXY__DEFAULT_LIFETIME_MINUTES";
+export declare const PROVIDER_CACHE_REDIS_URL_ENV = "APIFUSE__PROVIDER__CACHE_REDIS_URL";
+export declare const PROVIDER_STATE_REDIS_URL_ENV = "APIFUSE__PROVIDER__STATE_REDIS_URL";
+export declare const REDIS_URL_ENV = "APIFUSE__REDIS__URL";
+export type ProxyOptions = {
+    url: string;
+};
+export type ProxyConfig = Partial<ProxyOptions> & {
+    provider?: string;
+    apiKey?: string;
+};
+export type BrowserConfig = {
+    executablePath?: string;
+    headless?: boolean;
+};
+export type SessionConfig = {
+    storage?: "sqlite" | "supabase";
+    path?: string;
+};
+export type ApiFuseConfig = {
+    proxy?: ProxyConfig;
+    browser?: BrowserConfig;
+    session?: SessionConfig;
+    trace?: TraceConfig;
+    credentials?: Record<string, Record<string, string>>;
+};
+export type ProxyResolutionOptions = {
+    proxy?: string;
+    upstream?: {
+        proxy?: boolean | ProviderProxyPolicy;
+    };
+    apifuseConfig?: Pick<ApiFuseConfig, "proxy">;
+    proxyPolicy?: ProviderProxyPolicy;
+    affinityKey?: string;
+    /** Zero-based proxy-pool attempt index used by SDK transports for failover. */
+    proxyAttempt?: 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";
+    cacheStatus: ProxyCacheStatus;
+    cacheHit: boolean;
+    resolutionMs: number;
+    allocatorMs?: number;
+    allocatorStatus?: number;
+    allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+    allocatorAttempts?: number;
+    lockWaitMs?: number;
+    redisReadMs?: number;
+    redisWriteMs?: number;
+    poolAgeMs?: number;
+    poolExpiresInMs?: number;
+    attempts: number;
+    refreshes?: number;
+};
+export type ProxyAttemptTelemetryEvent = {
+    provider: "smartproxy";
+    attempt: number;
+    poolIndex?: number;
+    proxyHash?: string;
+    outcome: "ok" | "error";
+    errorCode?: string;
+    status?: number;
+    durationMs?: number;
+};
+export type ProxyTelemetrySink = {
+    recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
+    recordProxyAttempt?(event: ProxyAttemptTelemetryEvent): void;
+};
+export type ResolvedProxyConfig = {
+    shouldWarn: boolean;
+    url?: string;
+    source?: "explicit" | "env" | "config" | "smartproxy-allocator";
+    diagnostics?: Record<string, string | number | boolean>;
+};
+export declare class ProxyResolutionError extends Error {
+    readonly code: "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED";
+    readonly telemetry?: ProxyResolutionTelemetryEvent;
+    constructor(code: "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED", message: string, options?: {
+        cause?: unknown;
+        telemetry?: ProxyResolutionTelemetryEvent;
+    });
+}
+type ProxyRedisClient = Pick<Redis, "connect" | "del" | "eval" | "get" | "on" | "pttl" | "set" | "status">;
+export declare function providerCacheRedisUrlFromEnv(): string | undefined;
+export declare function providerStateRedisUrlFromEnv(): string | undefined;
+/** @internal Test-only hook for exercising shared proxy-cache behavior. */
+export declare function __setProxyRedisForTests(redis: ProxyRedisClient | undefined): void;
+export declare function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs: number | undefined): void;
+export declare function resolveProxyConfig(options?: ProxyResolutionOptions): ResolvedProxyConfig;
+export declare function resolveProxyConfigAsync(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
+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 {};