@apifuse/connector-sdk 2.0.0-beta.1

package/bin/apifuse-record.ts

@@ -0,0 +1,446 @@
+#!/usr/bin/env bun
+// @ts-nocheck
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { basename, dirname, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+	type ConnectorContext,
+	type ConnectorDefinition,
+	createHttpClient,
+	createSessionStore,
+	createStateContext,
+	createTlsClient,
+	executeOperation,
+	type HttpClient,
+	type TlsClient,
+} from "../src";
+
+type CliArgs = {
+	append: boolean;
+	connectorPath?: string;
+	operation?: string;
+	params: string;
+	sanitize: boolean;
+};
+
+type ConnectorRuntime = ConnectorDefinition;
+
+type MutableRecord = Record<string, unknown>;
+
+async function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const location = resolveConnectorLocation(args.connectorPath);
+	const connector = await loadConnector(location.rootDir);
+	const operationName = resolveOperationName(connector, args.operation);
+	const operation = connector.operations[operationName];
+	const parsedParams = parseParams(operation, args.params);
+
+	const capture = createCaptureContext(
+		resolveOperationBaseUrl(connector, operationName),
+	);
+
+	console.log(
+		`[apifuse record] Calling ${operationName} on ${connector.id}...`,
+	);
+
+	const result = await executeOperation(
+		connector,
+		operationName,
+		capture.ctx,
+		parsedParams,
+	);
+	const captured = capture.getCapturedRaw();
+
+	if (captured === undefined) {
+		throw new Error(
+			`No upstream response was captured for ${connector.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,
+	);
+
+	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;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+	let connectorPath: string | undefined;
+	let operation: string | undefined;
+	let params = "{}";
+	let sanitize = true;
+	let append = false;
+
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+
+		if (arg === "--operation" || arg === "-o") {
+			const value = argv[index + 1];
+			if (!value) {
+				throw new Error("Missing value for --operation.");
+			}
+
+			operation = value;
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith("--operation=")) {
+			operation = arg.slice("--operation=".length);
+			continue;
+		}
+
+		if (arg === "--params" || arg === "-p") {
+			const value = argv[index + 1];
+			if (!value) {
+				throw new Error("Missing value for --params.");
+			}
+
+			params = value;
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith("--params=")) {
+			params = arg.slice("--params=".length);
+			continue;
+		}
+
+		if (arg === "--sanitize") {
+			sanitize = true;
+			continue;
+		}
+
+		if (arg === "--no-sanitize") {
+			sanitize = false;
+			continue;
+		}
+
+		if (arg === "--append") {
+			append = true;
+			continue;
+		}
+
+		if (arg.startsWith("-")) {
+			throw new Error(`Unknown option: ${arg}`);
+		}
+
+		if (!connectorPath) {
+			connectorPath = arg;
+			continue;
+		}
+
+		throw new Error(`Unexpected argument: ${arg}`);
+	}
+
+	return { append, connectorPath, operation, params, sanitize };
+}
+
+function resolveConnectorLocation(inputPath?: string) {
+	const originalInput = inputPath ?? process.cwd();
+	const resolvedInput = resolve(process.cwd(), originalInput);
+
+	if (!existsSync(resolvedInput)) {
+		throw new Error(`Connector path not found: ${originalInput}`);
+	}
+
+	const initialDirectory = statSync(resolvedInput).isDirectory()
+		? resolvedInput
+		: dirname(resolvedInput);
+	const connectorRoot = findConnectorRoot(initialDirectory);
+
+	if (!connectorRoot) {
+		throw new Error(`Could not find connector root under: ${originalInput}`);
+	}
+
+	return {
+		inputPath: originalInput,
+		label: basename(connectorRoot),
+		rootDir: connectorRoot,
+	};
+}
+
+function findConnectorRoot(startDirectory: string): string | undefined {
+	let currentDirectory = startDirectory;
+
+	while (true) {
+		if (looksLikeConnectorRoot(currentDirectory)) {
+			return currentDirectory;
+		}
+
+		const parentDirectory = dirname(currentDirectory);
+		if (parentDirectory === currentDirectory) {
+			return undefined;
+		}
+
+		currentDirectory = parentDirectory;
+	}
+}
+
+function looksLikeConnectorRoot(directory: string): boolean {
+	return (
+		existsSync(resolve(directory, "index.ts")) &&
+		existsSync(resolve(directory, "manifest.json"))
+	);
+}
+
+async function loadConnector(rootDir: string): Promise<ConnectorRuntime> {
+	const entryPath = resolve(rootDir, "index.ts");
+	const module = (await import(pathToFileURL(entryPath).href)) as {
+		default?: ConnectorRuntime;
+	};
+
+	if (!module.default) {
+		throw new Error(`Connector must default-export a definition: ${entryPath}`);
+	}
+
+	return module.default;
+}
+
+function resolveOperationName(
+	connector: ConnectorRuntime,
+	operationName?: string,
+): string {
+	if (operationName) {
+		if (!(operationName in connector.operations)) {
+			throw new Error(
+				`Unknown operation "${operationName}" for connector "${connector.id}".`,
+			);
+		}
+
+		return operationName;
+	}
+
+	const [firstOperation] = Object.keys(connector.operations);
+	if (!firstOperation) {
+		throw new Error(`Connector "${connector.id}" has no operations.`);
+	}
+
+	return firstOperation;
+}
+
+function parseParams(
+	operation: ConnectorRuntime["operations"][string],
+	value: string,
+): unknown {
+	let parsed: unknown;
+
+	try {
+		parsed = JSON.parse(value);
+	} catch (error) {
+		throw new Error(
+			`Failed to parse --params JSON: ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+
+	return operation.input ? operation.input.parse(parsed) : parsed;
+}
+
+function resolveOperationBaseUrl(
+	connector: ConnectorRuntime,
+	operationName: string,
+): string {
+	const baseUrl = connector.operations[operationName]?.upstream?.baseUrl;
+	if (!baseUrl) {
+		throw new Error(
+			`Operation "${operationName}" for connector "${connector.id}" must define upstream.baseUrl.`,
+		);
+	}
+
+	return baseUrl;
+}
+
+function createCaptureContext(baseUrl: string) {
+	let capturedRaw: unknown;
+
+	const http = proxyHttpClient(createHttpClient(baseUrl), (response) => {
+		capturedRaw = response.data;
+	});
+	const tls = proxyTlsClient(createTlsClient(baseUrl), (response) => {
+		capturedRaw = normalizeCapturedTlsResponse(response);
+	});
+
+	const ctx: ConnectorContext = {
+		http,
+		tls,
+		browser: {
+			engine: "playwright-stealth",
+			newPage: async () => {
+				throw new Error("Browser client is not available in apifuse record.");
+			},
+		},
+		session: createSessionStore(),
+		state: createStateContext(),
+		trace: {
+			span: async (_name, fn) => fn(),
+		},
+		auth: {
+			requestField: async () => {
+				throw new Error("Auth prompts are not available in apifuse record.");
+			},
+		},
+	};
+
+	return {
+		ctx,
+		getCapturedRaw: () => capturedRaw,
+	};
+}
+
+function proxyHttpClient(
+	client: HttpClient,
+	onResponse: (response: Awaited<ReturnType<HttpClient["get"]>>) => void,
+): HttpClient {
+	return new Proxy(client, {
+		get(target, prop, receiver) {
+			const value = Reflect.get(target, prop, receiver);
+
+			if (typeof value !== "function") {
+				return value;
+			}
+
+			return async (...args: unknown[]) => {
+				const response = await value.apply(target, args);
+				onResponse(response);
+				return response;
+			};
+		},
+	}) 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;
+				};
+			}
+
+			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;
+		},
+	}) as TlsClient;
+}
+
+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;
+		},
+	}) as ReturnType<TlsClient["createSession"]>;
+}
+
+function normalizeCapturedTlsResponse(
+	response: Awaited<ReturnType<TlsClient["fetch"]>>,
+) {
+	try {
+		return JSON.parse(response.body);
+	} catch {
+		return response.body;
+	}
+}
+
+function sanitizeFixture(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map((item) => sanitizeFixture(item));
+	}
+
+	if (!value || typeof value !== "object") {
+		return value;
+	}
+
+	const entries = Object.entries(value as MutableRecord).map(
+		([key, entryValue]) => {
+			if (isSensitiveKey(key)) {
+				return [key, "[REDACTED]"] as const;
+			}
+
+			return [key, sanitizeFixture(entryValue)] as const;
+		},
+	);
+
+	return Object.fromEntries(entries);
+}
+
+function isSensitiveKey(key: string): boolean {
+	return /authorization|token|api[-_]?key/i.test(key);
+}
+
+async function prepareFixturePayload(
+	fixturePath: string,
+	payload: unknown,
+	append: boolean,
+): Promise<unknown> {
+	if (!append || !existsSync(fixturePath)) {
+		return payload;
+	}
+
+	try {
+		const existing = JSON.parse(readFileSync(fixturePath, "utf8")) as unknown;
+		if (Array.isArray(existing)) {
+			return [...existing, payload];
+		}
+	} catch {
+		// Fall through to overwrite with the new payload.
+	}
+
+	return payload;
+}
+
+function formatBytes(bytes: number): string {
+	if (bytes < 1024) {
+		return `${bytes} B`;
+	}
+
+	return `${(bytes / 1024).toFixed(1)} KB`;
+}
+
+await main();