@apifuse/connector-sdk 2.0.0-beta.1

package/src/__tests__/tls.test.ts

@@ -0,0 +1,345 @@
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+
+import { TransportError } from "../errors";
+import { normalizeResponse } from "../runtime/tls";
+import type { DeclarativeTlsResponse } from "../types";
+
+type MockSessionResponse = {
+	status: number;
+	body: string;
+	headers?: Record<string, string>;
+	rawHeaders?: Record<string, string> | [string, string][];
+	usedProtocol?: string;
+	cookies?:
+		| Record<string, { name: string; value: string }>
+		| Array<{ name: string; value: string }>;
+};
+
+type MockSessionState = {
+	responses: MockSessionResponse[];
+	error?: Error;
+	getCalls: Array<{ url: string; options?: Record<string, unknown> }>;
+	postCalls: Array<{
+		url: string;
+		body: string | Buffer | null;
+		options?: Record<string, unknown>;
+	}>;
+	closed: boolean;
+	options: Record<string, unknown>;
+};
+
+const mockTlsState = {
+	sessions: [] as MockSessionState[],
+	queuedResponses: [] as MockSessionResponse[],
+	queuedErrors: [] as Error[],
+	moduleClients: 0,
+};
+
+class MockModuleClient {
+	constructor() {
+		mockTlsState.moduleClients += 1;
+	}
+}
+
+class MockSessionClient {
+	private readonly state: MockSessionState;
+
+	constructor(
+		_moduleClient: MockModuleClient,
+		options: Record<string, unknown>,
+	) {
+		this.state = {
+			responses: mockTlsState.queuedResponses.splice(0),
+			error: mockTlsState.queuedErrors.shift(),
+			getCalls: [],
+			postCalls: [],
+			closed: false,
+			options,
+		};
+
+		mockTlsState.sessions.push(this.state);
+	}
+
+	async get(url: string, options?: Record<string, unknown>) {
+		this.state.getCalls.push({ url, options });
+
+		if (this.state.error) {
+			throw this.state.error;
+		}
+
+		const response = this.state.responses.shift();
+		if (!response) {
+			throw new Error("No queued response for GET");
+		}
+
+		return response;
+	}
+
+	async post(
+		url: string,
+		body: string | Buffer | null,
+		options?: Record<string, unknown>,
+	) {
+		this.state.postCalls.push({ url, body, options });
+
+		if (this.state.error) {
+			throw this.state.error;
+		}
+
+		const response = this.state.responses.shift();
+		if (!response) {
+			throw new Error("No queued response for POST");
+		}
+
+		return response;
+	}
+
+	close() {
+		this.state.closed = true;
+	}
+}
+
+mock.module("tlsclientwrapper", () => ({
+	ModuleClient: MockModuleClient,
+	SessionClient: MockSessionClient,
+}));
+
+describe("createTlsClient", () => {
+	beforeEach(() => {
+		mockTlsState.sessions.length = 0;
+		mockTlsState.queuedResponses.length = 0;
+		mockTlsState.queuedErrors.length = 0;
+		mockTlsState.moduleClients = 0;
+	});
+
+	it("returns fetch and createSession functions", async () => {
+		const { createTlsClient } = await import("../runtime/tls");
+
+		const client = createTlsClient("https://example.com");
+
+		expect(client.fetch).toBeFunction();
+		expect(client.createSession).toBeFunction();
+	});
+
+	it("returns normalized response for successful fetch", async () => {
+		mockTlsState.queuedResponses.push({
+			status: 200,
+			body: '{"ok":true}',
+			headers: { "content-type": "text/plain" },
+			rawHeaders: [["content-type", "text/plain"]],
+			usedProtocol: "h2",
+			cookies: [{ name: "sid", value: "abc" }],
+		});
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com");
+
+		const response = (await client.fetch("/health", {
+			headers: { accept: "text/plain" },
+		})) as DeclarativeTlsResponse;
+
+		expect(response.status).toBe(200);
+		expect(response.ok).toBe(true);
+		expect(response.headers).toEqual({ "content-type": "text/plain" });
+		expect(response.rawHeaders).toEqual([["content-type", "text/plain"]]);
+		expect(response.httpVersion).toBe("h2");
+		expect(response.cookies.get("sid")).toBe("abc");
+		expect(response.cookies.getAll()).toEqual({ sid: "abc" });
+		expect(response.cookies.toString()).toBe("sid=abc");
+		await expect(response.json<{ ok: boolean }>()).resolves.toEqual({
+			ok: true,
+		});
+	});
+
+	it("normalizes raw response metadata and false ok flag", async () => {
+		const response = normalizeResponse({
+			status: 400,
+			body: '{"error":true}',
+			headers: { "content-type": "application/json" },
+			rawHeaders: { "x-test": "1" },
+			cookies: { sid: { name: "sid", value: "xyz" } },
+		} as never) as DeclarativeTlsResponse;
+
+		expect(response.ok).toBe(false);
+		expect(response.rawHeaders).toEqual([["x-test", "1"]]);
+		expect(response.cookies.get("sid")).toBe("xyz");
+		await expect(response.json<{ error: boolean }>()).resolves.toEqual({
+			error: true,
+		});
+	});
+
+	it("throws TransportError on HTTP 500", async () => {
+		mockTlsState.queuedResponses.push({
+			status: 500,
+			body: "boom",
+			headers: { "content-type": "text/plain" },
+		});
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com");
+
+		await expect(client.fetch("/fail")).rejects.toMatchObject({
+			name: "TransportError",
+			status: 500,
+			message: "HTTP 500: boom",
+		});
+	});
+
+	it("createSession reuses the same session across fetches", async () => {
+		mockTlsState.queuedResponses.push(
+			{ status: 200, body: "first", headers: { a: "1" } },
+			{ status: 200, body: "second", headers: { a: "2" } },
+		);
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com");
+		const session = client.createSession();
+
+		await session.fetch("/one");
+		await session.fetch("/two");
+
+		expect(mockTlsState.sessions).toHaveLength(1);
+		expect(mockTlsState.sessions[0]?.getCalls).toEqual([
+			{ url: "https://example.com/one", options: { headers: undefined } },
+			{ url: "https://example.com/two", options: { headers: undefined } },
+		]);
+
+		session.close();
+		expect(mockTlsState.sessions[0]?.closed).toBe(true);
+	});
+
+	it("maps chrome-131 profile to chrome_131 for SessionClient", async () => {
+		mockTlsState.queuedResponses.push({
+			status: 200,
+			body: "ok",
+			headers: { "content-type": "text/plain" },
+		});
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com", "chrome-131");
+		const session = client.createSession();
+
+		await session.fetch("/profile");
+
+		expect(mockTlsState.sessions[0]?.options).toMatchObject({
+			tlsClientIdentifier: "chrome_131",
+		});
+	});
+
+	it("maps chrome-146 profile to chrome_146 for SessionClient", async () => {
+		mockTlsState.queuedResponses.push({
+			status: 200,
+			body: "ok",
+			headers: { "content-type": "text/plain" },
+		});
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com", "chrome-146");
+		const session = client.createSession();
+
+		await session.fetch("/profile");
+
+		expect(mockTlsState.sessions[0]?.options).toMatchObject({
+			tlsClientIdentifier: "chrome_146",
+		});
+	});
+
+	it("createSession accepts a profile override", async () => {
+		mockTlsState.queuedResponses.push({
+			status: 200,
+			body: "ok",
+			headers: { "content-type": "text/plain" },
+		});
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com", "chrome-146");
+		const session = client.createSession({ profile: "chrome-131" });
+
+		await session.fetch("/profile");
+
+		expect(mockTlsState.sessions[0]?.options).toMatchObject({
+			tlsClientIdentifier: "chrome_131",
+		});
+	});
+
+	it("uses direct JA3 and re-creates session when JA3 changes", async () => {
+		mockTlsState.queuedResponses.push({
+			status: 200,
+			body: "ok-1",
+			headers: { "content-type": "text/plain" },
+		});
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com");
+
+		await client.fetch("/ja3-a", { tls: { ja3: "custom-ja3-a" } });
+		mockTlsState.queuedResponses.push({
+			status: 200,
+			body: "ok-2",
+			headers: { "content-type": "text/plain" },
+		});
+		await client.fetch("/ja3-b", { tls: { ja3: "custom-ja3-b" } });
+
+		expect(mockTlsState.sessions).toHaveLength(2);
+		expect(mockTlsState.sessions[0]?.options).toMatchObject({
+			tlsClientIdentifier: "custom-ja3-a",
+		});
+		expect(mockTlsState.sessions[1]?.options).toMatchObject({
+			tlsClientIdentifier: "custom-ja3-b",
+		});
+	});
+
+	it("passes headerOrder through to TLS request options", async () => {
+		mockTlsState.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("/headers", {
+			headers: { accept: "text/plain" },
+			headerOrder: ["content-type", "user-agent"],
+		});
+
+		expect(mockTlsState.sessions[0]?.getCalls[0]?.options).toMatchObject({
+			headers: { accept: "text/plain" },
+			headerOrder: ["content-type", "user-agent"],
+		});
+	});
+
+	it("resolves profile identifiers via stealth profiles before heuristic fallback", async () => {
+		mockTlsState.queuedResponses.push({
+			status: 200,
+			body: "ok",
+			headers: { "content-type": "text/plain" },
+		});
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com", "ios-safari-26");
+		const session = client.createSession();
+
+		await session.fetch("/profile");
+
+		expect(mockTlsState.sessions[0]?.options).toMatchObject({
+			tlsClientIdentifier: "safari_ios_26_0",
+		});
+	});
+
+	it("wraps network failures in TransportError", async () => {
+		mockTlsState.queuedErrors.push(new Error("socket hang up"));
+
+		const { createTlsClient } = await import("../runtime/tls");
+		const client = createTlsClient("https://example.com");
+
+		await expect(client.fetch("/network")).rejects.toBeInstanceOf(
+			TransportError,
+		);
+		await expect(client.fetch("/network")).rejects.toMatchObject({
+			status: 0,
+			message: "Network error: Error: socket hang up",
+		});
+	});
+});

