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

package/bin/apifuse-pack-smoke.ts

@@ -0,0 +1,296 @@
+#!/usr/bin/env bun
+
+import {
+	type ChildProcess,
+	execFileSync,
+	spawn,
+	spawnSync,
+} from "node:child_process";
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+
+const PACK_RESULT_SCHEMA = z.array(
+	z.object({
+		filename: z.string(),
+	}),
+);
+const HEALTH_RESPONSE_SCHEMA = z.object({
+	status: z.string(),
+	provider: z.string(),
+	version: z.string().optional(),
+});
+const PING_RESPONSE_SCHEMA = z.object({
+	data: z
+		.object({
+			ok: z.boolean(),
+			message: z.string(),
+		})
+		.optional(),
+	error: z.unknown().optional(),
+});
+
+const KEEP_TEMP = process.env.APIFUSE_PACK_SMOKE_KEEP_TEMP === "1";
+
+const tempRoot = mkdtempSync(
+	join(tmpdir(), "apifuse-provider-sdk-pack-smoke-"),
+);
+const packDir = join(tempRoot, "pack");
+const consumerDir = join(tempRoot, "consumer");
+
+try {
+	mkdirSync(packDir, { recursive: true });
+	mkdirSync(consumerDir, { recursive: true });
+
+	const packed = packSdk(packDir);
+	const tarballPath = resolve(packDir, packed.filename);
+	const tarballSpecifier = `file:${tarballPath}`;
+
+	writeFileSync(
+		join(consumerDir, "package.json"),
+		`${JSON.stringify(
+			{
+				private: true,
+				type: "module",
+				dependencies: {
+					"@apifuse/provider-sdk": tarballSpecifier,
+				},
+			},
+			null,
+			2,
+		)}\n`,
+	);
+
+	run("bun", ["install"], consumerDir);
+
+	const cliBin = join(consumerDir, "node_modules", ".bin", "apifuse");
+	if (!existsSync(cliBin)) {
+		throw new Error(`Expected CLI bin at ${cliBin}`);
+	}
+
+	run(
+		"bun",
+		[
+			cliBin,
+			"create",
+			"dx-smoke",
+			"--yes",
+			"--json",
+			"--sdk-specifier",
+			tarballSpecifier,
+		],
+		consumerDir,
+	);
+
+	const generatedProviderDir = join(consumerDir, "dx-smoke");
+	run("bun", ["run", "check"], generatedProviderDir);
+	run("bun", ["run", "test"], generatedProviderDir);
+	assertGeneratedReadme(generatedProviderDir);
+	await smokeGeneratedDevServer(generatedProviderDir);
+
+	console.log(
+		`Provider SDK packed-artifact smoke passed: ${tarballPath} -> ${generatedProviderDir}`,
+	);
+} finally {
+	if (KEEP_TEMP) {
+		console.log(`Keeping smoke temp directory: ${tempRoot}`);
+	} else {
+		rmSync(tempRoot, { recursive: true, force: true });
+	}
+}
+
+function packSdk(destination: string): { filename: string } {
+	const raw = execFileSync(
+		"npm",
+		["pack", "--json", "--pack-destination", destination],
+		{
+			cwd: process.cwd(),
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "inherit"],
+		},
+	);
+	const parsed = PACK_RESULT_SCHEMA.parse(JSON.parse(raw));
+	const first = parsed[0];
+	if (!first) {
+		throw new Error("npm pack --json returned no package metadata.");
+	}
+	return first;
+}
+
+function run(command: string, args: string[], cwd: string): void {
+	const result = spawnSync(command, args, {
+		cwd,
+		env: process.env,
+		stdio: "inherit",
+	});
+
+	if (result.error) {
+		throw result.error;
+	}
+
+	if (result.status !== 0) {
+		throw new Error(
+			`Command failed (${[command, ...args].join(" ")}) in ${cwd} with exit code ${result.status}`,
+		);
+	}
+}
+
+function assertGeneratedReadme(providerDir: string): void {
+	const readme = readFileSync(join(providerDir, "README.md"), "utf8");
+	if (!readme.includes('"requestId":"req_local_ping"')) {
+		throw new Error(
+			"Generated README is missing requestId in local smoke docs.",
+		);
+	}
+	if (readme.includes('"connection":null')) {
+		throw new Error(
+			"Generated README must not document connection:null for no-auth local smoke.",
+		);
+	}
+	if (!readme.includes("bunx playwright install chromium")) {
+		throw new Error(
+			"Generated README is missing browser runtime troubleshooting guidance.",
+		);
+	}
+	if (!readme.includes("bun pm untrusted")) {
+		throw new Error(
+			"Generated README is missing Bun trusted-dependency troubleshooting guidance.",
+		);
+	}
+	if (!readme.includes("bun run record -- --operation <operation>")) {
+		throw new Error(
+			"Generated README must document fixture recording through the generated record script.",
+		);
+	}
+}
+
+async function smokeGeneratedDevServer(providerDir: string): Promise<void> {
+	const port = await getAvailablePort();
+	const server = spawn("bun", ["run", "dev"], {
+		cwd: providerDir,
+		env: { ...process.env, PORT: String(port) },
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+	let output = "";
+	server.stdout?.on("data", (chunk) => {
+		output += chunk.toString();
+	});
+	server.stderr?.on("data", (chunk) => {
+		output += chunk.toString();
+	});
+
+	try {
+		const baseUrl = `http://127.0.0.1:${port}`;
+		await waitForHttp(`${baseUrl}/health`, server, () => output);
+
+		const health = await fetchJson(`${baseUrl}/health`, HEALTH_RESPONSE_SCHEMA);
+		if (health.status !== "ok" || health.provider !== "dx-smoke") {
+			throw new Error(`Unexpected /health payload: ${JSON.stringify(health)}`);
+		}
+
+		const response = await fetch(`${baseUrl}/v1/ping`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				requestId: "req_pack_smoke_ping",
+				input: { value: "hello" },
+				headers: {},
+			}),
+		});
+		const payload = PING_RESPONSE_SCHEMA.parse(await response.json());
+
+		if (!response.ok || payload.data?.ok !== true) {
+			throw new Error(
+				`Unexpected /v1/ping response (${response.status}): ${JSON.stringify(payload)}`,
+			);
+		}
+	} finally {
+		await stopServer(server);
+	}
+}
+
+async function getAvailablePort(): Promise<number> {
+	return await new Promise((resolvePromise, rejectPromise) => {
+		const server = createServer();
+		server.once("error", rejectPromise);
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			server.close((error) => {
+				if (error) {
+					rejectPromise(error);
+					return;
+				}
+				if (!address || typeof address === "string") {
+					rejectPromise(new Error("Could not allocate a local TCP port."));
+					return;
+				}
+				resolvePromise(address.port);
+			});
+		});
+	});
+}
+
+async function fetchJson<T>(url: string, schema: z.ZodType<T>): Promise<T> {
+	const response = await fetch(url);
+	if (!response.ok) {
+		throw new Error(`${url} returned ${response.status}`);
+	}
+	return schema.parse(await response.json());
+}
+
+async function waitForHttp(
+	url: string,
+	server: ChildProcess,
+	getOutput: () => string,
+): Promise<void> {
+	const deadline = Date.now() + 10_000;
+	let lastError: unknown;
+
+	while (Date.now() < deadline) {
+		if (server.exitCode !== null) {
+			throw new Error(
+				`Dev server exited early with code ${server.exitCode}\n${getOutput()}`,
+			);
+		}
+
+		try {
+			await fetchJson(url, HEALTH_RESPONSE_SCHEMA);
+			return;
+		} catch (error) {
+			lastError = error;
+			await new Promise((resolve) => setTimeout(resolve, 200));
+		}
+	}
+
+	throw new Error(
+		`Timed out waiting for ${url}: ${lastError instanceof Error ? lastError.message : String(lastError)}\n${getOutput()}`,
+	);
+}
+
+async function stopServer(server: ChildProcess): Promise<void> {
+	if (server.exitCode !== null) {
+		return;
+	}
+	server.kill("SIGTERM");
+	await new Promise<void>((resolvePromise) => {
+		const timeout = setTimeout(() => {
+			if (server.exitCode === null) {
+				server.kill("SIGKILL");
+			}
+			resolvePromise();
+		}, 2_000);
+		server.once("exit", () => {
+			clearTimeout(timeout);
+			resolvePromise();
+		});
+	});
+}

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.0",
+	"version": "2.1.0-beta.2",
 	"private": false,
 	"type": "module",
