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

package/bin/apifuse-record.ts

@@ -7,14 +7,21 @@ import { basename, dirname, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import {
+	createBypassProviderCache,
 	createHttpClient,
-	createTlsClient,
+	createProviderChoiceContext,
+	createStealthClient,
+	createSttClientFromEnv,
 	executeOperation,
 	type HttpClient,
 	type ProviderContext,
 	type ProviderDefinition,
-	type TlsClient,
+	ProviderError,
+	type StealthClient,
+	TransportError,
+	ValidationError,
 } from "../src";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state";
 
 type CliArgs = {
 	append: boolean;
@@ -28,55 +35,77 @@ type ProviderRuntime = ProviderDefinition;
 
 type MutableRecord = Record<string, unknown>;
 
-export async function main() {
-	const args = parseArgs(normalizeArgs(process.argv.slice(2)));
-	const location = resolveProviderLocation(args.providerPath);
-	const provider = await loadProvider(location.rootDir);
-	const operationName = resolveOperationName(provider, args.operation);
-	const operation = provider.operations[operationName];
-	const parsedParams = parseParams(operation, args.params);
-
-	const capture = createCaptureContext(
-		resolveOperationBaseUrl(provider, operationName),
-	);
+const HELP_TEXT = `Usage: apifuse record [path] --operation <operation> --params '<json>'
 
-	console.log(`[apifuse record] Calling ${operationName} on ${provider.id}...`);
+Calls a real upstream-backed operation through ctx.http or ctx.stealth and writes __fixtures__/raw.json.
 
-	const result = await executeOperation(
-		provider,
-		operationName,
-		capture.ctx,
-		parsedParams,
-	);
-	const captured = capture.getCapturedRaw();
+Options:
+  --operation, -o <name>   operation to call
+  --params, -p <json>      JSON input passed to the operation (default: {})
+  --append                 append to an existing array fixture
+  --sanitize               redact common token/header fields (default)
+  --no-sanitize            write the captured upstream payload as-is
+  --help, -h               show this help
 
-	if (captured === undefined) {
-		throw new Error(
-			`No upstream response was captured for ${provider.id}.${operationName}.`,
+Example:
+  apifuse record providers/korea-air-quality --operation realtime --params '{"stationName":"jongno"}'`;
+
+export async function main() {
+	try {
+		const args = parseArgs(normalizeArgs(process.argv.slice(2)));
+		const location = resolveProviderLocation(args.providerPath);
+		const provider = await loadProvider(location.rootDir);
+		const operationName = resolveOperationName(provider, args.operation);
+		const operation = provider.operations[operationName];
+		const parsedParams = parseParams(operation, args.params);
+
+		const capture = createCaptureContext(
+			provider,
+			resolveOperationBaseUrl(provider, operationName),
 		);
-	}
 
-	const rawPayload = args.sanitize ? sanitizeFixture(captured) : captured;
-	const fixturePath = resolve(location.rootDir, "__fixtures__", "raw.json");
-	const nextPayload = await prepareFixturePayload(
-		fixturePath,
-		rawPayload,
-		args.append,
-	);
+		console.log(
+			`[apifuse record] Calling ${operationName} on ${provider.id}...`,
+		);
 
-	await mkdir(dirname(fixturePath), { recursive: true });
-	await writeFile(fixturePath, `${JSON.stringify(nextPayload, null, 2)}\n`);
+		const result = await executeOperation(
+			provider,
+			operationName,
+			capture.ctx,
+			parsedParams,
+		);
+		const captured = capture.getCapturedRaw();
 
-	console.log(
-		`[apifuse record] Captured response (${formatBytes(
-			Buffer.byteLength(JSON.stringify(rawPayload)),
-		)})`,
-	);
-	console.log(
-		`[apifuse record] Saved to ${relative(process.cwd(), fixturePath)}`,
-	);
+		if (captured === undefined) {
+			throw new Error(
+				`No upstream response was captured for ${provider.id}.${operationName}.`,
+			);
+		}
 
-	void result;
+		const rawPayload = args.sanitize ? sanitizeFixture(captured) : captured;
+		const fixturePath = resolve(location.rootDir, "__fixtures__", "raw.json");
+		const nextPayload = await prepareFixturePayload(
+			fixturePath,
+			rawPayload,
+			args.append,
+		);
+
+		await mkdir(dirname(fixturePath), { recursive: true });
+		await writeFile(fixturePath, `${JSON.stringify(nextPayload, null, 2)}\n`);
+
+		console.log(
+			`[apifuse record] Captured response (${formatBytes(
+				Buffer.byteLength(JSON.stringify(rawPayload)),
+			)})`,
+		);
+		console.log(
+			`[apifuse record] Saved to ${relative(process.cwd(), fixturePath)}`,
+		);
+
+		void result;
+	} catch (error) {
+		handleCliError(error);
+	}
 }
 
 function normalizeArgs(argv: string[]): string[] {
@@ -104,6 +133,11 @@ function parseArgs(argv: string[]): CliArgs {
 			continue;
 		}
 
+		if (arg === "--help" || arg === "-h") {
+			console.log(HELP_TEXT);
+			process.exit(0);
+		}
+
 		if (arg.startsWith("--operation=")) {
 			operation = arg.slice("--operation=".length);
 			continue;
@@ -155,6 +189,43 @@ function parseArgs(argv: string[]): CliArgs {
 	return { append, providerPath, operation, params, sanitize };
 }
 
+function handleCliError(error: unknown): never {
+	const message = formatCliError(error);
+	console.error(`[apifuse record] ${message}`);
+	process.exit(1);
+}
+
+function formatCliError(error: unknown): string {
+	if (error instanceof TransportError) {
+		return [
+			error.message,
+			error.upstreamStatus ? `status=${error.upstreamStatus}` : undefined,
+			error.options?.retryable !== undefined
+				? `retryable=${String(error.options.retryable)}`
+				: undefined,
+			error.fix ? `fix=${error.fix}` : undefined,
+		]
+			.filter(Boolean)
+			.join(" ");
+	}
+
+	if (error instanceof ProviderError || error instanceof ValidationError) {
+		return [
+			error.message,
+			error.code ? `code=${error.code}` : undefined,
+			error.fix,
+		]
+			.filter(Boolean)
+			.join(" ");
+	}
+
+	if (error instanceof Error) {
+		return error.message;
+	}
+
+	return String(error);
+}
+
 function resolveProviderLocation(inputPath?: string) {
 	const originalInput = inputPath ?? process.cwd();
 	const resolvedInput = resolve(process.cwd(), originalInput);
@@ -269,34 +340,53 @@ function resolveOperationBaseUrl(
 	return baseUrl;
 }
 
-function createCaptureContext(baseUrl: string) {
+function createCaptureContext(provider: ProviderRuntime, baseUrl: string) {
 	let capturedRaw: unknown;
 
 	const http = proxyHttpClient(createHttpClient(baseUrl), (response) => {
 		capturedRaw = response.data;
 	});
-	const tls = proxyTlsClient(createTlsClient(baseUrl), (response) => {
-		capturedRaw = normalizeCapturedTlsResponse(response);
-	});
+	const stealth = proxyStealthClient(
+		createStealthClient(baseUrl),
+		(response) => {
+			capturedRaw = normalizeCapturedStealthResponse(response);
+		},
+	);
 
+	const env = {
+		get: (key: string) => process.env[key],
+	};
+	const credential = {
+		mode: "none" as const,
+		get: () => undefined,
+		getAll: () => ({}),
+		getAccessToken: () => undefined,
+		getScopes: () => [],
+	};
+	const state = createMemoryProviderRuntimeState();
 	const ctx: ProviderContext = {
-		env: {
-			get: (key) => process.env[key],
-		},
-		credential: {
-			mode: "none",
-			get: () => undefined,
-			getAll: () => ({}),
-			getAccessToken: () => undefined,
-			getScopes: () => [],
-		},
+		env,
+		credential,
+		request: { headers: {} },
 		http,
-		tls,
+		cache: createBypassProviderCache({ providerId: provider.id }),
+		state,
+		stealth,
 		browser: {
 			engine: "playwright-stealth",
+			close: async () => {},
 			newPage: async () => {
 				throw new Error("Browser client is not available in apifuse record.");
 			},
+			rawPage: async () => {
+				throw new Error("Browser client is not available in apifuse record.");
+			},
+			withIsolatedContext: async () => {
+				throw new Error("Browser client is not available in apifuse record.");
+			},
+			solveChallenge: async () => {
+				throw new Error("Browser client is not available in apifuse record.");
+			},
 		},
 		trace: {
 			span: async (_name, fn) => fn(),
@@ -306,6 +396,14 @@ function createCaptureContext(baseUrl: string) {
 				throw new Error("Auth prompts are not available in apifuse record.");
 			},
 		},
+		stt: createSttClientFromEnv(provider.stt),
+		choice: createProviderChoiceContext({
+			providerId: provider.id,
+			env,
+			request: { headers: {} },
+			credential,
+			state,
+		}),
 	};
 
 	return {
@@ -335,59 +433,39 @@ function proxyHttpClient(
 	}) as HttpClient;
 }
 
-function proxyTlsClient(
-	client: TlsClient,
-	onResponse: (response: Awaited<ReturnType<TlsClient["fetch"]>>) => void,
-): TlsClient {
-	return new Proxy(client, {
-		get(target, prop, receiver) {
-			const value = Reflect.get(target, prop, receiver);
-
-			if (prop === "fetch" && typeof value === "function") {
-				return async (...args: unknown[]) => {
-					const response = await value.apply(target, args);
-					onResponse(response);
-					return response;
-				};
-			}
+type StealthSession = ReturnType<StealthClient["createSession"]>;
 
-			if (prop === "createSession" && typeof value === "function") {
-				return (...args: unknown[]) => {
-					const session = value.apply(target, args) as ReturnType<
-						TlsClient["createSession"]
-					>;
-					return proxyTlsSession(session, onResponse);
-				};
-			}
-
-			return value;
+function proxyStealthClient(
+	client: StealthClient,
+	onResponse: (response: Awaited<ReturnType<StealthClient["fetch"]>>) => void,
+): StealthClient {
+	return {
+		fetch: async (...args: Parameters<StealthClient["fetch"]>) => {
+			const response = await client.fetch(...args);
+			onResponse(response);
+			return response;
 		},
-	}) as TlsClient;
+		createSession: (...args: Parameters<StealthClient["createSession"]>) =>
+			proxyStealthSession(client.createSession(...args), onResponse),
+	};
 }
 
-function proxyTlsSession(
-	session: ReturnType<TlsClient["createSession"]>,
-	onResponse: (response: Awaited<ReturnType<TlsClient["fetch"]>>) => void,
-) {
-	return new Proxy(session, {
-		get(target, prop, receiver) {
-			const value = Reflect.get(target, prop, receiver);
-
-			if (prop === "fetch" && typeof value === "function") {
-				return async (...args: unknown[]) => {
-					const response = await value.apply(target, args);
-					onResponse(response);
-					return response;
-				};
-			}
-
-			return value;
+function proxyStealthSession(
+	session: StealthSession,
+	onResponse: (response: Awaited<ReturnType<StealthClient["fetch"]>>) => void,
+): StealthSession {
+	return {
+		fetch: async (...args: Parameters<StealthSession["fetch"]>) => {
+			const response = await session.fetch(...args);
+			onResponse(response);
+			return response;
 		},
-	}) as ReturnType<TlsClient["createSession"]>;
+		close: () => session.close(),
+	};
 }
 
-function normalizeCapturedTlsResponse(
-	response: Awaited<ReturnType<TlsClient["fetch"]>>,
+function normalizeCapturedStealthResponse(
+	response: Awaited<ReturnType<StealthClient["fetch"]>>,
 ) {
 	try {
 		return JSON.parse(response.body);