package/src/__tests__/types.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import type {
+	AuthMode,
+	BrowserEngine,
+	ConnectorContext,
+	ConnectorDefinition,
+	ConnectorMeta,
+	CookieJar,
+	StealthPlatform,
+	StealthProfile,
+	TlsFetchOptions,
+	TlsResponse,
+} from "../types";
+
+describe("ConnectorDefinition types", () => {
+	it("should allow valid connector meta", () => {
+		const meta = {
+			displayName: "CoinGecko Prices",
+			description: "Simple finance connector",
+			category: "finance",
+			tags: ["prices"],
+			icon: "./icon.png",
+		} satisfies ConnectorMeta;
+
+		expect(meta.displayName).toBe("CoinGecko Prices");
+		expect(meta.category).toBe("finance");
+	});
+
+	it("should enforce id format via pattern test", () => {
+		const validId = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)+$/.test(
+			"coingecko-prices",
+		);
+		expect(validId).toBe(true);
+
+		const invalidId = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)+$/.test("CoinGecko");
+		expect(invalidId).toBe(false);
+	});
+
+	it("should support all auth modes", () => {
+		const modes = [
+			"none",
+			"credentials",
+			"oauth2",
+			"api-key",
+		] as const satisfies readonly AuthMode[];
+		expect(modes).toContain("none");
+		expect(modes).toContain("credentials");
+	});
+
+	it("should type a complete connector definition", () => {
+		const definition = {
+			id: "coingecko-prices",
+			version: "1.0.0",
+			runtime: "standard" as const,
+			stealth: {
+				profile: "chrome-131",
+				platform: "macos" as StealthPlatform,
+			},
+			proxy: true,
+			browser: {
+				engine: "nodriver" as BrowserEngine,
+			},
+			meta: {
+				displayName: "CoinGecko Prices",
+				description: "Connector description",
+				category: "finance",
+				tags: ["prices"],
+				icon: "./icon.png",
+			},
+			operations: {
+				search: {
+					description: "Search prices",
+					input: z.object({ query: z.string() }),
+					output: z.object({ results: z.array(z.string()) }),
+					handler: async (_ctx: ConnectorContext, input: unknown) => {
+						const parsed = z.object({ query: z.string() }).parse(input);
+
+						return {
+							results: [parsed.query],
+						};
+					},
+					fixtures: {
+						request: { query: "bitcoin" },
+						response: { results: ["bitcoin"] },
+					},
+					hints: {
+						query: "Coin symbol or asset name",
+					},
+				},
+			},
+		} satisfies ConnectorDefinition;
+
+		expect(definition.id).toBe("coingecko-prices");
+		expect(definition.operations.search.description).toBe("Search prices");
+	});
+
+	it("should type stealth profiles", () => {
+		const stealthProfile = {
+			name: "chrome-131-macos",
+			platform: "macos",
+			version: "131",
+			userAgent: "Mozilla/5.0",
+			headerOrder: ["Host", "User-Agent"],
+		} satisfies StealthProfile;
+
+		expect(stealthProfile.platform).toBe("macos");
+	});
+
+	it("should type TLS fetch options and response extensions", async () => {
+		const cookies: CookieJar = {
+			get: (name) => (name === "sid" ? "abc" : undefined),
+			getAll: () => ({ sid: "abc" }),
+			toString: () => "sid=abc",
+		};
+
+		const options = {
+			profile: "chrome-131",
+			headerOrder: ["host", "user-agent"],
+			tls: {
+				ja3: "771,4865-4866",
+				h2: { HEADER_TABLE_SIZE: 65536 },
+			},
+		} satisfies TlsFetchOptions;
+
+		const response: TlsResponse = {
+			status: 200,
+			ok: true,
+			headers: { "content-type": "application/json" },
+			rawHeaders: [["content-type", "application/json"]],
+			body: '{"ok":true}',
+			cookies,
+			json: async <T>() => JSON.parse('{"ok":true}') as T,
+		};
+
+		expect(options.tls?.ja3).toBe("771,4865-4866");
+		expect(response.cookies.get("sid")).toBe("abc");
+		await expect(response.json<{ ok: boolean }>()).resolves.toEqual({
+			ok: true,
+		});
+	});
+});

