@apifuse/connector-sdk 2.0.0-beta.1

package/bin/apifuse-init.ts

@@ -0,0 +1,390 @@
+#!/usr/bin/env bun
+
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+
+import { cancel, intro, isCancel, outro, select, text } from "@clack/prompts";
+
+const CONNECTOR_NAME_REGEX = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const CATEGORIES = [
+	"developer-tools",
+	"finance",
+	"commerce",
+	"productivity",
+	"marketing",
+	"data",
+	"communication",
+	"other",
+] as const;
+
+type AuthMode = "none" | "credentials" | "api-key" | "oauth2";
+type RuntimeMode = "standard" | "browser";
+type Category = (typeof CATEGORIES)[number];
+
+type Answers = {
+	name: string;
+	displayName: string;
+	category: Category;
+	authMode: AuthMode;
+	runtime: RuntimeMode;
+};
+
+const HELP_TEXT = `Usage: apifuse init <connector-name>
+Example: apifuse init my-new-api`;
+
+export async function main() {
+	const args = normalizeArgs(process.argv.slice(2));
+
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(HELP_TEXT);
+		return;
+	}
+
+	intro("Create a new ApiFuse connector");
+
+	const initialName = args[0];
+	const answers = await promptForAnswers(initialName);
+	const workspaceRoot = findWorkspaceRoot();
+	const connectorRoot = resolve(workspaceRoot, "connectors", answers.name);
+
+	if (existsSync(connectorRoot)) {
+		throw new Error(
+			`Connector directory already exists: connectors/${answers.name}`,
+		);
+	}
+
+	await mkdir(join(connectorRoot, "__tests__"), { recursive: true });
+
+	await Promise.all([
+		writeFile(join(connectorRoot, "index.ts"), renderIndexTs(answers)),
+		writeFile(join(connectorRoot, "package.json"), renderPackageJson(answers)),
+		writeFile(join(connectorRoot, "Dockerfile"), renderDockerfile()),
+		writeFile(
+			join(connectorRoot, "manifest.json"),
+			renderManifestJson(answers),
+		),
+		writeFile(join(connectorRoot, "dev.ts"), renderDevTs()),
+		writeFile(join(connectorRoot, "tsconfig.json"), renderTsconfig()),
+		writeFile(
+			join(connectorRoot, "__tests__", "index.test.ts"),
+			renderTestTs(answers),
+		),
+	]);
+
+	outro(`Created connectors/${answers.name}`);
+	console.log(`
+Created:
+  connectors/${answers.name}/
+  ├── index.ts
+  ├── package.json
+  ├── Dockerfile
+  ├── manifest.json
+  ├── dev.ts
+  ├── tsconfig.json
+  └── __tests__/
+      └── index.test.ts
+`);
+}
+
+function normalizeArgs(argv: string[]): string[] {
+	return argv[0] === "init" ? argv.slice(1) : argv;
+}
+
+async function promptForAnswers(initialName?: string): Promise<Answers> {
+	const name = await promptValue(
+		text({
+			message: "Connector name",
+			initialValue: initialName,
+			placeholder: "my-new-api",
+			validate(value) {
+				const normalized = value?.trim() ?? "";
+				if (!normalized) {
+					return "Connector name is required.";
+				}
+
+				if (!CONNECTOR_NAME_REGEX.test(normalized)) {
+					return "Use kebab-case, e.g. my-new-api.";
+				}
+			},
+		}),
+	);
+
+	const displayName = await promptValue(
+		text({
+			message: "Display name",
+			initialValue: toDisplayName(name),
+			validate(value) {
+				if (!(value?.trim() ?? "")) {
+					return "Display name is required.";
+				}
+			},
+		}),
+	);
+
+	const category = await promptValue<Category>(
+		select({
+			message: "Category",
+			options: CATEGORIES.map((value) => ({ label: value, value })),
+		}),
+	);
+
+	const authMode = await promptValue<AuthMode>(
+		select({
+			message: "Auth mode",
+			options: [
+				{ label: "none", value: "none" },
+				{ label: "credentials", value: "credentials" },
+				{ label: "api-key", value: "api-key" },
+				{ label: "oauth2", value: "oauth2" },
+			],
+		}),
+	);
+
+	const runtime = await promptValue<RuntimeMode>(
+		select({
+			message: "Runtime",
+			options: [
+				{ label: "standard", value: "standard" },
+				{ label: "browser", value: "browser" },
+			],
+		}),
+	);
+
+	return {
+		authMode,
+		category,
+		displayName: displayName.trim(),
+		name: name.trim(),
+		runtime,
+	};
+}
+
+async function promptValue<T>(prompt: Promise<T | symbol>): Promise<T> {
+	const result = await prompt;
+
+	if (isCancel(result)) {
+		cancel("Operation cancelled.");
+		process.exit(0);
+	}
+
+	return result;
+}
+
+function findWorkspaceRoot(): string {
+	let currentDirectory = process.cwd();
+
+	while (true) {
+		if (existsSync(resolve(currentDirectory, "connectors"))) {
+			return currentDirectory;
+		}
+
+		const parentDirectory = dirname(currentDirectory);
+		if (parentDirectory === currentDirectory) {
+			return process.cwd();
+		}
+
+		currentDirectory = parentDirectory;
+	}
+}
+
+function toDisplayName(name: string): string {
+	return name
+		.split("-")
+		.filter(Boolean)
+		.map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`)
+		.join(" ");
+}
+
+function renderIndexTs(answers: Answers): string {
+	const authBlock = renderAuthBlock(answers.authMode);
+	const browserBlock =
+		answers.runtime === "browser"
+			? '\n  browser: {\n    engine: "nodriver",\n  },'
+			: "";
+
+	return `import { defineConnector, z } from "@apifuse/connector-sdk";
+
+const InputSchema = z.object({
+  value: z.string().default("hello").describe("Sample input value"),
+});
+
+const OutputSchema = z.object({
+  ok: z.boolean(),
+  message: z.string(),
+});
+
+export default defineConnector({
+  id: "${answers.name}",
+  version: "1.0.0",
+  runtime: "${answers.runtime}",${browserBlock}
+  auth: ${authBlock},
+  meta: {
+    displayName: "${escapeTemplate(answers.displayName)}",
+    description: "${escapeTemplate(answers.displayName)} connector",
+    category: "${answers.category}",
+    tags: ["${answers.name}", "example"],
+  },
+  operations: {
+    ping: {
+      description: "Sample operation for local connector development",
+      input: InputSchema,
+      output: OutputSchema,
+      handler: async (_ctx, input) => {
+        return {
+          ok: true,
+          message: "${escapeTemplate(answers.displayName)} received: " + input.value,
+        };
+      },
+      fixtures: {
+        request: { value: "hello" },
+        response: { ok: true, message: "${escapeTemplate(answers.displayName)} received: hello" },
+      },
+    },
+  },
+});
+`;
+}
+
+function renderAuthBlock(authMode: AuthMode): string {
+	switch (authMode) {
+		case "none":
+			return '{ mode: "none" }';
+		case "credentials":
+			return `{
+    mode: "credentials",
+    fields: [
+      { name: "username", label: "Username", type: "text", required: true },
+      { name: "password", label: "Password", type: "password", required: true },
+    ],
+  }`;
+		case "api-key":
+			return `{
+    mode: "api-key",
+    fields: [
+      { name: "apiKey", label: "API Key", type: "password", required: true },
+    ],
+  }`;
+		case "oauth2":
+			return `{
+    mode: "oauth2",
+    fields: [
+      { name: "accessToken", label: "Access Token", type: "password", required: true },
+    ],
+  }`;
+	}
+}
+
+function renderPackageJson(answers: Answers): string {
+	return `${JSON.stringify(
+		{
+			name: `@apifuse/connector-${answers.name}`,
+			version: "1.0.0",
+			private: true,
+			type: "module",
+			main: "./index.ts",
+			scripts: {
+				dev: "bun --hot dev.ts",
+				start: "bun dev.ts",
+				test: "bun test",
+			},
+			dependencies: {
+				"@apifuse/connector-sdk": "workspace:*",
+			},
+			devDependencies: {
+				"@types/bun": "latest",
+			},
+		},
+		null,
+		2,
+	)}
+`;
+}
+
+function renderDockerfile(): string {
+	return `FROM oven/bun:1.2-alpine
+WORKDIR /connector
+COPY package.json bun.lockb* ./
+RUN bun install --frozen-lockfile || bun install
+COPY . .
+EXPOSE 3900
+CMD ["bun", "run", "start"]
+`;
+}
+
+function renderManifestJson(answers: Answers): string {
+	return `${JSON.stringify(
+		{
+			auth: answers.authMode,
+			category: answers.category,
+			displayName: answers.displayName,
+			id: answers.name,
+			language: "typescript",
+			runtime: answers.runtime,
+			sdkVersion: 2,
+			version: "1.0.0",
+		},
+		null,
+		2,
+	)}
+`;
+}
+
+function renderDevTs(): string {
+	return `import { startDevServer } from "@apifuse/connector-sdk";
+
+import connector from "./index";
+
+startDevServer(connector, { port: Number(process.env.PORT) || 3900 });
+`;
+}
+
+function renderTsconfig(): string {
+	return `${JSON.stringify(
+		{
+			compilerOptions: {
+				target: "ES2022",
+				module: "ES2022",
+				moduleResolution: "bundler",
+				strict: true,
+				noEmit: true,
+				skipLibCheck: true,
+				resolveJsonModule: true,
+			},
+			include: ["**/*.ts"],
+			exclude: ["node_modules"],
+		},
+		null,
+		2,
+	)}
+`;
+}
+
+function renderTestTs(answers: Answers): string {
+	return `import { describe, expect, it } from "bun:test";
+import { runStandardTests } from "@apifuse/connector-sdk/testing";
+
+import connector from "../index";
+import manifest from "../manifest.json";
+
+runStandardTests(connector, undefined, { ...manifest, sdkVersion: 1 });
+
+describe("${answers.name}", () => {
+  it("keeps manifest metadata on sdk v2", () => {
+    expect(manifest.sdkVersion).toBe(2);
+    expect(manifest.auth).toBe("${answers.authMode}");
+  });
+});
+`;
+}
+
+function escapeTemplate(value: string): string {
+	return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+}
+
+if (import.meta.main) {
+	await main().catch((error: unknown) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}