@apifuse/connector-sdk 2.0.0-beta.1

package/package.json

@@ -0,0 +1,64 @@
+{
+	"name": "@apifuse/connector-sdk",
+	"version": "2.0.0-beta.1",
+	"private": false,
+	"type": "module",
+	"description": "ApiFuse Connector SDK — Build connectors with zero architectural constraints",
+	"license": "MIT",
+	"main": "./src/index.ts",
+	"types": "./src/index.ts",
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"bin",
+		"README.md"
+	],
+	"keywords": [
+		"apifuse",
+		"connector",
+		"sdk",
+		"api",
+		"zod",
+		"hono"
+	],
+	"bin": {
+		"apifuse-init": "./bin/apifuse-init.ts",
+		"apifuse": "./bin/apifuse.ts"
+	},
+	"exports": {
+		".": {
+			"default": "./src/index.ts",
+			"import": "./src/index.ts",
+			"types": "./src/index.ts"
+		},
+		"./testing": {
+			"default": "./src/testing/index.ts",
+			"import": "./src/testing/index.ts",
+			"types": "./src/testing/index.ts"
+		}
+	},
+	"scripts": {
+		"lint": "biome check",
+		"lint:fix": "biome lint --write",
+		"format": "biome format --write",
+		"type-check": "tsc --noEmit",
+		"test": "bun test",
+		"check": "bun run lint && bun run type-check"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.13",
+		"@clack/prompts": "^1.2.0",
+		"@types/bun": "latest",
+		"@types/node": "^25.1.0",
+		"typescript": "^5.9.3"
+	},
+	"dependencies": {
+		"hono": "^4.7.11",
+		"playwright": "^1.55.1",
+		"playwright-stealth": "^0.0.1",
+		"tlsclientwrapper": "^4.2.0",
+		"zod": "^4.3.6"
+	}
+}

package/src/__tests__/auth.test.ts

