@apifuse/connector-sdk 2.0.0-beta.1

package/src/__tests__/proxy.test.ts

@@ -0,0 +1,359 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test";
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { loadApiFuseConfig, resolveProxyConfig } from "../config/loader";
+import { createHttpClient } from "../runtime/http";
+
+type MockSessionResponse = {
+	status: number;
+	body: string;
+	headers?: Record<string, string>;
+	rawHeaders?: Record<string, string>;
+	usedProtocol?: string;
+};
+
+type MockSessionState = {
+	getCalls: Array<{ url: string; options?: Record<string, unknown> }>;
+	options: Record<string, unknown>;
+	responses: MockSessionResponse[];
+	closed: boolean;
+	proxyUrl?: string;
+	get: (
+		url: string,
+		options?: Record<string, unknown>,
+	) => Promise<MockSessionResponse>;
+	close: () => void;
+	destroySession: () => Promise<void>;
+	post: (
+		url: string,
+		body: string | Buffer | null,
+		options?: Record<string, unknown>,
+	) => Promise<MockSessionResponse>;
+	put: (
+		url: string,
+		body: string | Buffer | null,
+		options?: Record<string, unknown>,
+	) => Promise<MockSessionResponse>;
+	patch: (
+		url: string,
+		body: string | Buffer | null,
+		options?: Record<string, unknown>,
+	) => Promise<MockSessionResponse>;
+	delete: (
+		url: string,
+		options?: Record<string, unknown>,
+	) => Promise<MockSessionResponse>;
+	head: (
+		url: string,
+		options?: Record<string, unknown>,
+	) => Promise<MockSessionResponse>;
+	optionsMethod: (
+		url: string,
+		options?: Record<string, unknown>,
+	) => Promise<MockSessionResponse>;
+};
+
+const tlsState = {
+	sessions: [] as MockSessionState[],
+	queuedResponses: [] as MockSessionResponse[],
+	moduleClients: 0,
+};
+
+class MockModuleClient {
+	constructor() {
+		tlsState.moduleClients += 1;
+	}
+}
+
+class MockSessionClient {
+	private readonly state: MockSessionState;
+
+	constructor(
+		_moduleClient: MockModuleClient,
+		options: Record<string, unknown>,
+	) {
+		this.state = {
+			closed: false,
+			getCalls: [],
+			options,
+			proxyUrl:
+				typeof options.proxyUrl === "string" ? options.proxyUrl : undefined,
+			responses: tlsState.queuedResponses.splice(0),
+			get: async (url: string, requestOptions?: Record<string, unknown>) => {
+				this.state.getCalls.push({ url, options: requestOptions });
+				const response = this.state.responses.shift();
+				if (!response) {
+					throw new Error("No queued response for GET");
+				}
+				return response;
+			},
+			post: async () => {
+				throw new Error("POST not implemented in proxy test mock");
+			},
+			put: async () => {
+				throw new Error("PUT not implemented in proxy test mock");
+			},
+			patch: async () => {
+				throw new Error("PATCH not implemented in proxy test mock");
+			},
+			delete: async () => {
+				throw new Error("DELETE not implemented in proxy test mock");
+			},
+			head: async () => {
+				throw new Error("HEAD not implemented in proxy test mock");
+			},
+			optionsMethod: async () => {
+				throw new Error("OPTIONS not implemented in proxy test mock");
+			},
+			close: () => {
+				this.state.closed = true;
+			},
+			destroySession: async () => {
+				this.state.closed = true;
+			},
+		};
+
+		tlsState.sessions.push(this.state);
+	}
+
+	async get(url: string, options?: Record<string, unknown>) {
+		return this.state.get(url, options);
+	}
+
+	async post(
+		url: string,
+		body: string | Buffer | null,
+		options?: Record<string, unknown>,
+	) {
+		return this.state.post(url, body, options);
+	}
+
+	async put(
+		url: string,
+		body: string | Buffer | null,
+		options?: Record<string, unknown>,
+	) {
+		return this.state.put(url, body, options);
+	}
+
+	async patch(
+		url: string,
+		body: string | Buffer | null,
+		options?: Record<string, unknown>,
+	) {
+		return this.state.patch(url, body, options);
+	}
+
+	async delete(url: string, options?: Record<string, unknown>) {
+		return this.state.delete(url, options);
+	}
+
+	async head(url: string, options?: Record<string, unknown>) {
+		return this.state.head(url, options);
+	}
+
+	async options(url: string, options?: Record<string, unknown>) {
+		return this.state.optionsMethod(url, options);
+	}
+
+	close() {
+		this.state.close();
+	}
+
+	async destroySession() {
+		await this.state.destroySession();
+	}
+}
+
+mock.module("tlsclientwrapper", () => ({
+	ModuleClient: MockModuleClient,
+	SessionClient: MockSessionClient,
+}));
+
+describe("proxy integration", () => {
+	let originalFetch: typeof fetch;
+	let originalProxyEnv: string | undefined;
+
+	beforeEach(() => {
+		originalFetch = global.fetch;
+		originalProxyEnv = process.env.APIFUSE_PROXY_URL;
+		delete process.env.APIFUSE_PROXY_URL;
+		tlsState.sessions.length = 0;
+		tlsState.queuedResponses.length = 0;
+		tlsState.moduleClients = 0;
+	});
+
+	afterEach(() => {
+		global.fetch = originalFetch;
+		if (originalProxyEnv) {
+			process.env.APIFUSE_PROXY_URL = originalProxyEnv;
+		} else {
+			delete process.env.APIFUSE_PROXY_URL;
+		}
+	});
+
+	it("uses apifuse config proxy when upstream proxy routing is enabled", async () => {
+		let capturedProxy: string | undefined;
+
+		global.fetch = (async (_url, init) => {
+			capturedProxy = (init as RequestInit & { proxy?: string })?.proxy;
+			return new Response(JSON.stringify({ ok: true }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}) as typeof fetch;
+
+		const http = createHttpClient("https://example.com", {
+			apifuseConfig: { proxy: { url: "https://config-proxy.example:8443" } },
+			upstream: { proxy: true },
+		});
+
+		await http.get("/health");
+
+		expect(capturedProxy).toBe("https://config-proxy.example:8443");
+	});
+
+	it("uses APIFUSE_PROXY_URL when upstream proxy routing is enabled", async () => {
+		let capturedProxy: string | undefined;
+		process.env.APIFUSE_PROXY_URL = "https://env-proxy.example:8443";
+
+		global.fetch = (async (_url, init) => {
+			capturedProxy = (init as RequestInit & { proxy?: string })?.proxy;
+			return new Response(JSON.stringify({ ok: true }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}) as typeof fetch;
+
+		const http = createHttpClient("https://example.com", {
+			upstream: { proxy: true },
+		});
+
+		await http.get("/health");
+
+		expect(capturedProxy).toBe("https://env-proxy.example:8443");
+	});
+
+	it("passes request-level proxy through ctx.http", async () => {
+		let capturedProxy: string | undefined;
+
+		global.fetch = (async (_url, init) => {
+			capturedProxy = (init as RequestInit & { proxy?: string })?.proxy;
+			return new Response(JSON.stringify({ ok: true }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}) as typeof fetch;
+
+		const http = createHttpClient("https://example.com");
+
+		await http.get("/health", { proxy: "https://request-proxy.example:8443" });
+
+		expect(capturedProxy).toBe("https://request-proxy.example:8443");
+	});
+
+	it("warns once when proxy routing is required but missing", async () => {
+		const warnings: string[] = [];
+
+		global.fetch = (async () =>
+			new Response(JSON.stringify({ ok: true }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			})) as unknown as typeof fetch;
+
+		const http = createHttpClient("https://example.com", {
+			upstream: { proxy: true },
+			warn: (message) => {
+				warnings.push(message);
+			},
+		});
+
+		await http.get("/health");
+		await http.get("/health");
+
+		expect(warnings).toEqual([
+			"[connector-sdk] Connector requested proxy routing, but no proxy URL was configured. Continuing without proxy.",
+		]);
+	});
+
+	it("passes resolved proxy through ctx.tls session config and request options", async () => {
+		tlsState.queuedResponses.push({
+			status: 200,
+			body: "ok",
+			headers: { "content-type": "text/plain" },
+		});
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com", {
+			apifuseConfig: { proxy: { url: "https://tls-proxy.example:8443" } },
+			upstream: { proxy: true },
+		});
+
+		await client.fetch("/health");
+
+		expect(tlsState.sessions[0]?.options).toMatchObject({
+			proxyUrl: "https://tls-proxy.example:8443",
+		});
+		expect(tlsState.sessions[0]?.getCalls[0]?.options).toMatchObject({
+			proxy: "https://tls-proxy.example:8443",
+		});
+	});
+
+	it("passes request-level proxy through ctx.tls", async () => {
+		tlsState.queuedResponses.push({
+			status: 200,
+			body: "ok",
+			headers: { "content-type": "text/plain" },
+		});
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com");
+
+		await client.fetch("/health", {
+			proxy: "https://request-tls-proxy.example:8443",
+		});
+
+		expect(tlsState.sessions[0]?.options).toMatchObject({
+			proxyUrl: "https://request-tls-proxy.example:8443",
+		});
+		expect(tlsState.sessions[0]?.getCalls[0]?.options).toMatchObject({
+			proxy: "https://request-tls-proxy.example:8443",
+		});
+	});
+
+	it("resolves proxy config from env before config", () => {
+		process.env.APIFUSE_PROXY_URL = "https://env-proxy.example:8443";
+
+		expect(
+			resolveProxyConfig({
+				apifuseConfig: { proxy: { url: "https://config-proxy.example:8443" } },
+				upstream: { proxy: true },
+			}),
+		).toEqual({
+			shouldWarn: false,
+			url: "https://env-proxy.example:8443",
+		});
+	});
+
+	it("hydrates APIFUSE_PROXY_URL from apifuse.config.ts when env is unset", async () => {
+		const directory = await mkdtemp(path.join(tmpdir(), "apifuse-proxy-"));
+
+		await Bun.write(
+			`${directory}/apifuse.config.ts`,
+			[
+				"export default {",
+				"  proxy: { url: 'https://file-proxy.example:8443' },",
+				"};",
+			].join("\n"),
+		);
+
+		const config = await loadApiFuseConfig(directory);
+
+		expect(config.proxy?.url).toBe("https://file-proxy.example:8443");
+		expect(process.env.APIFUSE_PROXY_URL).toBe(
+			"https://file-proxy.example:8443",
+		);
+	});
+});

package/src/__tests__/recipes.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "bun:test";
+
+import { extractPagination, normalizeErrorResponse } from "../recipes/rest-api";
+
+describe("rest-api recipe", () => {
+	it("extracts pagination from standard shape", () => {
+		expect(extractPagination({ page: 1, per_page: 10, total: 100 })).toEqual({
+			page: 1,
+			perPage: 10,
+			total: 100,
+			totalPages: 10,
+			hasNext: true,
+			hasPrev: false,
+		});
+	});
+
+	it("returns null for missing pagination shape", () => {
+		expect(extractPagination({ foo: "bar" })).toBeNull();
+	});
+
+	it("normalizes error response from string error", () => {
+		expect(normalizeErrorResponse({ error: "Not found" })).toEqual({
+			message: "Not found",
+		});
+	});
+
+	it("normalizes error response from message field", () => {
+		expect(normalizeErrorResponse({ message: "Forbidden" })).toEqual({
+			message: "Forbidden",
+		});
+	});
+
+	it("returns null for empty error object", () => {
+		expect(normalizeErrorResponse({})).toBeNull();
+	});
+});

package/src/__tests__/serve.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+
+import { createConnectorServer } from "../serve";
+import type { ConnectorDefinition } from "../types";
+
+process.env.APIFUSE_STATE_SECRET = "test-secret";
+
+function createTestConnector() {
+	return {
+		id: "test-connector",
+		version: "1.0.0",
+		runtime: "standard",
+		meta: {
+			displayName: "Test Connector",
+			category: "test",
+		},
+		auth: {
+			mode: "credentials",
+			fields: [
+				{ name: "username", label: "Username", type: "text", required: true },
+				{ name: "otp", label: "One-time code", type: "otp", deferred: true },
+			],
+			exchange: async (ctx, credentials) => {
+				await ctx.session.set("username", credentials.username ?? "unknown");
+				const otp = await ctx.auth.requestField("otp");
+				await ctx.session.set("otp", otp);
+				await ctx.session.set(
+					"accessToken",
+					`token:${credentials.username}:${otp}`,
+				);
+			},
+			refresh: async (ctx) => {
+				const token = await ctx.session.get("accessToken");
+				await ctx.session.set("accessToken", `${token ?? "token"}:refreshed`);
+			},
+			disconnect: async (ctx) => {
+				await ctx.session.delete("accessToken");
+			},
+		},
+		operations: {
+			echo: {
+				description: "Echo input",
+				input: z.object({ value: z.string() }),
+				output: z.object({ echoed: z.string() }),
+				hints: { rateLimit: "low" },
+				handler: async (ctx, input) => {
+					const typedInput = input as { value: string };
+					const count = Number((await ctx.session.get("count")) ?? "0") + 1;
+					await ctx.session.set("count", String(count));
+					return { echoed: typedInput.value };
+				},
+			},
+		},
+	} satisfies ConnectorDefinition;
+}
+
+describe("createConnectorServer", () => {
+	const connector = createTestConnector();
+	const { app } = createConnectorServer(connector, {
+		stateSecret: process.env.APIFUSE_STATE_SECRET,
+	});
+
+	it("executes an operation and returns sessionPatch", async () => {
+		const response = await app.request("/execute/echo", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				input: { value: "hello" },
+				session: { count: "1" },
+			}),
+		});
+
+		expect(response.status).toBe(200);
+		expect(await response.json()).toEqual({
+			data: { echoed: "hello" },
+			sessionPatch: { count: "2" },
+			trace: {
+				spans: [
+					expect.objectContaining({
+						name: "handler:echo",
+						status: "ok",
+					}),
+				],
+			},
+		});
+	});
+
+	it("returns pending_field for deferred auth", async () => {
+		const response = await app.request("/connect", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ credentials: { username: "demo" } }),
+		});
+
+		expect(response.status).toBe(200);
+		expect(await response.json()).toEqual({
+			status: "pending_field",
+			field: "otp",
+			fieldLabel: "One-time code",
+			resumeToken: expect.any(String),
+			sessionPatch: { username: "demo" },
+		});
+	});
+
+	it("resumes deferred auth and returns success with sessionPatch", async () => {
+		const connectResponse = await app.request("/connect", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ credentials: { username: "demo" } }),
+		});
+		const connectBody = (await connectResponse.json()) as {
+			status: string;
+			resumeToken: string;
+			sessionPatch: Record<string, string>;
+		};
+
+		const resumeResponse = await app.request("/connect/resume", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				resumeToken: connectBody.resumeToken,
+				fieldValue: "123456",
+				session: connectBody.sessionPatch,
+			}),
+		});
+
+		expect(resumeResponse.status).toBe(200);
+		expect(await resumeResponse.json()).toEqual({
+			status: "success",
+			sessionPatch: {
+				username: "demo",
+				otp: "123456",
+				accessToken: "token:demo:123456",
+				__auth__: expect.any(String),
+			},
+		});
+	});
+
+	it("refreshes auth session", async () => {
+		const response = await app.request("/refresh", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				session: { accessToken: "token:demo:123456" },
+			}),
+		});
+
+		expect(response.status).toBe(200);
+		expect(await response.json()).toEqual({
+			status: "success",
+			sessionPatch: {
+				accessToken: "token:demo:123456:refreshed",
+				__auth__: expect.any(String),
+			},
+		});
+	});
+
+	it("disconnects auth session", async () => {
+		const response = await app.request("/disconnect", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({
+				session: { accessToken: "token:demo:123456" },
+			}),
+		});
+
+		expect(response.status).toBe(200);
+		expect(await response.json()).toEqual({ status: "success" });
+	});
+
+	it("returns health status", async () => {
+		const response = await app.request("/health");
+
+		expect(response.status).toBe(200);
+		expect(await response.json()).toEqual({
+			status: "ok",
+			connector: "test-connector",
+			version: "1.0.0",
+			uptime: expect.any(Number),
+		});
+	});
+
+	it("returns operation schema", async () => {
+		const response = await app.request("/schema/echo");
+		const body = (await response.json()) as {
+			operationId: string;
+			description: string;
+			hints: Record<string, string>;
+			input: {
+				type: string;
+				properties: Record<string, unknown>;
+				required: string[];
+			};
+			output: {
+				type: string;
+				properties: Record<string, unknown>;
+				required: string[];
+			};
+		};
+
+		expect(response.status).toBe(200);
+		expect(body.operationId).toBe("echo");
+		expect(body.description).toBe("Echo input");
+		expect(body.hints).toEqual({ rateLimit: "low" });
+		expect(body.input.type).toBe("object");
+		expect(body.input.properties.value).toEqual(
+			expect.objectContaining({ type: "string" }),
+		);
+		expect(body.input.required).toContain("value");
+		expect(body.output.type).toBe("object");
+		expect(body.output.properties.echoed).toEqual(
+			expect.objectContaining({ type: "string" }),
+		);
+	});
+
+	it("returns 404 for unknown operation", async () => {
+		const response = await app.request("/execute/missing", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ input: {}, session: {} }),
+		});
+
+		expect(response.status).toBe(404);
+		expect(await response.json()).toEqual({
+			error: {
+				code: "NOT_FOUND",
+				message: "Unknown operation: test-connector/missing",
+				details: { fix: "Valid operations: echo" },
+			},
+		});
+	});
+});