@apifuse/provider-sdk 2.1.0-beta.4 → 2.1.0-beta.6

package/bin/apifuse-record.ts

@@ -9,14 +9,19 @@ import { pathToFileURL } from "node:url";
 import {
 	createBypassProviderCache,
 	createHttpClient,
+	createProviderChoiceContext,
 	createStealthClient,
 	createSttClientFromEnv,
 	executeOperation,
 	type HttpClient,
 	type ProviderContext,
 	type ProviderDefinition,
+	ProviderError,
 	type StealthClient,
+	TransportError,
+	ValidationError,
 } from "../src";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state";
 
 type CliArgs = {
 	append: boolean;
@@ -30,56 +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(
-		provider,
-		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}.`,
+			);
+		}
+
+		const rawPayload = args.sanitize ? sanitizeFixture(captured) : captured;
+		const fixturePath = resolve(location.rootDir, "__fixtures__", "raw.json");
+		const nextPayload = await prepareFixturePayload(
+			fixturePath,
+			rawPayload,
+			args.append,
+		);
 
-	void result;
+		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[] {
@@ -107,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;
@@ -158,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);
@@ -285,25 +353,40 @@ function createCaptureContext(provider: ProviderRuntime, baseUrl: string) {
 		},
 	);
 
+	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,
 		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(),
@@ -314,6 +397,13 @@ function createCaptureContext(provider: ProviderRuntime, baseUrl: string) {
 			},
 		},
 		stt: createSttClientFromEnv(provider.stt),
+		choice: createProviderChoiceContext({
+			providerId: provider.id,
+			env,
+			request: { headers: {} },
+			credential,
+			state,
+		}),
 	};
 
 	return {