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

package/dist/cli/templates/provider/.dockerignore.tpl

@@ -0,0 +1,22 @@
+node_modules/
+.git/
+.github/
+
+# Environment and local secrets
+.env
+.env.*
+!.env.example
+
+# Local reports and generated artifacts
+submission-report.md
+coverage/
+dist/
+.cache/
+.turbo/
+.bun/
+*.tsbuildinfo
+
+# OS/editor junk
+.DS_Store
+Thumbs.db
+*.swp

package/dist/cli/templates/provider/.gitignore.tpl

@@ -0,0 +1,22 @@
+node_modules/
+
+# Environment and local secrets
+.env
+.env.*
+!.env.example
+
+# Build, coverage, cache, and local runtime artifacts
+coverage/
+dist/
+.cache/
+.turbo/
+.bun/
+*.tsbuildinfo
+
+# Bounty submission output
+submission-report.md
+
+# OS/editor junk
+.DS_Store
+Thumbs.db
+*.swp

package/dist/cli/templates/provider/Dockerfile.tpl

@@ -0,0 +1,7 @@
+FROM oven/bun:1.2-alpine
+WORKDIR /provider
+COPY package.json bun.lockb* ./
+RUN bun install --frozen-lockfile
+COPY . .
+EXPOSE 3000
+CMD ["bun", "run", "start"]

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

