@apifuse/connector-sdk 2.0.0-beta.1

package/src/__tests__/connectors-yaml.test.ts

@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import {
+	loadConnectorsYaml,
+	parseConnectorsYaml,
+	resolveConnectorConfig,
+} from "../config/connectors-yaml";
+
+const exampleYaml = `
+defaults:
+  container:
+    image: auto
+    memory: 256Mi
+    cpu: 250m
+    timeout: 30s
+    restart-policy: on-failure
+    max-restarts: 3
+  security:
+    read-only-rootfs: true
+    no-new-privileges: true
+
+connectors:
+  coingecko: {}
+  catchtable:
+    container:
+      memory: 1Gi
+      cpu: 1000m
+    replicas: 2
+    security:
+      egress: ['ct-api.catchtable.co.kr']
+      env: ['CATCHTABLE_PROXY_URL']
+  bank-login:
+    runtime: browser
+    container:
+      memory: 2Gi
+    cdp:
+      pool-size: 2..10
+      page-timeout: 120s
+`;
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+	await Promise.all(
+		tempDirs.splice(0).map((dir) => rm(dir, { force: true, recursive: true })),
+	);
+});
+
+describe("connectors.yaml", () => {
+	it("parses the documented example and normalizes pool-size", () => {
+		const parsed = parseConnectorsYaml(exampleYaml);
+
+		expect(parsed.defaults?.container?.memory).toBe("256Mi");
+		expect(parsed.connectors.coingecko).toEqual({});
+		expect(parsed.connectors["bank-login"].cdp?.["pool-size"]).toEqual({
+			min: 2,
+			max: 10,
+		});
+	});
+
+	it("resolves defaults for empty connector config", () => {
+		const parsed = parseConnectorsYaml(exampleYaml);
+		const resolved = resolveConnectorConfig(parsed, "coingecko");
+
+		expect(resolved.runtime).toBe("standard");
+		expect(resolved.replicas).toBe(1);
+		expect(resolved.container).toEqual({
+			image: "auto",
+			memory: "256Mi",
+			cpu: "250m",
+			timeout: "30s",
+			"restart-policy": "on-failure",
+			"max-restarts": 3,
+		});
+		expect(resolved.security).toEqual({
+			"read-only-rootfs": true,
+			"no-new-privileges": true,
+		});
+	});
+
+	it("merges connector overrides with defaults", () => {
+		const parsed = parseConnectorsYaml(exampleYaml);
+		const resolved = resolveConnectorConfig(parsed, "catchtable");
+
+		expect(resolved.replicas).toBe(2);
+		expect(resolved.container.memory).toBe("1Gi");
+		expect(resolved.container.cpu).toBe("1000m");
+		expect(resolved.container.timeout).toBe("30s");
+		expect(resolved.security.egress).toEqual(["ct-api.catchtable.co.kr"]);
+		expect(resolved.security.env).toEqual(["CATCHTABLE_PROXY_URL"]);
+		expect(resolved.security["read-only-rootfs"]).toBe(true);
+	});
+
+	it("applies browser cdp defaults while preserving parsed pool range", () => {
+		const parsed = parseConnectorsYaml(exampleYaml);
+		const resolved = resolveConnectorConfig(parsed, "bank-login");
+
+		expect(resolved.runtime).toBe("browser");
+		expect(resolved.container.memory).toBe("2Gi");
+		expect(resolved.cdp).toEqual({
+			"pool-size": { min: 2, max: 10 },
+			"page-timeout": "120s",
+			"pages-per-instance": 4,
+			"idle-timeout": "5m",
+		});
+	});
+
+	it("loads connectors yaml from disk", async () => {
+		const dir = mkdtempSync(path.join(tmpdir(), "connectors-yaml-"));
+		tempDirs.push(dir);
+		const filePath = path.join(dir, "connectors.yaml");
+
+		await Bun.write(filePath, exampleYaml);
+
+		const loaded = await loadConnectorsYaml(filePath);
+
+		expect(loaded.connectors.catchtable.replicas).toBe(2);
+	});
+
+	it("rejects invalid pool-size ranges", () => {
+		expect(() =>
+			parseConnectorsYaml(`
+connectors:
+  bank-login:
+    runtime: browser
+    cdp:
+      pool-size: 10..2
+`),
+		).toThrow("Invalid connectors.yaml configuration");
+	});
+});

package/src/__tests__/define.test.ts