@@ -0,0 +1,396 @@
+import { describe, expect, it } from "bun:test";
+
+import { AuthError, TransportError } from "../errors";
+import { createAuthManager } from "../runtime/auth";
+import { createSqliteSessionStore } from "../runtime/session";
+import { createStateContext } from "../runtime/state";
+import type {
+	AuthConfig,
+	AuthContext,
+	BrowserClient,
+	ConnectorContext,
+	HttpClient,
+	TlsClient,
+} from "../types";
+
+function parseAuthMarker(value: string | null): {
+	authenticated?: boolean;
+	refreshed?: boolean;
+	timestamp?: number;
+} | null {
+	if (value === null) {
+		return null;
+	}
+
+	return JSON.parse(value) as {
+		authenticated?: boolean;
+		refreshed?: boolean;
+		timestamp?: number;
+	};
+}
+
+function createMockCtx(): ConnectorContext {
+	return {
+		http: {} as HttpClient,
+		tls: {} as TlsClient,
+		browser: {} as BrowserClient,
+		session: createSqliteSessionStore({ databasePath: ":memory:" }),
+		state: createStateContext("test-secret"),
+		trace: { span: async (_name, fn) => fn() },
+		auth: {} as AuthContext,
+	};
+}
+
+describe("createAuthManager", () => {
+	it("calls config.exchange with the provided ctx and credentials", async () => {
+		const ctx = createMockCtx();
+		const credentials = {
+			username: "demo-user",
+			password: "demo-pass",
+		};
+
+		let receivedCtx: ConnectorContext | undefined;
+		let receivedCredentials: Record<string, string> | undefined;
+
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				exchange: async (exchangeCtx, exchangeCredentials) => {
+					receivedCtx = exchangeCtx;
+					receivedCredentials = exchangeCredentials;
+				},
+			},
+			ctx.session,
+		);
+
+		await manager.exchange(ctx, credentials);
+
+		expect(receivedCtx).toBe(ctx);
+		expect(receivedCredentials).toEqual(credentials);
+		expect(typeof receivedCtx?.auth.requestField).toBe("function");
+	});
+
+	it("stores an authenticated session marker after a successful exchange", async () => {
+		const ctx = createMockCtx();
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				exchange: async () => {},
+			},
+			ctx.session,
+		);
+
+		await manager.exchange(ctx, { username: "demo-user" });
+
+		const marker = parseAuthMarker(await ctx.session.get("__auth__"));
+
+		expect(marker?.authenticated).toBeTrue();
+		expect(typeof marker?.timestamp).toBe("number");
+	});
+
+	it("wraps exchange failures as AuthError", async () => {
+		const ctx = createMockCtx();
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				exchange: async () => {
+					throw new Error("otp failed");
+				},
+			},
+			ctx.session,
+		);
+
+		await expect(
+			manager.exchange(ctx, { username: "demo-user" }),
+		).rejects.toBeInstanceOf(AuthError);
+	});
+
+	it("returns auth fields from config", () => {
+		const fields: AuthConfig["fields"] = [
+			{ name: "username", label: "Username", type: "text", required: true },
+			{ name: "otp", label: "OTP", type: "otp", deferred: true },
+		];
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				fields,
+				exchange: async () => {},
+			},
+			createSqliteSessionStore({ databasePath: ":memory:" }),
+		);
+
+		expect(manager.getFields()).toEqual(fields);
+	});
+
+	it("resolves deferred auth fields through requestField + resolveField", async () => {
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				exchange: async () => {},
+			},
+			createSqliteSessionStore({ databasePath: ":memory:" }),
+		);
+		const auth = manager.createAuthContext();
+		const pendingOtp = auth.requestField("otp");
+
+		setTimeout(() => {
+			manager.resolveField("otp", "123456");
+		}, 0);
+
+		expect(await pendingOtp).toBe("123456");
+	});
+
+	it("reports auth-none mode", () => {
+		const manager = createAuthManager(
+			{
+				mode: "none",
+			},
+			createSqliteSessionStore({ databasePath: ":memory:" }),
+		);
+
+		expect(manager.isAuthNone()).toBeTrue();
+	});
+
+	it("calls config.refresh and stores a refreshed session marker", async () => {
+		const ctx = createMockCtx();
+		let receivedCtx: ConnectorContext | undefined;
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				refresh: async (refreshCtx) => {
+					receivedCtx = refreshCtx;
+				},
+			},
+			ctx.session,
+		);
+
+		await manager.refresh(ctx);
+
+		const marker = parseAuthMarker(await ctx.session.get("__auth__"));
+
+		expect(receivedCtx).toBe(ctx);
+		expect(marker?.authenticated).toBeTrue();
+		expect(marker?.refreshed).toBeTrue();
+		expect(typeof marker?.timestamp).toBe("number");
+	});
+
+	it("calls config.disconnect and deletes the auth session marker", async () => {
+		const ctx = createMockCtx();
+		await ctx.session.set("__auth__", JSON.stringify({ authenticated: true }));
+		let receivedCtx: ConnectorContext | undefined;
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				disconnect: async (disconnectCtx) => {
+					receivedCtx = disconnectCtx;
+				},
+			},
+			ctx.session,
+		);
+
+		await manager.disconnect(ctx);
+
+		expect(receivedCtx).toBe(ctx);
+		expect(await ctx.session.get("__auth__")).toBeNull();
+	});
+
+	it("deletes the auth session marker when disconnect is not configured", async () => {
+		const ctx = createMockCtx();
+		await ctx.session.set("__auth__", JSON.stringify({ authenticated: true }));
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+			},
+			ctx.session,
+		);
+
+		await manager.disconnect(ctx);
+
+		expect(await ctx.session.get("__auth__")).toBeNull();
+	});
+
+	it("wraps disconnect failures as AuthError", async () => {
+		const ctx = createMockCtx();
+		await ctx.session.set("__auth__", JSON.stringify({ authenticated: true }));
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				disconnect: async () => {
+					throw new Error("logout failed");
+				},
+			},
+			ctx.session,
+		);
+
+		await expect(manager.disconnect(ctx)).rejects.toBeInstanceOf(AuthError);
+		expect(await ctx.session.get("__auth__")).toBeNull();
+	});
+
+	it("wraps refresh failures as AuthError", async () => {
+		const ctx = createMockCtx();
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				refresh: async () => {
+					throw new Error("refresh failed");
+				},
+			},
+			ctx.session,
+		);
+
+		await expect(manager.refresh(ctx)).rejects.toBeInstanceOf(AuthError);
+	});
+
+	it("throws AuthError when refresh is not configured", async () => {
+		const ctx = createMockCtx();
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+			},
+			ctx.session,
+		);
+
+		await expect(manager.refresh(ctx)).rejects.toBeInstanceOf(AuthError);
+	});
+
+	it("returns operation result without refreshing when auto-refresh is unnecessary", async () => {
+		const ctx = createMockCtx();
+		let refreshCount = 0;
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				refresh: async () => {
+					refreshCount += 1;
+				},
+			},
+			ctx.session,
+		);
+
+		const result = await manager.wrapWithAutoRefresh(ctx, async () => "ok");
+
+		expect(result).toBe("ok");
+		expect(refreshCount).toBe(0);
+	});
+
+	it("refreshes once and retries when the operation fails with 401", async () => {
+		const ctx = createMockCtx();
+		let refreshCount = 0;
+		let attempt = 0;
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				refresh: async () => {
+					refreshCount += 1;
+				},
+			},
+			ctx.session,
+		);
+
+		const result = await manager.wrapWithAutoRefresh(ctx, async () => {
+			attempt += 1;
+			if (attempt === 1) {
+				throw new TransportError("Unauthorized", { status: 401 });
+			}
+
+			return "recovered";
+		});
+
+		expect(result).toBe("recovered");
+		expect(refreshCount).toBe(1);
+		expect(attempt).toBe(2);
+	});
+
+	it("deduplicates concurrent refreshes when multiple operations hit 401", async () => {
+		const ctx = createMockCtx();
+		let refreshCount = 0;
+		let releaseRefresh!: () => void;
+		const refreshBarrier = new Promise<void>((resolve) => {
+			releaseRefresh = resolve;
+		});
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				refresh: async () => {
+					refreshCount += 1;
+					await refreshBarrier;
+				},
+			},
+			ctx.session,
+		);
+
+		function failWith401ThenSucceed(label: string) {
+			let attempt = 0;
+			return async () => {
+				attempt += 1;
+				if (attempt === 1) {
+					throw new TransportError(`Unauthorized: ${label}`, { status: 401 });
+				}
+
+				return label;
+			};
+		}
+
+		const pending = Promise.all([
+			manager.wrapWithAutoRefresh(ctx, failWith401ThenSucceed("one")),
+			manager.wrapWithAutoRefresh(ctx, failWith401ThenSucceed("two")),
+			manager.wrapWithAutoRefresh(ctx, failWith401ThenSucceed("three")),
+		]);
+
+		await Promise.resolve();
+		expect(refreshCount).toBe(1);
+		releaseRefresh();
+
+		await expect(pending).resolves.toEqual(["one", "two", "three"]);
+		expect(refreshCount).toBe(1);
+	});
+
+	it("rethrows the original 401 when the retry also fails", async () => {
+		const ctx = createMockCtx();
+		let refreshCount = 0;
+		let attempt = 0;
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				refresh: async () => {
+					refreshCount += 1;
+				},
+			},
+			ctx.session,
+		);
+		const originalError = new TransportError("Unauthorized", { status: 401 });
+
+		await expect(
+			manager.wrapWithAutoRefresh(ctx, async () => {
+				attempt += 1;
+				if (attempt === 1) {
+					throw originalError;
+				}
+
+				throw new TransportError("Still unauthorized", { status: 401 });
+			}),
+		).rejects.toBe(originalError);
+		expect(refreshCount).toBe(1);
+	});
+
+	it("rethrows non-401 errors without refreshing", async () => {
+		const ctx = createMockCtx();
+		let refreshCount = 0;
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				refresh: async () => {
+					refreshCount += 1;
+				},
+			},
+			ctx.session,
+		);
+		const failure = new TransportError("Bad request", { status: 400 });
+
+		await expect(
+			manager.wrapWithAutoRefresh(ctx, async () => {
+				throw failure;
+			}),
+		).rejects.toBe(failure);
+		expect(refreshCount).toBe(0);
+	});
+});

