@apifuse/provider-sdk 2.0.0-beta.1 → 2.1.0-beta.1

package/src/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/src/cli/templates/provider/README.md.tpl

@@ -0,0 +1,41 @@
+# {{DISPLAY_NAME}}
+
+Generated with `apifuse create`.
+
+## Commands
+
+```bash
+bun run dev
+bun run check
+bun run test
+```
+
+## 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`
+
+## Next steps
+
+1. Replace the sample `ping` operation with real upstream logic.
+2. Record a real fixture with `bun run record:sample` or a provider-specific equivalent.
+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.
+
+## 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.

package/src/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.PORT) || 3900 });

package/src/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/src/cli/templates/provider/index.ts.tpl

@@ -0,0 +1,58 @@
+import { defineProvider, z } from "@apifuse/provider-sdk";
+
+const InputSchema = z
+  .object({
+    value: z
+      .string()
+      .default("hello")
+      .describe("Sample input value used to verify the generated provider scaffold is wired correctly."),
+  })
+  .describe("Input payload for the generated ping operation.");
+
+const OutputSchema = z
+  .object({
+    ok: z
+      .boolean()
+      .describe("Whether the generated provider handled the sample request successfully."),
+    message: z
+      .string()
+      .describe("Human-readable confirmation that the generated provider round-tripped the sample payload."),
+  })
+  .describe("Output payload returned by the generated ping operation.");
+
+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: {
+    displayName: "{{DISPLAY_NAME}}",
+    description: "{{DISPLAY_NAME}} provider starter for ApiFuse community contributions.",
+    category: "{{CATEGORY}}",
+    tags: ["{{PROVIDER_ID}}", "starter", "community"],
+  },
+  operations: {
+    ping: {
+      description:
+        "Confirms the generated provider wiring is operational by echoing a small sample payload through the ApiFuse runtime contract. Use when validating local development, baseline checks, or first-pass bounty scaffolds. Do NOT use for production data retrieval or upstream-specific workflows because this starter operation exists only to prove the generated project compiles, serves, and round-trips input/output correctly. Returns a success flag plus a message containing the supplied value.",
+      input: InputSchema,
+      output: OutputSchema,
+      handler: async (_ctx, input) => {
+        return {
+          ok: true,
+          message: "{{DISPLAY_NAME}} received: " + input.value,
+        };
+      },
+      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/src/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.PORT) || 3000 });

package/src/config/loader.ts

@@ -43,7 +43,67 @@ export type ResolvedProxyConfig = {
 
 function normalizeProxyUrl(url?: string): string | undefined {
 	const normalized = url?.trim();
-	return normalized ? normalized : undefined;
+	return normalized ? applyStickyProxySession(normalized) : undefined;
+}
+
+function applyStickyProxySession(proxyUrl: string): string {
+	let parsed: URL;
+	try {
+		parsed = new URL(proxyUrl);
+	} catch {
+		return proxyUrl;
+	}
+
+	if (!parsed.hostname || !parsed.username || !parsed.password) {
+		return proxyUrl;
+	}
+
+	const host = parsed.hostname.toLowerCase();
+	if (!host.includes("smartproxy") && !host.includes("decodo")) {
+		return proxyUrl;
+	}
+
+	const username = decodeURIComponent(parsed.username);
+	const sessionId =
+		process.env.APIFUSE_PROXY_SESSION_ID?.trim() || "apifuse-shared";
+	const sessionDuration =
+		process.env.APIFUSE_PROXY_SESSION_DURATION?.trim() || undefined;
+	const stickyUsername = host.includes("smartproxy")
+		? buildSmartproxyUsername(username, sessionId, sessionDuration)
+		: buildDecodoUsername(username, sessionId, sessionDuration ?? "60");
+
+	parsed.username = stickyUsername;
+	return parsed.toString();
+}
+
+function buildSmartproxyUsername(
+	username: string,
+	sessionId: string,
+	sessionDuration?: string,
+): string {
+	const parts = username.split("_");
+	const configuredLife = parts
+		.find((part) => part.startsWith("life-"))
+		?.slice("life-".length);
+	const baseUsername = parts
+		.filter((part) => !part.startsWith("session-") && !part.startsWith("life-"))
+		.join("_");
+	return `${baseUsername}_session-${sessionId}_life-${sessionDuration ?? configuredLife ?? "60"}`;
+}
+
+function buildDecodoUsername(
+	username: string,
+	sessionId: string,
+	sessionDuration: string,
+): string {
+	const withoutSticky = username.replace(
+		/-session-.+-sessionduration-\d+$/,
+		"",
+	);
+	const baseUsername = withoutSticky.startsWith("user-")
+		? withoutSticky
+		: `user-${withoutSticky}`;
+	return `${baseUsername}-session-${sessionId}-sessionduration-${sessionDuration}`;
 }
 
 function syncProxyEnv(config: ApiFuseConfig): void {