@apifuse/provider-sdk 2.0.0-beta.1 → 2.1.0-beta.0

package/src/stealth/profiles.ts

@@ -158,6 +158,10 @@ export function generateLayer2Headers(
 	return headers;
 }
 
+const STEALTH_PROFILE_ALIASES: Record<string, string> = {
+	"chrome-desktop": "chrome-146",
+};
+
 const STEALTH_PROFILES: Record<string, StealthProfile> = {
 	"chrome-146": createProfile("chrome-146", {
 		platform: "macos",
@@ -169,87 +173,6 @@ const STEALTH_PROFILES: Record<string, StealthProfile> = {
 		h2Settings: CHROMIUM_H2_SETTINGS,
 		headerOrder: CHROMIUM_HEADER_ORDER,
 	}),
-	"chrome-144": createProfile("chrome-144", {
-		platform: "macos",
-		version: "144.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0 Safari/537.36",
-		tlsClientIdentifier: "chrome_144",
-		ja3: CHROMIUM_JA3,
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
-	"chrome-133": createProfile("chrome-133", {
-		platform: "macos",
-		version: "133.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
-		tlsClientIdentifier: "chrome_133",
-		ja3: CHROMIUM_JA3,
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
-	"chrome-131": createProfile("chrome-131", {
-		platform: "macos",
-		version: "131.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
-		tlsClientIdentifier: "chrome_131",
-		ja3: CHROMIUM_JA3,
-		ja4: "t13d1516h2_8daaf6152771_02713d6af862",
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
-	"chrome-124": createProfile("chrome-124", {
-		platform: "macos",
-		version: "124.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
-		tlsClientIdentifier: "chrome_124",
-		ja3: CHROMIUM_JA3,
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
-	"chrome-120": createProfile("chrome-120", {
-		platform: "macos",
-		version: "120.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
-		tlsClientIdentifier: "chrome_120",
-		ja3: CHROMIUM_JA3,
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
-	"chrome-146-psk": createProfile("chrome-146-psk", {
-		platform: "macos",
-		version: "146.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
-		tlsClientIdentifier: "chrome_146_PSK",
-		ja3: CHROMIUM_JA3,
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
-	"chrome-131-psk": createProfile("chrome-131-psk", {
-		platform: "macos",
-		version: "131.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36",
-		tlsClientIdentifier: "chrome_131_PSK",
-		ja3: CHROMIUM_JA3,
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
-	"chrome-130-psk": createProfile("chrome-130-psk", {
-		platform: "macos",
-		version: "130.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36",
-		tlsClientIdentifier: "chrome_130_PSK",
-		ja3: CHROMIUM_JA3,
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
 	"firefox-147": createProfile("firefox-147", {
 		platform: "macos",
 		version: "147.0",
@@ -310,16 +233,6 @@ const STEALTH_PROFILES: Record<string, StealthProfile> = {
 		h2Settings: SAFARI_H2_SETTINGS,
 		headerOrder: SAFARI_HEADER_ORDER,
 	}),
-	"edge-131": createProfile("edge-131", {
-		platform: "windows",
-		version: "131.0.0.0",
-		userAgent:
-			"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0",
-		tlsClientIdentifier: "chrome_131",
-		ja3: CHROMIUM_JA3,
-		h2Settings: CHROMIUM_H2_SETTINGS,
-		headerOrder: CHROMIUM_HEADER_ORDER,
-	}),
 	"ios-safari-26": createProfile("ios-safari-26", {
 		platform: "ios",
 		version: "26.0",
@@ -373,7 +286,8 @@ const STEALTH_PROFILES: Record<string, StealthProfile> = {
 };
 
 export function getStealthProfile(name: string): StealthProfile {
-	const profile = STEALTH_PROFILES[name];
+	const canonicalName = STEALTH_PROFILE_ALIASES[name] ?? name;
+	const profile = STEALTH_PROFILES[canonicalName];
 
 	if (!profile) {
 		throw new SDKError(`Unknown stealth profile: ${name}`);
@@ -387,5 +301,8 @@ export function getStealthProfile(name: string): StealthProfile {
 }
 
 export function listStealthProfiles(): string[] {
-	return Object.keys(STEALTH_PROFILES);
+	return [
+		...Object.keys(STEALTH_PROFILES),
+		...Object.keys(STEALTH_PROFILE_ALIASES),
+	];
 }

package/src/testing/run.ts

@@ -1,20 +1,270 @@
 import { describe, expect, it } from "bun:test";
 
-import type { ProviderDefinition } from "../types";
+import { safeParseSchemaSync } from "../schema";
+import type {
+	AuthMode,
+	CredentialContext,
+	HttpResponse,
+	ProviderContext,
+	ProviderDefinition,
+} from "../types";
 
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)+$/;
+const VALID_AUTH_MODES = [
+	"none",
+	"platform-managed",
+	"credentials",
+	"oauth2",
+] as const;
+const UPDATE_SNAPSHOT_ARGS = new Set(["-u", "--update-snapshots"]);
 
-type ProviderManifest = {
-	id?: unknown;
-	displayName?: unknown;
-	category?: unknown;
-	version?: unknown;
-	sdkVersion?: unknown;
-	runtime?: unknown;
-	auth?: unknown;
-	stealthProfile?: unknown;
-	language?: unknown;
-};
+export interface StandardTestsManifest {
+	id?: string;
+	displayName?: string;
+	category?: string;
+	version?: string;
+	runtime?: ProviderDefinition["runtime"];
+	sdkVersion?: number;
+	auth?: AuthMode;
+	language?: string;
+	signature?: string;
+	signatureUri?: string;
+}
+
+export interface StandardTestsOptions {
+	/** Validate operation request/response fixtures and JSON raw fixture shape. */
+	validateFixture?: boolean;
+	/** Write/read __fixtures__/transform.snap.json for handler(raw fixture) output. */
+	snapshot?: boolean;
+	/** Opt-in integration-only manifest signature assertion. */
+	verifyManifest?: boolean;
+	/** Opt-in auth mode/operation consistency assertion. */
+	validateAuthMode?: boolean;
+	/** Override inferred __fixtures__ directory for tests generated outside providers/<id>. */
+	fixtureDir?: string;
+}
+
+interface FixtureEnvelope {
+	request?: unknown;
+	response?: unknown;
+}
+
+function isFixtureEnvelope(value: unknown): value is FixtureEnvelope {
+	return (
+		value !== null &&
+		typeof value === "object" &&
+		!Array.isArray(value) &&
+		("request" in value || "response" in value)
+	);
+}
+
+function isJsonCompatible(value: unknown): boolean {
+	if (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean"
+	) {
+		return Number.isFinite(value) || typeof value !== "number";
+	}
+
+	if (Array.isArray(value)) {
+		return value.every(isJsonCompatible);
+	}
+
+	if (typeof value === "object" && value !== null) {
+		return Object.values(value).every(isJsonCompatible);
+	}
+
+	return false;
+}
+
+function sortJson(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map(sortJson);
+	}
+
+	if (value !== null && typeof value === "object") {
+		return Object.fromEntries(
+			Object.entries(value)
+				.sort(([left], [right]) => left.localeCompare(right))
+				.map(([key, entry]) => [key, sortJson(entry)]),
+		);
+	}
+
+	return value;
+}
+
+function stableStringify(value: unknown): string {
+	return `${JSON.stringify(sortJson(value), null, 2)}\n`;
+}
+
+function shouldUpdateSnapshots(): boolean {
+	return process.argv.some((arg) => UPDATE_SNAPSHOT_ARGS.has(arg));
+}
+
+function inferFixtureDir(providerId: string): string {
+	const stack = new Error().stack ?? "";
+	const testFile = stack
+		.split("\n")
+		.map((line) => line.match(/\(?((?:file:\/\/)?[^():]+\.test\.ts)/)?.[1])
+		.find((file) => file !== undefined);
+
+	if (testFile) {
+		const pathname = testFile.startsWith("file://")
+			? new URL(testFile).pathname
+			: testFile;
+		return `${pathname.replace(/\/[^/]+$/, "")}/../__fixtures__`;
+	}
+
+	return `providers/${providerId}/__fixtures__`;
+}
+
+function jsonResponse(data: unknown): HttpResponse {
+	return {
+		status: 200,
+		ok: true,
+		headers: {},
+		data,
+		json: async <_T = unknown>() => JSON.parse(JSON.stringify(data)),
+		text: async () => JSON.stringify(data),
+	};
+}
+
+function unsupported(name: string): never {
+	throw new Error(`Standard test snapshot context does not support ${name}`);
+}
+
+function createSnapshotContext(rawFixture: unknown): ProviderContext {
+	const credential: CredentialContext = {
+		mode: "none",
+		get: () => undefined,
+		getAll: () => ({}),
+		getAccessToken: () => undefined,
+		getScopes: () => [],
+	};
+
+	return {
+		env: { get: () => undefined },
+		credential,
+		request: { headers: {} },
+		http: {
+			request: async () => jsonResponse(rawFixture),
+			get: async () => jsonResponse(rawFixture),
+			post: async () => jsonResponse(rawFixture),
+			put: async () => jsonResponse(rawFixture),
+			delete: async () => jsonResponse(rawFixture),
+		},
+		tls: {
+			fetch: async () => unsupported("ctx.tls.fetch"),
+			createSession: () => unsupported("ctx.tls.createSession"),
+		},
+		browser: {
+			engine: "playwright-stealth",
+			newPage: async () => unsupported("ctx.browser.newPage"),
+		},
+		trace: {
+			span: async (_name, fn) => fn(),
+		},
+		auth: {
+			requestField: async (name) =>
+				unsupported(`ctx.auth.requestField(${name})`),
+		},
+	};
+}
+
+async function transformSnapshotOutput(
+	provider: ProviderDefinition,
+	rawFixture: unknown,
+): Promise<unknown> {
+	const entries = Object.entries(provider.operations);
+	const context = createSnapshotContext(rawFixture);
+	const outputs = await Promise.all(
+		entries.map(async ([operationName, operation]) => {
+			const request = operation.fixtures?.request ?? {};
+			const output = await operation.handler(context, request);
+			return [operationName, output] as const;
+		}),
+	);
+
+	if (outputs.length === 1) {
+		return outputs[0]?.[1];
+	}
+
+	return Object.fromEntries(outputs);
+}
+
+function formatJson(value: unknown): string {
+	return JSON.stringify(value, null, 2);
+}
+
+function formatJsonDiff(current: unknown, expected: unknown): string {
+	const currentLines = formatJson(current).split("\n");
+	const expectedLines = formatJson(expected).split("\n");
+	const lineCount = Math.max(currentLines.length, expectedLines.length);
+	const lines = ["JSON diff (- current, + expected):"];
+
+	for (let index = 0; index < lineCount; index += 1) {
+		const currentLine = currentLines[index];
+		const expectedLine = expectedLines[index];
+
+		if (currentLine === expectedLine) {
+			if (currentLine !== undefined) {
+				lines.push(`  ${currentLine}`);
+			}
+			continue;
+		}
+
+		if (currentLine !== undefined) {
+			lines.push(`- ${currentLine}`);
+		}
+		if (expectedLine !== undefined) {
+			lines.push(`+ ${expectedLine}`);
+		}
+	}
+
+	return lines.join("\n");
+}
+
+function expectSchemaFixture(
+	operationName: string,
+	fieldName: "request" | "response",
+	fixture: unknown,
+	result: ReturnType<typeof safeParseSchemaSync>,
+): void {
+	if (result.success) {
+		expect(result.success).toBe(true);
+		return;
+	}
+
+	throw new Error(
+		[
+			`Fixture ${operationName}.${fieldName} failed schema validation.`,
+			formatJsonDiff(
+				{ valid: false, value: fixture, error: result.error },
+				{ valid: true, value: fixture },
+			),
+		].join("\n"),
+	);
+}
+
+function parseSchemaFixture(
+	operationName: string,
+	fieldName: "request" | "response",
+	schema: ProviderDefinition["operations"][string]["input"],
+	fixture: unknown,
+): void {
+	expectSchemaFixture(
+		operationName,
+		fieldName,
+		fixture,
+		safeParseSchemaSync(
+			schema,
+			fixture,
+			`operations.${operationName}.fixtures.${fieldName}`,
+		),
+	);
+}
 
 /**
  * Run standard SDK tests for a provider in one line.
@@ -22,15 +272,84 @@ type ProviderManifest = {
  * Usage:
  * import { myProvider } from "../index";
  * import { runStandardTests } from "@apifuse/provider-sdk/testing";
- * runStandardTests(myProvider);
+ * runStandardTests(myProvider, rawFixture, manifest, { snapshot: true });
  */
 export function runStandardTests(
 	provider: ProviderDefinition,
-	_rawFixture?: unknown,
-	manifest?: ProviderManifest,
+	rawFixture?: unknown,
+	manifest?: StandardTestsManifest,
+	options: StandardTestsOptions = {},
 ): void {
 	const operations = Object.entries(provider.operations);
 
+	const assertFixtureValidation = (): void => {
+		expect(rawFixture).toBeDefined();
+		expect(isJsonCompatible(rawFixture)).toBe(true);
+
+		for (const [operationName, op] of operations) {
+			if (op.fixtures?.request !== undefined) {
+				parseSchemaFixture(
+					operationName,
+					"request",
+					op.input,
+					op.fixtures.request,
+				);
+			}
+
+			if (op.fixtures?.response !== undefined) {
+				parseSchemaFixture(
+					operationName,
+					"response",
+					op.output,
+					op.fixtures.response,
+				);
+			}
+
+			if (isFixtureEnvelope(rawFixture)) {
+				if (rawFixture.request !== undefined) {
+					parseSchemaFixture(
+						operationName,
+						"request",
+						op.input,
+						rawFixture.request,
+					);
+				}
+
+				if (rawFixture.response !== undefined) {
+					parseSchemaFixture(
+						operationName,
+						"response",
+						op.output,
+						rawFixture.response,
+					);
+				}
+			}
+		}
+	};
+
+	const assertManifestSignature = (): void => {
+		expect(manifest).toBeDefined();
+		expect(Boolean(manifest?.signature ?? manifest?.signatureUri)).toBe(true);
+	};
+
+	const assertAuthModeContract = (): void => {
+		const authMode = provider.auth?.mode ?? "none";
+		expect(VALID_AUTH_MODES).toContain(authMode);
+
+		if (manifest?.auth !== undefined) {
+			expect(manifest.auth).toBe(authMode);
+		}
+
+		if (authMode === "credentials" || authMode === "oauth2") {
+			expect(provider.auth?.flow).toBeTruthy();
+			expect(Object.keys(provider.operations).length).toBeGreaterThan(0);
+			expect(provider.credential?.keys.length ?? 0).toBeGreaterThan(0);
+			return;
+		}
+
+		expect(provider.credential?.keys ?? []).toHaveLength(0);
+	};
+
 	describe(`[SDK Standard Tests] ${provider.id}`, () => {
 		it("id follows kebab-case format", () => {
 			expect(CONNECTOR_ID_REGEX.test(provider.id)).toBe(true);
@@ -40,7 +359,7 @@ export function runStandardTests(
 			expect(provider.meta.displayName).toBeTruthy();
 			expect(provider.meta.category).toBeTruthy();
 			expect(provider.version).toBeTruthy();
-			expect(["standard", "browser"]).toContain(provider.runtime);
+			expect(["standard", "shared", "browser"]).toContain(provider.runtime);
 		});
 
 		it("has at least one operation", () => {
@@ -58,31 +377,71 @@ export function runStandardTests(
 		it("operation schemas can parse fixture data", () => {
 			for (const [operationName, op] of operations) {
 				if (op.fixtures?.request !== undefined && op.input) {
-					const requestResult = op.input.safeParse(op.fixtures.request);
-					expect(requestResult.success).toBe(true);
+					parseSchemaFixture(
+						operationName,
+						"request",
+						op.input,
+						op.fixtures.request,
+					);
 				}
 
 				if (op.fixtures?.response !== undefined && op.output) {
-					const responseResult = op.output.safeParse(op.fixtures.response);
-					expect(responseResult.success).toBe(true);
+					parseSchemaFixture(
+						operationName,
+						"response",
+						op.output,
+						op.fixtures.response,
+					);
 				}
 
 				expect(operationName).toBeTruthy();
 			}
 		});
 
-		it("manifest matches provider metadata", () => {
-			if (!manifest) {
-				return;
-			}
-
-			expect(manifest.id).toBe(provider.id);
-			expect(manifest.displayName).toBe(provider.meta.displayName);
-			expect(manifest.category).toBe(provider.meta.category);
-			expect(manifest.version).toBe(provider.version);
-			expect(manifest.runtime).toBe(provider.runtime);
-			expect(manifest.sdkVersion).toBe(1);
-			expect(manifest.language).toBe("typescript");
+		it("provider metadata is declared in defineProvider", () => {
+			expect(provider.id).toBeTruthy();
+			expect(provider.meta.displayName).toBeTruthy();
+			expect(provider.meta.category).toBeTruthy();
+			expect(provider.version).toBeTruthy();
+			expect(VALID_AUTH_MODES).toContain(provider.auth?.mode ?? "none");
 		});
+
+		if (options.validateFixture) {
+			it("validates raw and declared operation fixtures", () => {
+				assertFixtureValidation();
+			});
+		}
+
+		if (options.verifyManifest) {
+			it("verifies manifest signature metadata", () => {
+				assertManifestSignature();
+			});
+		}
+
+		if (options.validateAuthMode) {
+			it("validates auth mode contract", () => {
+				assertAuthModeContract();
+			});
+		}
+
+		if (options.snapshot) {
+			it("matches transform snapshot", async () => {
+				expect(rawFixture).toBeDefined();
+				const fixtureDir = options.fixtureDir ?? inferFixtureDir(provider.id);
+				const snapshotPath = `${fixtureDir}/transform.snap.json`;
+				const actual = await transformSnapshotOutput(provider, rawFixture);
+				const serialized = stableStringify(actual);
+				const snapshotFile = Bun.file(snapshotPath);
+
+				if (shouldUpdateSnapshots() || !(await snapshotFile.exists())) {
+					await Bun.write(snapshotPath, serialized);
+				}
+
+				const expected: unknown = JSON.parse(
+					await Bun.file(snapshotPath).text(),
+				);
+				expect(actual).toEqual(expected);
+			});
+		}
 	});
 }