@@ -0,0 +1,225 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+
+import { defineConnector } from "../define";
+import { ConnectorError, ValidationError } from "../errors";
+import type { ConnectorContext } from "../types";
+
+const InputSchema = z.object({ id: z.string() });
+const OutputSchema = z.object({ name: z.string(), price: z.number() });
+
+const validConfig = {
+	id: "coingecko-prices",
+	version: "1.0.0",
+	runtime: "standard" as const,
+	meta: {
+		displayName: "CoinGecko Prices",
+		description: "Simple finance connector",
+		category: "finance",
+		tags: ["prices"],
+	},
+	operations: {
+		prices: {
+			input: InputSchema,
+			output: OutputSchema,
+			handler: async (_ctx: ConnectorContext, input: unknown) => {
+				const parsed = InputSchema.parse(input);
+
+				return {
+					name: parsed.id,
+					price: 50_000,
+				};
+			},
+			fixtures: {
+				request: { id: "bitcoin" },
+				response: { name: "Bitcoin", price: 50_000 },
+			},
+		},
+	},
+};
+
+describe("defineConnector", () => {
+	it("returns connector with top-level identity fields accessible", () => {
+		const connector = defineConnector(validConfig);
+
+		expect(connector.id).toBe("coingecko-prices");
+		expect(connector.version).toBe("1.0.0");
+		expect(connector.runtime).toBe("standard");
+		expect(connector.meta.displayName).toBe("CoinGecko Prices");
+	});
+
+	it("preserves operation definitions", async () => {
+		const connector = defineConnector(validConfig);
+		await expect(
+			connector.operations.prices.handler?.({} as never, { id: "bitcoin" }),
+		).resolves.toEqual({ name: "bitcoin", price: 50_000 });
+	});
+
+	it("throws ConnectorError for invalid id format - uppercase", () => {
+		expect(() =>
+			defineConnector({
+				...validConfig,
+				id: "CoinGecko",
+			}),
+		).toThrow(ConnectorError);
+	});
+
+	it("throws ConnectorError for invalid id format - single word", () => {
+		expect(() =>
+			defineConnector({ ...validConfig, id: "coingecko" }),
+		).not.toThrow();
+	});
+
+	it("throws ConnectorError for invalid id format - spaces", () => {
+		expect(() =>
+			defineConnector({
+				...validConfig,
+				id: "coin gecko prices",
+			}),
+		).toThrow(ConnectorError);
+	});
+
+	it("throws ConnectorError for invalid id format - underscore", () => {
+		expect(() =>
+			defineConnector({
+				...validConfig,
+				id: "coingecko_prices",
+			}),
+		).toThrow(ConnectorError);
+	});
+
+	it("throws ValidationError when operation fixture.request does not match input schema", () => {
+		const badConfig = {
+			...validConfig,
+			operations: {
+				...validConfig.operations,
+				prices: {
+					...validConfig.operations.prices,
+					fixtures: {
+						request: { wrong_field: "x" } as unknown as z.infer<
+							typeof InputSchema
+						>,
+						response: validConfig.operations.prices.fixtures.response,
+					},
+				},
+			},
+		};
+
+		expect(() => defineConnector(badConfig)).toThrow(ValidationError);
+	});
+
+	it("throws ValidationError when operation fixture.response does not match output schema", () => {
+		const badConfig = {
+			...validConfig,
+			operations: {
+				...validConfig.operations,
+				prices: {
+					...validConfig.operations.prices,
+					fixtures: {
+						request: validConfig.operations.prices.fixtures.request,
+						response: { wrong: true } as unknown as z.infer<
+							typeof OutputSchema
+						>,
+					},
+				},
+			},
+		};
+
+		expect(() => defineConnector(badConfig)).toThrow(ValidationError);
+	});
+
+	it("ValidationError includes zodError for actionable debugging", () => {
+		const badConfig = {
+			...validConfig,
+			operations: {
+				...validConfig.operations,
+				prices: {
+					...validConfig.operations.prices,
+					fixtures: {
+						request: { wrong_field: "x" } as unknown as z.infer<
+							typeof InputSchema
+						>,
+						response: validConfig.operations.prices.fixtures.response,
+					},
+				},
+			},
+		};
+
+		try {
+			defineConnector(badConfig);
+		} catch (error) {
+			expect(error instanceof ValidationError).toBe(true);
+			expect((error as ValidationError).zodError).toBeDefined();
+		}
+	});
+
+	it("ConnectorError has fix hint for invalid id", () => {
+		try {
+			defineConnector({ ...validConfig, id: "BAD_ID" });
+		} catch (error) {
+			expect(error instanceof ConnectorError).toBe(true);
+			expect((error as ConnectorError).fix).toBeDefined();
+		}
+	});
+
+	it("throws ConnectorError when no operations defined", () => {
+		expect(() => defineConnector({ ...validConfig, operations: {} })).toThrow(
+			ConnectorError,
+		);
+	});
+
+	it("works without operation fixtures", () => {
+		const noFixturesConfig = {
+			...validConfig,
+			operations: {
+				...validConfig.operations,
+				prices: {
+					...validConfig.operations.prices,
+					fixtures: undefined,
+				},
+			},
+		};
+
+		const connector = defineConnector(noFixturesConfig);
+
+		expect(connector.id).toBe("coingecko-prices");
+		expect(connector.operations.prices.fixtures).toBeUndefined();
+	});
+
+	it("requires browser config when runtime is browser", () => {
+		expect(() =>
+			defineConnector({
+				...validConfig,
+				runtime: "browser",
+			}),
+		).toThrow(ConnectorError);
+	});
+
+	it("rejects browser config when runtime is not browser", () => {
+		expect(() =>
+			defineConnector({
+				...validConfig,
+				browser: { engine: "nodriver" },
+			}),
+		).toThrow(ConnectorError);
+	});
+
+	it("keeps operation schema inference usable for input parsing", () => {
+		const connector = defineConnector(validConfig);
+		const parsed = connector.operations.prices.input?.safeParse({
+			id: "bitcoin",
+		});
+
+		expect(parsed?.success).toBe(true);
+	});
+
+	it("keeps operation schema inference usable for output parsing", () => {
+		const connector = defineConnector(validConfig);
+		const parsed = connector.operations.prices.output?.safeParse({
+			name: "Bitcoin",
+			price: 50_000,
+		});
+
+		expect(parsed?.success).toBe(true);
+	});
+});