-	"description": "ApiFuse Provider SDK \u2014 Build providers with zero architectural constraints",
+	"description": "ApiFuse Provider SDK — Build providers with zero architectural constraints",
 	"license": "MIT",
 	"main": "./src/index.ts",
 	"types": "./src/index.ts",
@@ -61,23 +61,24 @@
 		"type-check": "tsgo --noEmit",
 		"test": "bun test",
 		"check": "bun run lint && bun run type-check",
-		"pack:check": "bun bin/apifuse-pack-check.ts"
+		"pack:check": "bun bin/apifuse-pack-check.ts",
+		"pack:smoke": "bun bin/apifuse-pack-smoke.ts"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.12",
-		"@clack/prompts": "^1.2.0",
+		"@biomejs/biome": "^2.4.15",
 		"@types/bun": "latest",
-		"@types/node": "^25.1.0",
+		"@types/node": "^25.8.0",
 		"typescript": "^6.0.3"
 	},
 	"dependencies": {
+		"@clack/prompts": "^1.4.0",
 		"ajv": "^8.17",
-		"hono": "^4.12.14",
+		"hono": "^4.12.19",
 		"playwright": "^1.55.1",
 		"playwright-stealth": "^0.0.1",
 		"re2-wasm": "^1.0",
 		"safe-regex": "^2.1",
 		"tlsclientwrapper": "^4.2.0",
-		"zod": "^4.3.6"
+		"zod": "^4.4.3"
 	}
 }