package/src/__tests__/browser-auth.test.ts

@@ -0,0 +1,180 @@
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+
+import { z } from "zod";
+
+import { createAuthManager } from "../runtime/auth";
+import { createSqliteSessionStore } from "../runtime/session";
+import type { ConnectorContext, ConnectorDefinition } from "../types";
+
+const readlineState = {
+	answers: [] as string[],
+	closeCount: 0,
+	questions: [] as string[],
+};
+
+mock.module("node:readline", () => ({
+	createInterface: () => ({
+		question: (prompt: string, callback: (answer: string) => void) => {
+			readlineState.questions.push(prompt);
+			callback(readlineState.answers.shift() ?? "");
+		},
+		close: () => {
+			readlineState.closeCount += 1;
+		},
+	}),
+}));
+
+const { createConnectorContext, runExchangeWithDeferredFieldPrompting } =
+	await import("../../bin/apifuse-dev");
+
+function createConnector(runtime: "standard" | "browser"): ConnectorDefinition {
+	return {
+		id: `test-${runtime}`,
+		version: "1.0.0",
+		runtime,
+		meta: {
+			displayName: `Test ${runtime}`,
+			category: "test",
+		},
+		browser: runtime === "browser" ? { engine: "nodriver" } : undefined,
+		operations: {
+			auth: {
+				input: z.unknown(),
+				output: z.unknown(),
+				handler: async (_ctx, input: unknown) => input,
+			},
+		},
+	};
+}
+
+describe("browser auth flow", () => {
+	it("auth exchange receives a real browser client when runtime is browser", async () => {
+		const session = createSqliteSessionStore({ databasePath: ":memory:" });
+		let browserHasClose = false;
+		const authManager = createAuthManager(
+			{
+				mode: "credentials",
+				exchange: async (ctx) => {
+					browserHasClose = Reflect.has(ctx.browser as object, "close");
+				},
+			},
+			session,
+		);
+
+		const { ctx } = createConnectorContext(
+			createConnector("browser"),
+			session,
+			authManager,
+		);
+
+		await authManager.exchange(ctx, { username: "demo" });
+
+		expect(browserHasClose).toBeTrue();
+	});
+
+	it("uses browser stub when runtime is standard", async () => {
+		const session = createSqliteSessionStore({ databasePath: ":memory:" });
+		const authManager = createAuthManager(undefined, session);
+		const { ctx } = createConnectorContext(
+			createConnector("standard"),
+			session,
+			authManager,
+		);
+
+		expect(Reflect.has(ctx.browser as object, "close")).toBeFalse();
+		await expect(ctx.browser.newPage()).rejects.toMatchObject({
+			code: "BROWSER_RUNTIME_UNSUPPORTED",
+		});
+	});
+});
+
+describe("deferred OTP via getPendingFields", () => {
+	beforeEach(() => {
+		readlineState.answers.length = 0;
+		readlineState.closeCount = 0;
+		readlineState.questions.length = 0;
+	});
+
+	it("resolveField delivers OTP to a waiting requestField and exposes pending fields", async () => {
+		const session = createSqliteSessionStore({ databasePath: ":memory:" });
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				exchange: async (ctx) => {
+					const otp = await ctx.auth.requestField("otp");
+					expect(otp).toBe("123456");
+				},
+			},
+			session,
+		);
+		const ctx: ConnectorContext = {
+			browser: {} as never,
+			http: {} as never,
+			tls: {} as never,
+			session,
+			state: {} as never,
+			trace: {
+				span: async <T>(_name: string, fn: () => Promise<T>) => await fn(),
+			},
+			auth: manager.createAuthContext(),
+		};
+
+		const exchangePromise = manager.exchange(ctx, {
+			phone: "+82",
+			password: "x",
+		});
+
+		await Promise.resolve();
+		expect(manager.getPendingFields()).toContain("otp");
+		manager.resolveField("otp", "123456");
+
+		await exchangePromise;
+		expect(manager.getPendingFields()).toEqual([]);
+	});
+
+	it("prompts for deferred OTP and resolves it through readline", async () => {
+		readlineState.answers.push(" 123456 ");
+		const session = createSqliteSessionStore({ databasePath: ":memory:" });
+		const manager = createAuthManager(
+			{
+				mode: "credentials",
+				exchange: async (ctx) => {
+					const otp = await ctx.auth.requestField("otp");
+					expect(otp).toBe("123456");
+				},
+			},
+			session,
+		);
+		const ctx: ConnectorContext = {
+			browser: {} as never,
+			http: {} as never,
+			tls: {} as never,
+			session,
+			state: {} as never,
+			trace: {
+				span: async <T>(_name: string, fn: () => Promise<T>) => await fn(),
+			},
+			auth: manager.createAuthContext(),
+		};
+
+		await runExchangeWithDeferredFieldPrompting(
+			manager,
+			ctx,
+			{ username: "demo" },
+			{ pollIntervalMs: 0 },
+		);
+
+		expect(readlineState.questions).toEqual(["\n[apifuse dev] Enter otp: "]);
+		expect(readlineState.closeCount).toBe(1);
+		expect(manager.getPendingFields()).toEqual([]);
+	});
+
+	it("getPendingFields returns empty when no fields are pending", () => {
+		const manager = createAuthManager(
+			undefined,
+			createSqliteSessionStore({ databasePath: ":memory:" }),
+		);
+
+		expect(manager.getPendingFields()).toEqual([]);
+	});
+});