@apifuse/connector-sdk 2.0.0-beta.1

package/src/__tests__/http.test.ts

@@ -0,0 +1,238 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+
+import { TransportError } from "../errors";
+import { createHttpClient } from "../runtime/http";
+import { getStealthProfile } from "../stealth/profiles";
+
+describe("createHttpClient", () => {
+	let originalFetch: typeof fetch;
+
+	beforeEach(() => {
+		originalFetch = global.fetch;
+	});
+
+	afterEach(() => {
+		global.fetch = originalFetch;
+	});
+
+	it("get() returns HttpResponse with plain response fields", async () => {
+		global.fetch = (async () =>
+			new Response(JSON.stringify({ args: { q: "1" } }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			})) as unknown as typeof fetch;
+
+		const http = createHttpClient();
+		const result = await http.get("https://httpbin.org/get", {
+			params: { q: "1" },
+		});
+
+		expect(result.status).toBe(200);
+		expect(result.ok).toBeTrue();
+		expect(result.headers["content-type"]).toBe("application/json");
+		expect(result.data).toEqual({ args: { q: "1" } });
+		expect(await result.json<{ args: { q: string } }>()).toEqual({
+			args: { q: "1" },
+		});
+		expect(await result.text()).toBe(JSON.stringify({ args: { q: "1" } }));
+	});
+
+	it("post() sends body and returns response", async () => {
+		let capturedBody: string | null = null;
+
+		global.fetch = (async (_url, init) => {
+			capturedBody = init?.body as string;
+			return new Response(JSON.stringify({ json: { key: "value" } }), {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}) as typeof fetch;
+
+		const http = createHttpClient();
+		const result = await http.post("https://httpbin.org/post", {
+			key: "value",
+		});
+
+		if (capturedBody === null) {
+			throw new Error("Expected request body to be captured");
+		}
+
+		expect(capturedBody === JSON.stringify({ key: "value" })).toBe(true);
+		expect(result.data).toEqual({ json: { key: "value" } });
+		expect(await result.text()).toBe(
+			JSON.stringify({ json: { key: "value" } }),
+		);
+	});
+
+	it("throws TransportError on 4xx", async () => {
+		global.fetch = (async () =>
+			new Response("Not Found", { status: 404 })) as unknown as typeof fetch;
+
+		const http = createHttpClient();
+
+		await expect(http.get("https://example.com/not-found")).rejects.toThrow(
+			TransportError,
+		);
+	});
+
+	it("TransportError has status code", async () => {
+		global.fetch = (async () =>
+			new Response("Server Error", { status: 500 })) as unknown as typeof fetch;
+
+		const http = createHttpClient();
+
+		try {
+			await http.get("https://example.com/error");
+		} catch (error) {
+			expect(error instanceof TransportError).toBe(true);
+			expect((error as TransportError).status).toBe(500);
+		}
+	});
+
+	it("throws TransportError on network error", async () => {
+		global.fetch = (async () => {
+			throw new Error("Network error");
+		}) as unknown as typeof fetch;
+
+		const http = createHttpClient();
+
+		await expect(http.get("https://example.com")).rejects.toThrow(
+			TransportError,
+		);
+	});
+
+	it("put() sends body with PUT method", async () => {
+		let capturedMethod: string | undefined;
+
+		global.fetch = (async (_url, init) => {
+			capturedMethod = init?.method;
+			return new Response("{}", {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}) as typeof fetch;
+
+		const http = createHttpClient();
+
+		await http.put("https://example.com/resource", { data: "updated" });
+		expect(capturedMethod).toBe("PUT");
+	});
+
+	it("delete() sends DELETE method", async () => {
+		let capturedMethod: string | undefined;
+
+		global.fetch = (async (_url, init) => {
+			capturedMethod = init?.method;
+			return new Response("{}", {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}) as typeof fetch;
+
+		const http = createHttpClient();
+
+		await http.delete("https://example.com/resource");
+		expect(capturedMethod).toBe("DELETE");
+	});
+
+	it("request() uses GET by default and supports custom methods", async () => {
+		const capturedMethods: string[] = [];
+
+		global.fetch = (async (_url, init) => {
+			capturedMethods.push(String(init?.method));
+			return new Response("{}", {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}) as typeof fetch;
+
+		const http = createHttpClient();
+
+		await http.request("https://example.com/default");
+		await http.request("https://example.com/custom", { method: "PATCH" });
+
+		expect(capturedMethods).toEqual(["GET", "PATCH"]);
+	});
+
+	it("injects Layer 2 headers from a Chromium stealth profile", async () => {
+		let capturedHeaders: HeadersInit | undefined;
+
+		global.fetch = (async (_url, init) => {
+			capturedHeaders = init?.headers;
+			return new Response("{}", {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}) as typeof fetch;
+
+		const http = createHttpClient("https://example.com", {
+			stealthProfile: getStealthProfile("chrome-131"),
+		});
+
+		await http.get("/resource");
+
+		expect(capturedHeaders).toMatchObject({
+			"Accept-Language": "ko-KR,ko;q=0.9,en-US;q=0.8",
+			"Sec-Ch-Ua":
+				'"Chromium";v="131", "Google Chrome";v="131", "Not)A;Brand";v="99"',
+			"Sec-Ch-Ua-Mobile": "?0",
+			"Sec-Ch-Ua-Platform": '"macOS"',
+			"User-Agent": getStealthProfile("chrome-131").userAgent,
+		});
+	});
+
+	it("allows caller headers to override auto-injected Layer 2 headers", async () => {
+		let capturedHeaders: HeadersInit | undefined;
+
+		global.fetch = (async (_url, init) => {
+			capturedHeaders = init?.headers;
+			return new Response("{}", {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}) as typeof fetch;
+
+		const http = createHttpClient("https://example.com", {
+			stealthProfile: getStealthProfile("edge-131"),
+		});
+
+		await http.get("/resource", {
+			headers: {
+				"Accept-Language": "en-US",
+				"Sec-Ch-Ua": "custom-brand",
+			},
+		});
+
+		expect(capturedHeaders).toMatchObject({
+			"Accept-Language": "en-US",
+			"Sec-Ch-Ua": "custom-brand",
+			"Sec-Ch-Ua-Mobile": "?0",
+			"Sec-Ch-Ua-Platform": '"Windows"',
+		});
+	});
+
+	it("omits Sec-Ch-Ua headers for Firefox while keeping Accept-Language", async () => {
+		let capturedHeaders: Record<string, string> | undefined;
+
+		global.fetch = (async (_url, init) => {
+			capturedHeaders = init?.headers as Record<string, string>;
+			return new Response("{}", {
+				status: 200,
+				headers: { "Content-Type": "application/json" },
+			});
+		}) as typeof fetch;
+
+		const http = createHttpClient("https://example.com", {
+			stealthProfile: getStealthProfile("firefox-133"),
+		});
+
+		await http.get("/resource");
+
+		expect(capturedHeaders?.["Accept-Language"]).toBe(
+			"ko-KR,ko;q=0.9,en-US;q=0.8",
+		);
+		expect(capturedHeaders?.["Sec-Ch-Ua"]).toBeUndefined();
+		expect(capturedHeaders?.["Sec-Ch-Ua-Platform"]).toBeUndefined();
+		expect(capturedHeaders?.["Sec-Ch-Ua-Mobile"]).toBeUndefined();
+	});
+});

package/src/__tests__/insights.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+	generateInsights,
+	type Insight,
+	type InsightSeverity,
+} from "../runtime/insights";
+import type { Span } from "../runtime/trace";
+
+function makeSpan(
+	name: string,
+	overrides: Partial<Span> = {},
+	attributes: Span["attributes"] = {},
+): Span {
+	const duration_ms = overrides.duration_ms ?? 10;
+	return {
+		id: overrides.id ?? crypto.randomUUID(),
+		name,
+		startedAt: overrides.startedAt ?? 1_000,
+		endedAt: overrides.endedAt ?? 1_000 + duration_ms,
+		duration_ms,
+		status: overrides.status ?? "ok",
+		attributes: overrides.attributes ?? attributes,
+		...(overrides.parentId ? { parentId: overrides.parentId } : {}),
+		...(overrides.error ? { error: overrides.error } : {}),
+	};
+}
+
+function findInsight(insights: Insight[], id: string): Insight {
+	const insight = insights.find((item) => item.id === id);
+	if (!insight) {
+		throw new Error(`Missing insight: ${id}`);
+	}
+
+	return insight;
+}
+
+function expectSeverity(
+	insights: Insight[],
+	id: string,
+	severity: InsightSeverity,
+): Insight {
+	const insight = findInsight(insights, id);
+	expect(insight.severity).toBe(severity);
+	return insight;
+}
+
+describe("generateInsights", () => {
+	it("returns empty array for empty spans", () => {
+		expect(generateInsights([])).toEqual([]);
+	});
+
+	it("detects TLS reuse failure when less than 20% are reused", () => {
+		const spans: Span[] = [
+			makeSpan("tls.fetch", {}, { connection_reused: false }),
+			makeSpan("tls.fetch", {}, { connection_reused: false }),
+			makeSpan("tls.fetch", {}, { connection_reused: false }),
+			makeSpan("tls.fetch", {}, { connection_reused: false }),
+			makeSpan("tls.fetch", {}, { connection_reused: true }),
+		];
+
+		const insight = expectSeverity(
+			generateInsights(spans),
+			"tls_reuse_failure",
+			"warning",
+		);
+
+		expect(insight.message).toContain("TLS connection reuse");
+		expect(insight.fix).toContain("ctx.tls.createSession");
+	});
+
+	it("marks TLS reuse as OK when at least 80% are reused", () => {
+		const spans: Span[] = [
+			makeSpan("tls.fetch", {}, { connection_reused: true }),
+			makeSpan("tls.fetch", {}, { connection_reused: true }),
+			makeSpan("tls.fetch", {}, { connection_reused: true }),
+			makeSpan("tls.fetch", {}, { connection_reused: true }),
+			makeSpan("tls.fetch", {}, { connection_reused: false }),
+		];
+
+		const insight = expectSeverity(
+			generateInsights(spans),
+			"tls_reuse_failure",
+			"info",
+		);
+
+		expect(insight.message.startsWith("✓")).toBe(true);
+		expect(insight.message).toContain("80%");
+	});
+
+	it("detects slow transform spans by p95", () => {
+		const spans: Span[] = [
+			makeSpan("transformResponse", { duration_ms: 5 }),
+			makeSpan("transformResponse", { duration_ms: 8 }),
+			makeSpan("transformResponse", { duration_ms: 20 }),
+			makeSpan("transformResponse", { duration_ms: 25 }),
+		];
+
+		const insight = expectSeverity(
+			generateInsights(spans),
+			"slow_transform",
+			"warning",
+		);
+
+		expect(insight.message).toContain("p95");
+		expect(insight.fix).toContain("transformResponse");
+	});
+
+	it("detects large responses over 100KB", () => {
+		const spans: Span[] = [
+			makeSpan("tls.fetch", {}, { response_size: 120_000 }),
+			makeSpan("http.get", {}, { response_size: 5_000 }),
+		];
+
+		const insight = expectSeverity(
+			generateInsights(spans),
+			"large_response",
+			"warning",
+		);
+
+		expect(insight.message).toContain("Response size");
+		expect(insight.fix).toContain("limit");
+	});
+
+	it("detects repeated DNS latency for the same host without reuse", () => {
+		const spans: Span[] = [
+			makeSpan(
+				"tls.fetch",
+				{},
+				{
+					url: "https://api.example.com/a",
+					dns_ms: 8,
+					connection_reused: false,
+				},
+			),
+			makeSpan(
+				"tls.fetch",
+				{},
+				{
+					url: "https://api.example.com/b",
+					dns_ms: 12,
+					connection_reused: false,
+				},
+			),
+		];
+
+		const insight = expectSeverity(
+			generateInsights(spans),
+			"dns_repeated",
+			"warning",
+		);
+
+		expect(insight.message).toContain("api.example.com");
+		expect(insight.fix).toContain("DNS");
+	});
+
+	it("detects proxy overhead when proxied requests are twice as slow", () => {
+		const spans: Span[] = [
+			makeSpan("tls.fetch", { duration_ms: 100 }, { proxy: false }),
+			makeSpan("tls.fetch", { duration_ms: 120 }, { proxy: false }),
+			makeSpan("tls.fetch", { duration_ms: 250 }, { proxy: true }),
+			makeSpan("tls.fetch", { duration_ms: 260 }, { proxy: true }),
+		];
+
+		const insight = expectSeverity(
+			generateInsights(spans),
+			"proxy_overhead",
+			"warning",
+		);
+
+		expect(insight.message).toContain("with proxy");
+		expect(insight.fix).toContain("proxy");
+	});
+
+	it("detects browser idle waits over five seconds", () => {
+		const spans: Span[] = [
+			makeSpan("page.waitForSelector", {}, { wait_ms: 6_200 }),
+			makeSpan("page.click", { duration_ms: 20 }),
+		];
+
+		const insight = expectSeverity(
+			generateInsights(spans),
+			"browser_idle",
+			"warning",
+		);
+
+		expect(insight.message).toContain("6200ms");
+		expect(insight.fix).toContain("waitForSelector");
+	});
+
+	it("detects frequent session refreshes", () => {
+		const spans: Span[] = [
+			makeSpan("tls.fetch"),
+			makeSpan("tls.fetch"),
+			makeSpan("tls.fetch"),
+			makeSpan("tls.fetch"),
+			makeSpan("tls.fetch"),
+			makeSpan("auth.refresh"),
+		];
+
+		const insight = expectSeverity(
+			generateInsights(spans),
+			"session_expiry_frequent",
+			"warning",
+		);
+
+		expect(insight.message).toContain("20%");
+		expect(insight.fix).toContain("ttl");
+	});
+});