package/src/ceremonies/index.ts

@@ -63,6 +63,7 @@ const DEVICE_FLOW_KEY = "__device_flow";
 const MAGIC_LINK_KEY = "__magic_link";
 const COMBINED_STAGE_KEY = "__combined_stage";
 const SWITCH_SELECTION_KEY = "__switch_selection";
+const FORM_FIELD_ORDER_EXTENSION = "x-apifuse-field-order";
 
 function isRecord(value: unknown): value is JsonObject {
 	return !!value && typeof value === "object" && !Array.isArray(value);
@@ -175,11 +176,31 @@ function buildJsonSchemaForm(
 ): AuthTurn {
 	return createTurn("form", {
 		hint,
-		expectedInput,
+		expectedInput: withDeclaredFormFieldOrder(expectedInput),
 		data: {},
 	});
 }
 
+function withDeclaredFormFieldOrder(expectedInput: JsonObject): JsonObject {
+	const properties = expectedInput.properties;
+	if (!isRecord(properties)) {
+		return expectedInput;
+	}
+
+	const existingOrder = expectedInput[FORM_FIELD_ORDER_EXTENSION];
+	if (
+		Array.isArray(existingOrder) &&
+		existingOrder.every((value) => typeof value === "string")
+	) {
+		return expectedInput;
+	}
+
+	return {
+		...expectedInput,
+		[FORM_FIELD_ORDER_EXTENSION]: Object.keys(properties),
+	};
+}
+
 export function validateCeremonyOutput(turn: unknown): AuthTurn {
 	if (!validateAuthTurn(turn)) {
 		const detail = validateAuthTurn.errors

package/src/cli/create.ts

@@ -479,7 +479,7 @@ export async function buildProviderCreatePlan(
 				RUNTIME: options.runtime,
 				BROWSER_BLOCK:
 					options.runtime === "browser"
-						? ',\n  browser: {\n    engine: "nodriver",\n  }'
+						? ',\n  browser: {\n    engine: "playwright-stealth",\n  }'
 						: "",
 				SECRETS_BLOCK: renderSecretsBlock(options.authMode),
 				CREDENTIAL_BLOCK: renderCredentialBlock(options.authMode),
@@ -568,9 +568,8 @@ function renderPackageJson(input: {
 			scripts: {
 				dev: "apifuse dev .",
 				check: "apifuse check .",
-				"record:sample":
-					'apifuse record . --operation ping --params \'{"value":"hello"}\'',
 				test: "apifuse test .",
+				record: "apifuse record .",
 				"perf:sample": "apifuse perf . --operation ping --runs 3",
 				start: "bun start.ts",
 			},

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

@@ -21,8 +21,63 @@ bun run test
 - `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`.
+- TLS/browser runtime: if Bun blocks native dependency lifecycle scripts, run
+  `bun pm untrusted` and trust SDK dependencies such as `koffi` before debugging
+  `ctx.tls`; for TypeScript browser Providers use
+  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only),
+  then install local Chromium with `bunx playwright install chromium` or set
+  `CDP_POOL_URL`.
+
 ## 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. Extend tests and operation metadata until the provider is bounty-ready.
+2. Once the real operation declares `upstream.baseUrl` and uses `ctx.http` or
+   `ctx.tls`, 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.

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

@@ -4,7 +4,6 @@ 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.");
@@ -49,6 +48,10 @@ export default defineProvider({
         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/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 {

package/src/define.ts

@@ -233,8 +233,10 @@ const HEALTH_CHECK_CASE_FIELDS = new Set([
 const HEALTH_CHECK_UNSUPPORTED_FIELDS = new Set(["reason", "trackedIn"]);
 const PROVIDER_HEALTH_MONITOR_FIELDS = new Set([
 	"requiredSecrets",
+	"probeOverrides",
 	"serviceAccount",
 ]);
+const PROVIDER_HEALTH_MONITOR_PROBE_OVERRIDE_FIELDS = new Set(["interval"]);
 
 function levenshtein(a: string, b: string): number {
 	const m = a.length;
@@ -307,13 +309,13 @@ function validateProviderHealthMonitor(
 				fix: `Set healthMonitor to { requiredSecrets?: string[]; serviceAccount?: string }`,
 			},
 		);
+	const healthMonitorRecord = Object.fromEntries(Object.entries(healthMonitor));
 	rejectUnknownFields(
-		healthMonitor as Record<string, unknown>,
+		healthMonitorRecord,
 		PROVIDER_HEALTH_MONITOR_FIELDS,
 		"healthMonitor",
 	);
-	const requiredSecrets = (healthMonitor as ProviderHealthMonitorConfig)
-		.requiredSecrets;
+	const requiredSecrets = healthMonitorRecord.requiredSecrets;
 	if (requiredSecrets !== undefined) {
 		if (!Array.isArray(requiredSecrets))
 			throw new ValidationError(
@@ -326,8 +328,44 @@ function validateProviderHealthMonitor(
 				);
 		}
 	}
-	const serviceAccount = (healthMonitor as ProviderHealthMonitorConfig)
-		.serviceAccount;
+	const probeOverrides = healthMonitorRecord.probeOverrides;
+	if (probeOverrides !== undefined) {
+		if (
+			!probeOverrides ||
+			typeof probeOverrides !== "object" ||
+			Array.isArray(probeOverrides)
+		)
+			throw new ValidationError(
+				`Provider "${providerId}" has invalid healthMonitor.probeOverrides: must be an object keyed by probe id.`,
+			);
+		for (const [probeId, override] of Object.entries(probeOverrides)) {
+			if (probeId.length === 0)
+				throw new ValidationError(
+					`Provider "${providerId}" has invalid healthMonitor.probeOverrides key: must be a non-empty probe id.`,
+				);
+			if (!override || typeof override !== "object" || Array.isArray(override))
+				throw new ValidationError(
+					`Provider "${providerId}" has invalid healthMonitor.probeOverrides["${probeId}"]: must be an object.`,
+				);
+			const overrideRecord = Object.fromEntries(Object.entries(override));
+			rejectUnknownFields(
+				overrideRecord,
+				PROVIDER_HEALTH_MONITOR_PROBE_OVERRIDE_FIELDS,
+				`healthMonitor.probeOverrides["${probeId}"]`,
+			);
+			const interval = overrideRecord.interval;
+			const validProbeIntervals: readonly string[] = PROBE_INTERVALS;
+			if (
+				interval !== undefined &&
+				(typeof interval !== "string" ||
+					!validProbeIntervals.includes(interval))
+			)
+				throw new ValidationError(
+					`Provider "${providerId}" has invalid healthMonitor.probeOverrides["${probeId}"].interval: must be one of ${PROBE_INTERVALS.join(", ")}.`,
+				);
+		}
+	}
+	const serviceAccount = healthMonitorRecord.serviceAccount;
 	if (
 		serviceAccount !== undefined &&
 		(typeof serviceAccount !== "string" || serviceAccount.length === 0)
@@ -591,7 +629,7 @@ export function defineProvider<
 		throw new ProviderError(
 			`Provider "${config.id}" must define browser.engine when runtime is "browser"`,
 			{
-				fix: 'Add browser: { engine: "nodriver" } or another supported engine',
+				fix: 'Add browser: { engine: "playwright-stealth" } for TypeScript providers, or another supported engine for your runtime',
 			},
 		);
 	if (config.browser && config.runtime !== "browser")

package/src/index.ts

@@ -2,12 +2,6 @@
 
 export { z } from "zod";
 export * from "./ceremonies";
-export {
-	type ClarifyResponse,
-	type CompositeContext,
-	type CompositeOperationDefinition,
-	defineCompositeOperation,
-} from "./composite";
 export type {
 	ApiFuseConfig,
 	BrowserConfig,

package/src/provider.ts

@@ -1,7 +1,6 @@
 export { z } from "zod";
 
 export { createFormCeremony } from "./ceremonies";
-export { defineCompositeOperation } from "./composite";
 export { defineOperation, defineProvider } from "./define";
 export { AuthError, ProviderError, ValidationError } from "./errors";
 export type {