package/src/__tests__/utils.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+	checkResultCode,
+	isEmptyResult,
+	nullIfPlaceholder,
+	unwrapGovEnvelope,
+} from "../recipes/gov-api";
+import { toISODate } from "../utils/date";
+import { pivotByField, unwrapEnvelope } from "../utils/parse";
+import { stripHtml, truncate } from "../utils/text";
+import { toBoolean, toFloat, toInt, toNumber } from "../utils/transform";
+
+describe("transform utils", () => {
+	it("parses numbers and booleans", () => {
+		expect(toNumber("1.5")).toBe(1.5);
+		expect(toFloat("1.25", 1)).toBe(1.3);
+		expect(toInt("38.7")).toBe(39);
+		expect(toBoolean("true")).toBe(true);
+		expect(toBoolean(0)).toBe(false);
+	});
+});
+
+describe("date utils", () => {
+	it("formats dates with timezone", () => {
+		expect(toISODate("20230101", "Asia/Seoul")).toBe(
+			"2023-01-01T00:00:00+09:00",
+		);
+	});
+});
+
+describe("text utils", () => {
+	it("strips html and truncates text", () => {
+		expect(stripHtml("<b>hello</b>")).toBe("hello");
+		expect(truncate("hello world", 5)).toBe("hello...");
+	});
+});
+
+describe("parse utils", () => {
+	it("unwraps envelopes and pivots arrays", () => {
+		expect(unwrapEnvelope({ a: { b: 1 } }, "a.b")).toBe(1);
+		expect(pivotByField([{ k: "A", v: 1 }], "k", "v")).toEqual({ A: 1 });
+	});
+});
+
+describe("gov-api recipe", () => {
+	it("checks result code and placeholder values", () => {
+		expect(checkResultCode({ resultCode: "00" })).toBe(true);
+		expect(nullIfPlaceholder("-", ["-"])).toBeNull();
+	});
+
+	it("unwraps gov envelope and detects empty results", () => {
+		expect(
+			unwrapGovEnvelope({
+				response: { body: { items: { item: [{ id: 1 }] } } },
+			}),
+		).toEqual([{ id: 1 }]);
+		expect(isEmptyResult({ response: { header: { resultCode: "03" } } })).toBe(
+			true,
+		);
+	});
+});