package/src/__tests__/errors.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "bun:test";
+import {
+	AuthError,
+	ConnectorError,
+	SDKError,
+	TransportError,
+	ValidationError,
+} from "../errors";
+
+describe("ConnectorError", () => {
+	it("should include fix hint", () => {
+		const err = new ConnectorError("Something broke", { fix: "Try again" });
+		expect(err.fix).toBe("Try again");
+		expect(err.message).toBe("Something broke");
+		expect(err.name).toBe("ConnectorError");
+	});
+
+	it("should include code", () => {
+		const err = new ConnectorError("Error", { code: "E001" });
+		expect(err.code).toBe("E001");
+	});
+
+	it("should be instanceof Error", () => {
+		const err = new ConnectorError("test");
+		expect(err instanceof Error).toBe(true);
+		expect(err instanceof ConnectorError).toBe(true);
+	});
+});
+
+describe("AuthError", () => {
+	it("should be instanceof ConnectorError", () => {
+		const err = new AuthError("Unauthorized", {
+			code: "refresh_failed",
+			fix: "Re-authenticate",
+		});
+		expect(err instanceof ConnectorError).toBe(true);
+		expect(err instanceof AuthError).toBe(true);
+		expect(err.name).toBe("AuthError");
+		expect(err.code).toBe("refresh_failed");
+	});
+});
+
+describe("ValidationError", () => {
+	it("should store zodError", () => {
+		const zodErr = { issues: [{ path: ["id"], message: "Required" }] };
+		const err = new ValidationError("Invalid input", {
+			zodError: zodErr,
+			fix: "Check id field",
+		});
+		expect(err.zodError).toEqual(zodErr);
+		expect(err instanceof ConnectorError).toBe(true);
+	});
+});
+
+describe("TransportError", () => {
+	it("should store HTTP status", () => {
+		const err = new TransportError("Connection failed", { status: 502 });
+		expect(err.status).toBe(502);
+		expect(err instanceof ConnectorError).toBe(true);
+	});
+});
+
+describe("SDKError", () => {
+	it("should be instanceof ConnectorError", () => {
+		const err = new SDKError("Internal SDK error");
+		expect(err instanceof ConnectorError).toBe(true);
+		expect(err.name).toBe("SDKError");
+	});
+});