@@ -0,0 +1,163 @@
+# {{DISPLAY_NAME}}
+
+Generated with `apifuse create`.
+
+## Commands
+
+```bash
+bun run dev
+bun run check
+bun run test
+bun run submit-check -- --smoke
+bunx apifuse perf . --operation <operation-id> --runs 3
+```
+
+
+## Module layout
+
+The generated provider uses the recommended split layout:
+
+```text
+index.ts              # composition root: defineProvider() and wiring only
+meta.ts               # provider metadata
+operations/           # APIFuse operation contracts and handlers
+schemas/              # public input/output schemas near operations
+upstream/             # upstream ceremony: clients, auth, request builders
+mappers/              # upstream-to-APIFuse normalization helpers
+domain/               # shared provider-specific business ceremony
+```
+
+Small providers may stay in one file, but larger providers are easier to
+review when `index.ts` remains a short composition root.
+
+## Pre-submission report
+
+Before posting bounty evidence, run:
+
+```bash
+bun run submit-check -- --smoke
+```
+
+This writes `submission-report.md` with a review-readiness score, blockers,
+warnings, health coverage notes, fixture/schema evidence, and remediation. A
+score is not a payout guarantee; blockers must be fixed before maintainer
+review. The generated `ping` starter intentionally warns until you replace it
+with real upstream-backed Operations. `APIFUSE__PROVIDER__*` env vars enable
+live upstream calls; without them, structured provider errors can still verify
+runtime routing. The full public-only checklist is shipped in
+`node_modules/@apifuse/provider-sdk/SUBMISSION.md`.
+
+
+## Operation guide
+
+### Parameters
+
+Starter `ping` accepts `{ "value": string }`. Replace this section with each
+real operation's input schema, required fields, formats, limits, and examples
+before submitting bounty evidence.
+
+### Response
+
+Starter `ping` returns `{ "ok": boolean, "message": string }`. Replace this
+section with the normalized response fields, units, enum values, pagination,
+and upstream caveats for each real operation.
+
+### Example
+
+```json
+{
+	"requestId": "req_local_ping",
+	"input": { "value": "hello" },
+	"headers": {}
+}
+```
+
+## Provider server contract
+
+- Dev default: `3900`
+- Start/Docker/container contract: `3000`
+- `GET /health`
+- `POST /v1/{operation}`
+- `POST /auth/start`
+- `POST /auth/continue`
+- `POST /auth/poll`
+- `POST /auth/disconnect`
+
+## Local smoke
+
+```bash
+curl -s http://localhost:3900/health
+curl -s -X POST http://localhost:3900/v1/ping \
+  -H 'Content-Type: application/json' \
+  -d '{"requestId":"req_local_ping","input":{"value":"hello"},"headers":{}}'
+```
+
+The `POST /v1/{operation}` body is a request envelope:
+
+- `requestId` is required and can be any unique local debugging string.
+- `input` contains the operation input shape.
+- `headers` is optional.
+- `connection` is optional; omit it for no-auth/public operations. For
+  credential debugging, pass `{ "id", "mode", "secrets", "metadata",
+  "externalRef" }` with local-only secret values.
+
+Structured errors return an `error` object with `code`, `message`,
+`requestId`, and optional `details`; validation failures include field paths in
+`details`, and the `apifuse dev` terminal prints a structured provider log.
+
+## Debugging checklist
+
+- `invalid_request`: include `requestId` and `input`; omit `connection` for
+  public/no-auth operations and never send `connection: null`.
+- Credentials: declare `credential.keys`, pass local-only values through
+  `connection.secrets`, and read them with `ctx.credential`.
+- Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
+  carry returned `contextPatch` values into the next request's `context`.
+- Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with an
+  SDK stealth `profile`; the TypeScript stealth runtime uses `impit` internally.
+  `ctx.stealth` supports Chrome/Firefox-style profiles. For TypeScript browser
+  Providers or Safari-specific behavior use `browser.engine: "playwright-stealth"`
+  (`nodriver` is Python-runtime only), then install local Chromium with
+  `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.
+
+## Next steps
+
+1. Replace the sample `ping` operation with real upstream logic.
+2. Once the real operation declares `upstream.baseUrl` and uses `ctx.http` or
+   `ctx.stealth`, record a fixture with:
+   `bun run record -- --operation <operation> --params '<json-input>'`.
+3. Replace the starter `healthCheckUnsupported` with a real `healthCheck` for read-only upstream operations when safe.
+4. Extend tests and operation metadata until the provider is bounty-ready.
+
+`apifuse record` is not expected to work with the generated local-only `ping`
+operation because it intentionally has no upstream response to capture.
+
+## Health-check authorship
+
+Every operation must declare exactly one of:
+
+- `healthCheck` — preferred for safe read-only upstream probes.
+- `healthCheckUnsupported` — allowed only when a probe is destructive, paid,
+  credential-sensitive, flaky by design, or otherwise unsafe. Use a specific
+  reason; reviewers reject placeholder reasons such as "TODO" or "later".
+
+The generated `ping` operation uses `healthCheckUnsupported` only because it is
+a local scaffold check, not a real upstream API probe.
+
+`healthCheck.cases[].assertions` receives `{ data, status, durationMs, meta }`.
+`data` is the parsed operation output. Use this shape in real operations:
+
+```ts
+healthCheck: {
+  interval: "5m",
+  cases: [{
+    name: "lookup baseline",
+    input: { q: "btc" },
+    assertions: ({ data, status, durationMs }) => {
+      if (status !== 200 || data.results.length === 0 || durationMs > 3000) {
+        return { status: "degraded", label: "lookup baseline changed" };
+      }
+    },
+  }],
+}
+```

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

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

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

@@ -0,0 +1,3 @@
+# Domain
+
+Put provider-specific business ceremony here when it is shared across operations and too complex to live inside one operation module.

package/dist/cli/templates/provider/index.test.ts.tpl

@@ -0,0 +1,13 @@
+import { describe, expect, it } from "bun:test";
+import { runStandardTests } from "@apifuse/provider-sdk/testing";
+
+import provider from "../index";
+
+runStandardTests(provider);
+
+describe("{{PROVIDER_ID}}", () => {
+  it("exposes provider metadata from defineProvider", () => {
+    expect(provider.id).toBe("{{PROVIDER_ID}}");
+    expect(provider.reviewed).toBe("community");
+  });
+});

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

@@ -0,0 +1,15 @@
+import { defineProvider } from "@apifuse/provider-sdk/provider";
+
+import { providerMeta } from "./meta";
+import { operations } from "./operations";
+
+export default defineProvider({
+  id: "{{PROVIDER_ID}}",
+  version: "1.0.0",
+  runtime: "{{RUNTIME}}"{{BROWSER_BLOCK}},
+  allowedHosts: ["api.example.com"],
+  reviewed: "community",
+  {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
+  meta: providerMeta,
+  operations: operations,
+});

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

@@ -0,0 +1,3 @@
+# Mappers
+
+Put normalization helpers here when upstream responses need to become public APIFuse operation outputs.

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

@@ -0,0 +1,7 @@
+export const providerMeta = {
+  displayName: "{{PROVIDER_ID}}",
+  displayNameKey: "meta.displayName",
+  descriptionKey: "meta.description",
+  category: "{{CATEGORY}}",
+  tags: ["{{PROVIDER_ID}}", "starter", "community"],
+} as const;

package/dist/cli/templates/provider/operations/index.ts.tpl

@@ -0,0 +1,5 @@
+import { pingOperation } from "./ping";
+
+export const operations = {
+  ping: pingOperation,
+};

package/dist/cli/templates/provider/operations/ping.ts.tpl

@@ -0,0 +1,24 @@
+import { defineOperation } from "@apifuse/provider-sdk/provider";
+
+import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
+
+export const pingOperation = defineOperation({
+  descriptionKey: "operations.ping.description",
+  input: pingInputSchema,
+  output: pingOutputSchema,
+  handler: async ({{HANDLER_CTX}}, input) => {
+    {{BROWSER_HANDLER_BLOCK}}
+    return {
+      ok: true,
+      message: "{{DISPLAY_NAME}} received: " + input.value{{BROWSER_RESPONSE_FIELDS}},
+    };
+  },
+  fixtures: {
+    request: { value: "hello" },
+    response: { ok: true, message: "{{DISPLAY_NAME}} received: hello" },
+  },
+  healthCheckUnsupported: {
+    reason:
+      "Generated local-only scaffold operation. Replace this with a real healthCheck for upstream-backed bounty operations when safe; keep healthCheckUnsupported only for destructive, paid, credential-sensitive, or otherwise unprobeable operations with a specific rationale.",
+  },
+});

package/dist/cli/templates/provider/schemas/ping.ts.tpl

@@ -0,0 +1,24 @@
+import { describeKey, z } from "@apifuse/provider-sdk/provider";
+
+export const pingInputSchema = describeKey(
+  z.object({
+    value: describeKey(z.string(), "schemaDescriptions.input.value"),
+  }),
+  "schemaDescriptions.input.root",
+);
+
+export const pingOutputSchema = describeKey(
+  z.object({
+    ok: describeKey(z.boolean(), "schemaDescriptions.output.ok"),
+    message: describeKey(z.string(), "schemaDescriptions.output.message"),
+    pageTitle: describeKey(
+      z.string().optional(),
+      "schemaDescriptions.output.pageTitle",
+    ),
+    frameCount: describeKey(
+      z.number().int().nonnegative().optional(),
+      "schemaDescriptions.output.frameCount",
+    ),
+  }),
+  "schemaDescriptions.output.root",
+);

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 {};