@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.31

package/bin/apifuse-dev.ts

@@ -2,22 +2,27 @@
 
 import { existsSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
-import type { ProviderDefinition } from "../src";
 import {
-	createBrowserClient,
 	createCredentialContext,
 	createEnvContext,
 	createHttpClient,
+	createOcrClientFromEnv,
 	createProviderCache,
 	createProviderChoiceContext,
-	createStealthClient,
+	createUnsupportedResolverClient,
 	createSttClientFromEnv,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	type ProviderDefinition,
 	ProviderError,
-} from "../src";
-import { createMemoryProviderRuntimeState } from "../src/runtime/state";
-import { createTraceContext } from "../src/runtime/trace";
-import type { BrowserClient, ProviderContext } from "../src/types";
+	type ProviderProxyPolicy,
+} from "../src/index.js";
+import { createBrowserClient } from "../src/runtime/browser.js";
+import { createResolverClientFromEnv } from "../src/runtime/resolver.js";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
+import { createStealthClient } from "../src/runtime/stealth.js";
+import { createTraceContext } from "../src/runtime/trace.js";
+import { getStealthProfile } from "../src/stealth/profiles.js";
+import type { BrowserClient, ProviderContext } from "../src/types.js";
 
 const HELP_TEXT = `Usage: apifuse dev [path]
 Example: apifuse dev providers/korea-air-quality
@@ -33,12 +38,9 @@ export async function main() {
 
 	const providerPath = resolveProviderPath(args[0] ?? ".");
 	const providerModule = await import(resolve(providerPath, "index.ts"));
-	const provider = assertProviderDefinition(
-		providerModule.default,
-		providerPath,
-	);
+	const provider = assertProviderDefinition(providerModule.default, providerPath);
 
-	const { startDevServer } = await import("../src/dev");
+	const { startDevServer } = await import("../src/dev.js");
 	const port = Number(process.env.APIFUSE__RUNTIME__PORT) || 3900;
 
 	startDevServer(provider, { port });
@@ -57,8 +59,7 @@ export async function main() {
 
 	const firstOperation = Object.keys(provider.operations)[0];
 	if (firstOperation) {
-		const sampleInput =
-			provider.operations[firstOperation]?.fixtures?.request ?? {};
+		const sampleInput = provider.operations[firstOperation]?.fixtures?.request ?? {};
 		const sampleBody = JSON.stringify({
 			requestId: `req_local_${firstOperation}`,
 			input: sampleInput,
@@ -84,6 +85,11 @@ export function createProviderContext(provider: ProviderDefinition): {
 	]);
 	const credential = createCredentialContext();
 	const state = createMemoryProviderRuntimeState();
+	const cache = createProviderCache({ providerId: provider.id });
+	const proxyPolicy = resolveNativeProxyPolicy(provider);
+	const stealthProfile = provider.stealth?.profile
+		? getStealthProfile(provider.stealth.profile)
+		: undefined;
 	const ctx: ProviderContext = {
 		env,
 		credential,
@@ -96,11 +102,27 @@ export function createProviderContext(provider: ProviderDefinition): {
 					})
 				: createUnsupportedBrowserStub(),
 		http: createHttpClient(),
-		cache: createProviderCache({ providerId: provider.id }),
+		cache,
 		state,
 		trace: createTraceContext(),
 		stealth: createStealthClient("http://localhost"),
+		ocr: createOcrClientFromEnv(provider.ocr),
 		stt: createSttClientFromEnv(provider.stt),
+		resolver: provider.resolver
+			? createResolverClientFromEnv(provider.resolver, undefined, {
+					allowedHosts: provider.allowedHosts,
+					cache,
+					...(proxyPolicy
+						? {
+								proxyIntent: {
+									mode: proxyPolicy.mode,
+									upstream: { proxy: provider.proxy },
+									...(stealthProfile ? { userAgent: stealthProfile.userAgent } : {}),
+								},
+							}
+						: {}),
+				})
+			: createUnsupportedResolverClient("Provider does not declare resolver capability"),
 		choice: createProviderChoiceContext({
 			providerId: provider.id,
 			env,
@@ -112,6 +134,13 @@ export function createProviderContext(provider: ProviderDefinition): {
 	return { ctx };
 }
 
+function resolveNativeProxyPolicy(provider: ProviderDefinition): ProviderProxyPolicy | undefined {
+	if (typeof provider.proxy === "object") return provider.proxy;
+	if (provider.proxy === true) return { mode: "optional" };
+	if (provider.proxy === false) return { mode: "disabled" };
+	return undefined;
+}
+
 function normalizeArgs(argv: string[]): string[] {
 	return argv[0] === "dev" ? argv.slice(1) : argv;
 }
@@ -149,9 +178,7 @@ function renderHotReloadCommand(providerPath: string, port: number): string {
 	const devEntry = resolve(providerPath, "dev.ts");
 	if (existsSync(devEntry)) {
 		const relativeDevEntry = relative(process.cwd(), devEntry) || "dev.ts";
-		const portPrefix = process.env.APIFUSE__RUNTIME__PORT
-			? `APIFUSE__RUNTIME__PORT=${port} `
-			: "";
+		const portPrefix = process.env.APIFUSE__RUNTIME__PORT ? `APIFUSE__RUNTIME__PORT=${port} ` : "";
 		return `${portPrefix}bun --hot ${relativeDevEntry}`;
 	}
 	return "rerun `apifuse dev` after edits (no dev.ts entrypoint found)";
@@ -166,40 +193,28 @@ function createUnsupportedBrowserStub(): BrowserClient {
 		engine: "playwright-stealth",
 		async close() {},
 		async newPage() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" to use ctx.browser',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" to use ctx.browser',
+			});
 		},
 		async rawPage() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" and APIFUSE__CDP_POOL__URL to use ctx.browser.rawPage',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" and APIFUSE__CDP_POOL__URL to use ctx.browser.rawPage',
+			});
 		},
 		async withIsolatedContext() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" to use ctx.browser.withIsolatedContext',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" to use ctx.browser.withIsolatedContext',
+			});
 		},
 		async solveChallenge() {
-			throw new ProviderError(
-				"Browser runtime is not enabled for this provider",
-				{
-					code: "BROWSER_RUNTIME_UNSUPPORTED",
-					fix: 'Set provider runtime to "browser" to use ctx.browser.solveChallenge',
-				},
-			);
+			throw new ProviderError("Browser runtime is not enabled for this provider", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+				fix: 'Set provider runtime to "browser" to use ctx.browser.solveChallenge',
+			});
 		},
 	};
 }
@@ -216,10 +231,7 @@ function createUnsupportedAuthStub() {
 	};
 }
 
-function assertProviderDefinition(
-	value: unknown,
-	providerPath: string,
-): ProviderDefinition {
+function assertProviderDefinition(value: unknown, providerPath: string): ProviderDefinition {
 	if (!isProviderDefinition(value)) {
 		throw new Error(
 			`Expected ${resolve(providerPath, "index.ts")} to export default defineProvider(...)`,
@@ -230,11 +242,7 @@ function assertProviderDefinition(
 }
 
 function isProviderDefinition(value: unknown): value is ProviderDefinition {
-	if (
-		!isRecord(value) ||
-		!isRecord(value.meta) ||
-		!isRecord(value.operations)
-	) {
+	if (!isRecord(value) || !isRecord(value.meta) || !isRecord(value.operations)) {
 		return false;
 	}
 

package/bin/apifuse-pack-check.ts

@@ -48,6 +48,13 @@ const requiredPaths = [
 	"src/cli/templates/provider/operations/ping.ts.tpl",
 	"src/cli/templates/provider/schemas/ping.ts.tpl",
 	"src/cli/templates/provider/upstream/README.md.tpl",
+	"src/cli/templates/provider/AGENTS.md.tpl",
+	"src/cli/templates/provider/.agents/skills/normalization-standards/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/upstream-contract-verification/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/fixtures-and-recording/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/pagination-and-counts/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/health-checks-and-fail-closed/SKILL.md.tpl",
+	"src/cli/templates/provider/.agents/skills/upstream-notes/README.md.tpl",
 	"dist/cli/templates/provider/.dockerignore.tpl",
 	"dist/cli/templates/provider/.gitignore.tpl",
 	"dist/cli/templates/provider/Dockerfile.tpl",
@@ -60,6 +67,13 @@ const requiredPaths = [
 	"dist/cli/templates/provider/operations/ping.ts.tpl",
 	"dist/cli/templates/provider/schemas/ping.ts.tpl",
 	"dist/cli/templates/provider/upstream/README.md.tpl",
+	"dist/cli/templates/provider/AGENTS.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/normalization-standards/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/upstream-contract-verification/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/fixtures-and-recording/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/pagination-and-counts/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/health-checks-and-fail-closed/SKILL.md.tpl",
+	"dist/cli/templates/provider/.agents/skills/upstream-notes/README.md.tpl",
 	"dist/auth-turn/index.js",
 	"dist/auth-turn/index.d.ts",
 	"dist/auth-turn/auth-turn.v1.schema.json",
@@ -142,9 +156,9 @@ function assertPublicSmokeDocs(label: string, content: string): void {
 		);
 	}
 
-	if (!content.includes("impit")) {
+	if (!content.includes("wreq-js")) {
 		throw new Error(
-			`${label} must include impit stealth runtime guidance for TLS/browser bounties.`,
+			`${label} must include wreq-js stealth runtime guidance for TLS/browser bounties.`,
 		);
 	}
 
@@ -154,6 +168,12 @@ function assertPublicSmokeDocs(label: string, content: string): void {
 		);
 	}
 
+	if (!content.includes("Chrome, Firefox, and Safari")) {
+		throw new Error(
+			`${label} must document the browser families supported by the TypeScript stealth runtime.`,
+		);
+	}
+
 	if (
 		!content.includes('browser.engine: "playwright-stealth"') ||
 		!content.includes("nodriver")

package/bin/apifuse-pack-smoke.ts

@@ -1,19 +1,7 @@
 #!/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 { 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";
@@ -41,9 +29,7 @@ const PING_RESPONSE_SCHEMA = z.object({
 
 const KEEP_TEMP = process.env.APIFUSE__PACK_SMOKE__KEEP_TEMP === "1";
 
-const tempRoot = mkdtempSync(
-	join(tmpdir(), "apifuse-provider-sdk-pack-smoke-"),
-);
+const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-smoke-"));
 const packDir = join(tempRoot, "pack");
 const consumerDir = join(tempRoot, "consumer");
 const externalWorkspaceDir = join(tempRoot, "external-workspace");
@@ -73,6 +59,21 @@ try {
 	);
 
 	run("bun", ["install"], consumerDir);
+	run(
+		"bun",
+		[
+			"--eval",
+			[
+				'import { resolveProxy } from "@apifuse/provider-sdk";',
+				'if (typeof resolveProxy !== "function") throw new Error("resolveProxy is not exported");',
+				'const resolved = await resolveProxy({ proxy: "http://127.0.0.1:8080" });',
+				'if (resolved.url !== "http://127.0.0.1:8080") throw new Error("resolveProxy returned the wrong URL");',
+				'console.log("packed root resolveProxy export OK");',
+			].join("\n"),
+		],
+		consumerDir,
+	);
+	smokePackedStealthNative(consumerDir);
 
 	const cliBin = join(consumerDir, "node_modules", ".bin", "apifuse");
 	if (!existsSync(cliBin)) {
@@ -81,15 +82,7 @@ try {
 
 	run(
 		"bun",
-		[
-			cliBin,
-			"create",
-			"dx-smoke",
-			"--yes",
-			"--json",
-			"--sdk-specifier",
-			tarballSpecifier,
-		],
+		[cliBin, "create", "dx-smoke", "--yes", "--json", "--sdk-specifier", tarballSpecifier],
 		consumerDir,
 	);
 
@@ -99,11 +92,7 @@ try {
 	run("bun", ["run", "test"], generatedProviderDir);
 	assertGeneratedReadme(generatedProviderDir);
 	await smokeGeneratedDevServer(generatedProviderDir);
-	assertExternalWorkspaceTopology(
-		cliBin,
-		externalWorkspaceDir,
-		tarballSpecifier,
-	);
+	assertExternalWorkspaceTopology(cliBin, externalWorkspaceDir, tarballSpecifier);
 
 	console.log(
 		`Provider SDK packed-artifact smoke passed: ${tarballPath} -> ${generatedProviderDir}`,
@@ -148,15 +137,8 @@ function assertExternalWorkspaceTopology(
 		externalWorkspaceDir,
 	);
 
-	const generatedProviderDir = join(
-		externalWorkspaceDir,
-		"external-workspace-smoke",
-	);
-	const forbiddenProviderDir = join(
-		externalWorkspaceDir,
-		"providers",
-		"external-workspace-smoke",
-	);
+	const generatedProviderDir = join(externalWorkspaceDir, "external-workspace-smoke");
+	const forbiddenProviderDir = join(externalWorkspaceDir, "providers", "external-workspace-smoke");
 	if (!existsSync(generatedProviderDir)) {
 		throw new Error(
 			"Public create must generate a one-provider repository at <name>/ even when providers/ exists.",
@@ -168,9 +150,7 @@ function assertExternalWorkspaceTopology(
 		);
 	}
 
-	const packageJson = JSON.parse(
-		readFileSync(join(generatedProviderDir, "package.json"), "utf8"),
-	);
+	const packageJson = JSON.parse(readFileSync(join(generatedProviderDir, "package.json"), "utf8"));
 	const sdkDependency = packageJson?.dependencies?.["@apifuse/provider-sdk"];
 	if (sdkDependency !== tarballSpecifier) {
 		throw new Error(
@@ -178,9 +158,7 @@ function assertExternalWorkspaceTopology(
 		);
 	}
 	if (JSON.stringify(packageJson).includes("workspace:")) {
-		throw new Error(
-			"External bounty workspace scaffold must not contain workspace: dependencies.",
-		);
+		throw new Error("External bounty workspace scaffold must not contain workspace: dependencies.");
 	}
 
 	run("bun", ["install"], generatedProviderDir);
@@ -199,30 +177,20 @@ function assertExternalWorkspaceTopology(
 		},
 	);
 	if (monorepoAttempt.status === 0) {
-		throw new Error(
-			"--preset monorepo must reject outside the private APIFuse monorepo.",
-		);
+		throw new Error("--preset monorepo must reject outside the private APIFuse monorepo.");
 	}
 	const rejectionOutput = `${monorepoAttempt.stdout}\n${monorepoAttempt.stderr}`;
-	if (
-		!rejectionOutput.includes(
-			"Monorepo preset is internal to the APIFuse repository",
-		)
-	) {
+	if (!rejectionOutput.includes("Monorepo preset is internal to the APIFuse repository")) {
 		throw new Error(`Unexpected monorepo rejection output: ${rejectionOutput}`);
 	}
 }
 
 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 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) {
@@ -249,32 +217,62 @@ function run(command: string, args: string[], cwd: string): void {
 	}
 }
 
+function smokePackedStealthNative(consumerDir: string): void {
+	run(
+		"bun",
+		[
+			"--eval",
+			[
+				'import { createServer } from "node:http";',
+				'import { createStealthClient } from "@apifuse/provider-sdk/runtime/stealth";',
+				"const server = createServer((_request, response) => {",
+				'  response.setHeader("set-cookie", "pack_native_cookie=landed; Path=/");',
+				'  response.end("packed native stealth ok");',
+				"});",
+				"await new Promise((resolve, reject) => {",
+				'  server.once("error", reject);',
+				'  server.listen(0, "127.0.0.1", resolve);',
+				"});",
+				"const address = server.address();",
+				'if (!address || typeof address === "string") throw new Error("Local server has no TCP address");',
+				'const baseUrl = "http://127.0.0.1:" + address.port;',
+				'const session = createStealthClient(baseUrl).createSession({ profile: "safari-17" });',
+				"try {",
+				'  const response = await session.fetch("/native");',
+				'  if (response.body !== "packed native stealth ok") throw new Error("Unexpected stealth body: " + response.body);',
+				'  if (session.cookies.get("pack_native_cookie", baseUrl + "/native") !== "landed") {',
+				'    throw new Error("Packed stealth Set-Cookie did not land in the SDK jar");',
+				"  }",
+				'  console.log("packed native Safari stealth request OK");',
+				"} finally {",
+				"  session.close();",
+				"  await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));",
+				"}",
+			].join("\n"),
+		],
+		consumerDir,
+	);
+}
+
 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.",
-		);
+		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.",
-		);
+		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.",
-		);
+		throw new Error("Generated README is missing browser runtime troubleshooting guidance.");
 	}
-	if (!readme.includes("impit")) {
-		throw new Error(
-			"Generated README is missing impit stealth runtime guidance.",
-		);
+	if (!readme.includes("wreq-js")) {
+		throw new Error("Generated README is missing wreq-js stealth runtime guidance.");
+	}
+	if (!readme.includes("Chrome, Firefox, and Safari")) {
+		throw new Error("Generated README is missing supported stealth browser families.");
 	}
 	if (!readme.includes("bun run submit-check")) {
-		throw new Error(
-			"Generated README must document the submit-check pre-submission workflow.",
-		);
+		throw new Error("Generated README must document the submit-check pre-submission workflow.");
 	}
 	if (!readme.includes("bun run record -- --operation <operation>")) {
 		throw new Error(
@@ -368,9 +366,7 @@ async function waitForHttp(
 
 	while (Date.now() < deadline) {
 		if (server.exitCode !== null) {
-			throw new Error(
-				`Dev server exited early with code ${server.exitCode}\n${getOutput()}`,
-			);
+			throw new Error(`Dev server exited early with code ${server.exitCode}\n${getOutput()}`);
 		}
 
 		try {