package/src/__tests__/executor.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, it, mock } from "bun:test";
+
+import { z } from "../../node_modules/zod";
+
+import { TransportError } from "../errors";
+import { executeOperation } from "../runtime/executor";
+import type { ConnectorContext, ConnectorDefinition } from "../types";
+
+function createMockCtx(fetchResponse: unknown, status = 200): ConnectorContext {
+	return {
+		tls: {
+			fetch: mock(async (_url: string, _opts?: unknown) => ({
+				status,
+				ok: status >= 200 && status < 300,
+				headers: {},
+				rawHeaders: [],
+				body: "",
+				cookies: {
+					get: () => undefined,
+					getAll: () => ({}),
+					toString: () => "",
+				},
+				json: async <T>() => fetchResponse as T,
+			})),
+			createSession: mock(() => ({
+				fetch: async () => ({
+					status,
+					ok: status >= 200 && status < 300,
+					headers: {},
+					rawHeaders: [] as [string, string][],
+					body: "",
+					cookies: {
+						get: () => undefined,
+						getAll: () => ({}),
+						toString: () => "",
+					},
+					json: async <T>() => ({}) as T,
+				}),
+				close: () => {},
+			})),
+		},
+		http: {} as ConnectorContext["http"],
+		browser: {} as ConnectorContext["browser"],
+		session: {
+			get: mock(async () => null),
+			set: mock(async () => {}),
+			delete: mock(async () => {}),
+		},
+		state: {} as ConnectorContext["state"],
+		trace: {
+			span: async <T>(_name: string, fn: () => Promise<T>) => fn(),
+		},
+		auth: {
+			requestField: mock(async () => ""),
+		},
+	};
+}
+
+function createMockConnector(options?: {
+	handler?: ConnectorDefinition["operations"][string]["handler"];
+	auth?: ConnectorDefinition["auth"];
+}): ConnectorDefinition {
+	return {
+		id: "test-connector",
+		version: "1.0.0",
+		runtime: "standard",
+		auth: options?.auth,
+		meta: {
+			displayName: "Test Connector",
+			category: "test",
+		},
+		operations: {
+			search: {
+				description: "Search",
+				input: z.object({ query: z.string() }),
+				output: z.object({ results: z.array(z.string()) }),
+				handler:
+					options?.handler ??
+					(async (_ctx: ConnectorContext, input: unknown) => {
+						const parsed = z.object({ query: z.string() }).parse(input);
+
+						return {
+							results: [parsed.query],
+						};
+					}),
+			},
+		},
+	};
+}
+
+describe("executeOperation", () => {
+	it("runs the handler and validates output", async () => {
+		const ctx = createMockCtx({});
+		const connector = createMockConnector();
+
+		const result = await executeOperation(connector, "search", ctx, {
+			query: "test",
+		});
+
+		expect(result).toEqual({ results: ["test"] });
+	});
+
+	it("passes through handler output parsing", async () => {
+		const ctx = createMockCtx({});
+		const connector = createMockConnector({
+			handler: async () => ({ results: ["result1", "result2"] }),
+		});
+
+		const result = await executeOperation(connector, "search", ctx, {
+			query: "test",
+		});
+
+		expect(result).toEqual({ results: ["result1", "result2"] });
+	});
+
+	it("throws ConnectorError when operation not found", async () => {
+		const ctx = createMockCtx({});
+		const connector = createMockConnector();
+
+		await expect(
+			executeOperation(connector, "nonexistent", ctx, {}),
+		).rejects.toThrow("nonexistent");
+	});
+
+	it("throws ConnectorError when operation has no handler", async () => {
+		const ctx = createMockCtx({});
+		const connector: ConnectorDefinition = {
+			...createMockConnector(),
+			operations: {
+				search: {
+					description: "No upstream",
+					input: z.object({ query: z.string() }),
+					output: z.object({ results: z.array(z.string()) }),
+					handler: undefined as never,
+				},
+			},
+		};
+
+		await expect(
+			executeOperation(connector, "search", ctx, { query: "test" }),
+		).rejects.toThrow(TypeError);
+	});
+
+	it("auto-refreshes on 401 response if auth is configured", async () => {
+		let callCount = 0;
+		const ctx: ConnectorContext = {
+			...createMockCtx({}),
+			tls: {
+				fetch: mock(async () => {
+					callCount++;
+					const responseStatus = callCount === 1 ? 401 : 200;
+					return {
+						status: responseStatus,
+						ok: responseStatus >= 200 && responseStatus < 300,
+						headers: {},
+						rawHeaders: [],
+						body: "",
+						cookies: {
+							get: () => undefined,
+							getAll: () => ({}),
+							toString: () => "",
+						},
+						json: async <T>() => ({ items: [] }) as T,
+					};
+				}),
+				createSession: mock(() => ({
+					fetch: async () => ({
+						status: 200,
+						ok: true,
+						headers: {},
+						rawHeaders: [] as [string, string][],
+						body: "",
+						cookies: {
+							get: () => undefined,
+							getAll: () => ({}),
+							toString: () => "",
+						},
+						json: async <T>() => ({}) as T,
+					}),
+					close: () => {},
+				})),
+			},
+			session: {
+				get: mock(async (key: string) => (key === "__auth__" ? "token" : null)),
+				set: mock(async () => {}),
+				delete: mock(async () => {}),
+			},
+		};
+
+		const authRefresh = mock(async () => {});
+		const connector = createMockConnector({
+			auth: {
+				mode: "credentials",
+				refresh: authRefresh,
+			},
+			handler: async () => {
+				callCount++;
+				if (callCount === 1) {
+					throw new TransportError("Unauthorized", { status: 401 });
+				}
+
+				return { results: [] };
+			},
+		});
+
+		const result = await executeOperation(connector, "search", ctx, {
+			query: "test",
+		});
+
+		expect(authRefresh).toHaveBeenCalledTimes(1);
+		expect(callCount).toBe(2);
+		expect(result).toEqual({ results: [] });
+	});
+});