@apifuse/connector-sdk 2.0.0-beta.1

package/README.md

@@ -0,0 +1,44 @@
+# @apifuse/connector-sdk
+
+ApiFuse Connector SDK — Build private API automation connectors.
+
+## Installation
+
+```bash
+bun add @apifuse/connector-sdk
+```
+
+## Quick Start
+
+```typescript
+import { defineConnector } from '@apifuse/connector-sdk'
+import { z } from 'zod'
+
+export default defineConnector({
+  meta: {
+    id: 'my-api-prices',
+    displayName: 'My API Prices',
+    category: 'finance',
+    version: '1.0.0',
+    runtime: 'standard',
+    upstream: { baseUrl: 'https://api.example.com' },
+  },
+  input: z.object({ id: z.string() }),
+  output: z.object({ price: z.number() }),
+  operations: {
+    prices: {
+      execute: async (ctx, input) => {
+        const res = await ctx.http.get('/prices', { params: { id: input.id } })
+        return res.data as { price: number }
+      },
+    },
+  },
+})
+```
+
+## Testing
+
+```typescript
+import { runStandardTests } from '@apifuse/connector-sdk/testing'
+runStandardTests(myConnector)
+```

package/bin/apifuse-check.ts

@@ -0,0 +1,408 @@
+#!/usr/bin/env bun
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { z } from "zod";
+
+import type { ConnectorDefinition } from "../src";
+
+const HELP_TEXT = `Usage: apifuse check [path]
+Example: apifuse check connectors/upbit-crypto
+Default: apifuse check .`;
+
+const manifestSchema = z.object({
+	auth: z.enum(["none", "credentials", "api-key", "oauth2"]),
+	category: z.string().min(1),
+	displayName: z.string().min(1),
+	id: z.string().min(1),
+	language: z.literal("typescript"),
+	runtime: z.enum(["standard", "browser"]),
+	sdkVersion: z.number().int().positive(),
+	version: z.string().min(1),
+});
+
+type CheckResult = {
+	message: string;
+	passed: boolean;
+	details?: string[];
+};
+
+type SafeParseResult =
+	| { success: true; data: unknown }
+	| { success: false; error: z.ZodError };
+
+export async function main() {
+	const args = normalizeArgs(process.argv.slice(2));
+
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(HELP_TEXT);
+		return;
+	}
+
+	const inputPath = args[0] ?? ".";
+	const connectorRoot = resolveConnectorRoot(inputPath);
+	const results = await runChecks(connectorRoot);
+	const failed = results.filter((result) => !result.passed);
+
+	console.log(`Checking connector: ${connectorRoot}\n`);
+
+	for (const result of results) {
+		const prefix = result.passed ? "✓" : "✗";
+		console.log(`${prefix} ${result.message}`);
+
+		for (const detail of result.details ?? []) {
+			console.log(`  - ${detail}`);
+		}
+	}
+
+	if (failed.length > 0) {
+		process.exit(1);
+	}
+
+	console.log("\nAll checks passed.");
+}
+
+function normalizeArgs(argv: string[]): string[] {
+	return argv[0] === "check" ? argv.slice(1) : argv;
+}
+
+function resolveConnectorRoot(inputPath: string): string {
+	const resolvedInput = resolveFromParents(inputPath);
+
+	if (!existsSync(resolvedInput)) {
+		throw new Error(`Connector path not found: ${inputPath}`);
+	}
+
+	const startDirectory = statSync(resolvedInput).isDirectory()
+		? resolvedInput
+		: dirname(resolvedInput);
+
+	for (let currentDirectory = startDirectory; ; ) {
+		if (existsSync(resolve(currentDirectory, "index.ts"))) {
+			return currentDirectory;
+		}
+
+		const parentDirectory = dirname(currentDirectory);
+		if (parentDirectory === currentDirectory) {
+			break;
+		}
+
+		currentDirectory = parentDirectory;
+	}
+
+	throw new Error(`Could not find connector root for: ${inputPath}`);
+}
+
+function resolveFromParents(inputPath: string): string {
+	let currentDirectory = process.cwd();
+
+	while (true) {
+		const candidate = resolve(currentDirectory, inputPath);
+		if (existsSync(candidate)) {
+			return candidate;
+		}
+
+		const parentDirectory = dirname(currentDirectory);
+		if (parentDirectory === currentDirectory) {
+			return resolve(process.cwd(), inputPath);
+		}
+
+		currentDirectory = parentDirectory;
+	}
+}
+
+async function runChecks(connectorRoot: string): Promise<CheckResult[]> {
+	const indexPath = resolve(connectorRoot, "index.ts");
+	const manifestPath = resolve(connectorRoot, "manifest.json");
+	const dockerfilePath = resolve(connectorRoot, "Dockerfile");
+	const packageJsonPath = resolve(connectorRoot, "package.json");
+
+	const connectorModule = existsSync(indexPath)
+		? await import(pathToFileURL(indexPath).href)
+		: undefined;
+	const connector = assertConnectorDefinition(connectorModule?.default);
+
+	return [
+		checkIndex(indexPath, connector),
+		checkOperations(connector),
+		checkFixtures(connector),
+		checkSchemas(connector),
+		checkManifest(manifestPath, connector),
+		checkDockerfile(dockerfilePath),
+		checkPackageJson(packageJsonPath),
+	];
+}
+
+function checkIndex(
+	indexPath: string,
+	connector: ConnectorDefinition | undefined,
+): CheckResult {
+	if (!existsSync(indexPath)) {
+		return {
+			message: "index.ts exists and exports default defineConnector",
+			passed: false,
+		};
+	}
+
+	if (!connector) {
+		return {
+			message: "index.ts exists and exports default defineConnector",
+			passed: false,
+		};
+	}
+
+	return {
+		message: "index.ts exists and exports default defineConnector",
+		passed: true,
+		details: [`connector id: ${connector.id}`],
+	};
+}
+
+function checkOperations(
+	connector: ConnectorDefinition | undefined,
+): CheckResult {
+	if (!connector) {
+		return {
+			message: "All operations have handler, input, output",
+			passed: false,
+		};
+	}
+
+	const failures: string[] = [];
+
+	for (const [operationId, operation] of Object.entries(connector.operations)) {
+		if (typeof operation.handler !== "function") {
+			failures.push(`${operationId}: missing handler`);
+		}
+
+		if (!hasSafeParse(operation.input)) {
+			failures.push(`${operationId}: missing input schema`);
+		}
+
+		if (!hasSafeParse(operation.output)) {
+			failures.push(`${operationId}: missing output schema`);
+		}
+	}
+
+	return {
+		message: "All operations have handler, input, output",
+		passed: failures.length === 0,
+		details: failures.length > 0 ? failures : Object.keys(connector.operations),
+	};
+}
+
+function checkFixtures(
+	connector: ConnectorDefinition | undefined,
+): CheckResult {
+	if (!connector) {
+		return { message: "All operations have fixtures", passed: false };
+	}
+
+	const failures: string[] = [];
+
+	for (const [operationId, operation] of Object.entries(connector.operations)) {
+		if (!operation.fixtures) {
+			failures.push(`${operationId}: missing fixtures`);
+			continue;
+		}
+
+		if (operation.fixtures.request === undefined) {
+			failures.push(`${operationId}: missing fixtures.request`);
+		}
+
+		if (operation.fixtures.response === undefined) {
+			failures.push(`${operationId}: missing fixtures.response`);
+		}
+	}
+
+	return {
+		message: "All operations have fixtures",
+		passed: failures.length === 0,
+		details: failures,
+	};
+}
+
+function checkSchemas(connector: ConnectorDefinition | undefined): CheckResult {
+	if (!connector) {
+		return {
+			message: "Zod schemas parse fixtures without error",
+			passed: false,
+		};
+	}
+
+	const failures: string[] = [];
+
+	for (const [operationId, operation] of Object.entries(connector.operations)) {
+		if (!operation.fixtures) {
+			continue;
+		}
+
+		const requestResult = parseFixture(
+			operation.input,
+			operation.fixtures.request,
+		);
+		if (!requestResult.success) {
+			failures.push(
+				`${operationId}: request fixture invalid (${requestResult.error.issues.map((issue: z.ZodIssue) => issue.message).join(", ")})`,
+			);
+		}
+
+		const responseResult = parseFixture(
+			operation.output,
+			operation.fixtures.response,
+		);
+		if (!responseResult.success) {
+			failures.push(
+				`${operationId}: response fixture invalid (${responseResult.error.issues.map((issue: z.ZodIssue) => issue.message).join(", ")})`,
+			);
+		}
+	}
+
+	return {
+		message: "Zod schemas parse fixtures without error",
+		passed: failures.length === 0,
+		details: failures,
+	};
+}
+
+function checkManifest(
+	manifestPath: string,
+	connector: ConnectorDefinition | undefined,
+): CheckResult {
+	if (!existsSync(manifestPath)) {
+		return { message: "manifest.json exists and is valid", passed: false };
+	}
+
+	try {
+		const manifest = manifestSchema.parse(
+			JSON.parse(readFileSync(manifestPath, "utf-8")) as unknown,
+		);
+		const details: string[] = [];
+
+		if (connector) {
+			if (manifest.id !== connector.id) {
+				details.push(
+					`id mismatch: manifest=${manifest.id} connector=${connector.id}`,
+				);
+			}
+
+			if (manifest.displayName !== connector.meta.displayName) {
+				details.push(
+					`displayName mismatch: manifest=${manifest.displayName} connector=${connector.meta.displayName}`,
+				);
+			}
+
+			if (manifest.category !== connector.meta.category) {
+				details.push(
+					`category mismatch: manifest=${manifest.category} connector=${connector.meta.category}`,
+				);
+			}
+
+			if (manifest.runtime !== connector.runtime) {
+				details.push(
+					`runtime mismatch: manifest=${manifest.runtime} connector=${connector.runtime}`,
+				);
+			}
+		}
+
+		return {
+			message: "manifest.json exists and is valid",
+			passed: details.length === 0,
+			details,
+		};
+	} catch (error) {
+		return {
+			message: "manifest.json exists and is valid",
+			passed: false,
+			details: [error instanceof Error ? error.message : String(error)],
+		};
+	}
+}
+
+function checkDockerfile(dockerfilePath: string): CheckResult {
+	return {
+		message: "Dockerfile exists",
+		passed: existsSync(dockerfilePath),
+	};
+}
+
+function checkPackageJson(packageJsonPath: string): CheckResult {
+	if (!existsSync(packageJsonPath)) {
+		return {
+			message: "package.json exists with @apifuse/connector-sdk dependency",
+			passed: false,
+		};
+	}
+
+	try {
+		const packageJson = z
+			.object({
+				dependencies: z.record(z.string(), z.string()).optional(),
+			})
+			.parse(JSON.parse(readFileSync(packageJsonPath, "utf-8")) as unknown);
+
+		const dependency = packageJson.dependencies?.["@apifuse/connector-sdk"];
+
+		return {
+			message: "package.json exists with @apifuse/connector-sdk dependency",
+			passed: typeof dependency === "string" && dependency.length > 0,
+			details:
+				typeof dependency === "string"
+					? [`@apifuse/connector-sdk: ${dependency}`]
+					: ["Missing dependencies.@apifuse/connector-sdk"],
+		};
+	} catch (error) {
+		return {
+			message: "package.json exists with @apifuse/connector-sdk dependency",
+			passed: false,
+			details: [error instanceof Error ? error.message : String(error)],
+		};
+	}
+}
+
+function assertConnectorDefinition(
+	value: unknown,
+): ConnectorDefinition | undefined {
+	return isConnectorDefinition(value) ? value : undefined;
+}
+
+function isConnectorDefinition(value: unknown): value is ConnectorDefinition {
+	if (
+		!isRecord(value) ||
+		!isRecord(value.meta) ||
+		!isRecord(value.operations)
+	) {
+		return false;
+	}
+
+	return (
+		typeof value.id === "string" &&
+		typeof value.version === "string" &&
+		(value.runtime === "standard" || value.runtime === "browser") &&
+		typeof value.meta.displayName === "string" &&
+		typeof value.meta.category === "string"
+	);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function hasSafeParse(value: unknown): value is {
+	safeParse: (input: unknown) => SafeParseResult;
+} {
+	return isRecord(value) && typeof value.safeParse === "function";
+}
+
+function parseFixture(schema: z.ZodType, fixture: unknown): SafeParseResult {
+	return schema.safeParse(fixture);
+}
+
+if (import.meta.main) {
+	await main().catch((error: unknown) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}

package/bin/apifuse-dev.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env bun
+
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import * as readline from "node:readline";
+
+import type { ConnectorDefinition } from "../src";
+import {
+	ConnectorError,
+	createBrowserClient,
+	createHttpClient,
+	createStateContext,
+	createTlsClient,
+} from "../src";
+import type { AuthManager } from "../src/runtime/auth";
+import { createTraceContext } from "../src/runtime/trace";
+import type { ConnectorContext, SessionStore } from "../src/types";
+
+const HELP_TEXT = `Usage: apifuse dev [path]
+Example: apifuse dev connectors/upbit-crypto
+Default: apifuse dev .`;
+
+export async function main() {
+	const args = normalizeArgs(process.argv.slice(2));
+
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(HELP_TEXT);
+		return;
+	}
+
+	const connectorPath = resolveConnectorPath(args[0] ?? ".");
+	const connectorModule = await import(resolve(connectorPath, "index.ts"));
+	const connector = assertConnectorDefinition(
+		connectorModule.default,
+		connectorPath,
+	);
+
+	const { startDevServer } = await import("../src/dev");
+	const port = Number(process.env.PORT) || 3900;
+
+	startDevServer(connector, { port });
+
+	console.log("\nEndpoints:");
+	console.log(`  GET  http://localhost:${port}/health`);
+
+	for (const operationId of Object.keys(connector.operations)) {
+		console.log(`  POST http://localhost:${port}/execute/${operationId}`);
+		console.log(`  GET  http://localhost:${port}/schema/${operationId}`);
+	}
+
+	console.log("\nHot reload:");
+	console.log(
+		`  bun --hot ${resolveImportPath("apifuse-dev.ts")} ${args[0] ?? "."}`,
+	);
+}
+
+export function createConnectorContext(
+	connector: ConnectorDefinition,
+	session: SessionStore,
+	authManager: AuthManager,
+): { ctx: ConnectorContext } {
+	const ctx: ConnectorContext = {
+		auth: authManager.createAuthContext(),
+		browser:
+			connector.runtime === "browser"
+				? createBrowserClient({
+						engine: connector.browser?.engine ?? "playwright-stealth",
+					})
+				: createUnsupportedBrowserStub(),
+		http: createHttpClient(),
+		session,
+		state: createStateContext("dev-secret"),
+		trace: createTraceContext(),
+		tls: createTlsClient("http://localhost"),
+	};
+
+	return { ctx };
+}
+
+export async function runExchangeWithDeferredFieldPrompting(
+	authManager: AuthManager,
+	ctx: ConnectorContext,
+	credentials: Record<string, string>,
+	options: { pollIntervalMs?: number } = {},
+): Promise<void> {
+	const promptedFields = new Set<string>();
+	const pollIntervalMs = options.pollIntervalMs ?? 100;
+	let isSettled = false;
+
+	const exchangePromise = authManager.exchange(ctx, credentials).finally(() => {
+		isSettled = true;
+	});
+
+	while (!isSettled) {
+		for (const fieldName of authManager.getPendingFields()) {
+			if (promptedFields.has(fieldName)) {
+				continue;
+			}
+
+			promptedFields.add(fieldName);
+			const value = await promptForField(fieldName);
+			authManager.resolveField(fieldName, value.trim());
+		}
+
+		if (!isSettled) {
+			await Bun.sleep(pollIntervalMs);
+		}
+	}
+
+	await exchangePromise;
+}
+
+function normalizeArgs(argv: string[]): string[] {
+	return argv[0] === "dev" ? argv.slice(1) : argv;
+}
+
+function resolveConnectorPath(inputPath: string): string {
+	const resolvedInput = resolveFromParents(inputPath);
+	const entryPath = resolve(resolvedInput, "index.ts");
+
+	if (!existsSync(entryPath)) {
+		throw new Error(`Could not find index.ts in connector path: ${inputPath}`);
+	}
+
+	return resolvedInput;
+}
+
+function resolveFromParents(inputPath: string): string {
+	let currentDirectory = process.cwd();
+
+	while (true) {
+		const candidate = resolve(currentDirectory, inputPath);
+		if (existsSync(candidate)) {
+			return candidate;
+		}
+
+		const parentDirectory = dirname(currentDirectory);
+		if (parentDirectory === currentDirectory) {
+			return resolve(process.cwd(), inputPath);
+		}
+
+		currentDirectory = parentDirectory;
+	}
+}
+
+function resolveImportPath(fileName: string): string {
+	return resolve(process.cwd(), "bin", fileName);
+}
+
+function createUnsupportedBrowserStub(): ConnectorContext["browser"] {
+	return {
+		engine: "playwright-stealth",
+		async newPage() {
+			throw new ConnectorError(
+				"Browser runtime is not enabled for this connector",
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+					fix: 'Set connector runtime to "browser" to use ctx.browser',
+				},
+			);
+		},
+	};
+}
+
+async function promptForField(fieldName: string): Promise<string> {
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	});
+
+	try {
+		return await new Promise<string>((resolvePrompt) => {
+			rl.question(`\n[apifuse dev] Enter ${fieldName}: `, (answer) => {
+				resolvePrompt(answer);
+			});
+		});
+	} finally {
+		rl.close();
+	}
+}
+
+function assertConnectorDefinition(
+	value: unknown,
+	connectorPath: string,
+): ConnectorDefinition {
+	if (!isConnectorDefinition(value)) {
+		throw new Error(
+			`Expected ${resolve(connectorPath, "index.ts")} to export default defineConnector(...)`,
+		);
+	}
+
+	return value;
+}
+
+function isConnectorDefinition(value: unknown): value is ConnectorDefinition {
+	if (
+		!isRecord(value) ||
+		!isRecord(value.meta) ||
+		!isRecord(value.operations)
+	) {
+		return false;
+	}
+
+	return (
+		typeof value.id === "string" &&
+		typeof value.version === "string" &&
+		(value.runtime === "standard" || value.runtime === "browser") &&
+		typeof value.meta.displayName === "string" &&
+		typeof value.meta.category === "string"
+	);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+if (import.meta.main) {
+	await main().catch((error: unknown) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}