@apifuse/provider-sdk 2.1.0-beta.3 → 2.1.0-beta.4

package/bin/apifuse-perf.ts

@@ -8,8 +8,10 @@ import { pathToFileURL } from "node:url";
 
 import {
 	type ApiFuseConfig,
+	createBypassProviderCache,
 	createHttpClient,
-	createTlsClient,
+	createStealthClient,
+	createSttClientFromEnv,
 	executeOperation,
 	getProviderBaseUrl,
 	type HttpClient,
@@ -18,8 +20,8 @@ import {
 	type ProviderDefinition,
 	ProviderError,
 	type Span,
-	type TlsClient,
-	type TlsResponse,
+	type StealthClient,
+	type StealthResponse,
 	wrapWithInstrumentation,
 } from "../src";
 import {
@@ -440,12 +442,12 @@ async function loadFixtureReplay(
 }
 
 function assertProxyConfigured(config: ApiFuseConfig): void {
-	if (config.proxy?.url || process.env.APIFUSE_PROXY_URL) {
+	if (config.proxy?.url || process.env.APIFUSE__PROXY__URL) {
 		return;
 	}
 
 	throw new Error(
-		"--compare-proxy requires a proxy URL in apifuse.config.ts or APIFUSE_PROXY_URL.",
+		"--compare-proxy requires a proxy URL in apifuse.config.ts or APIFUSE__PROXY__URL.",
 	);
 }
 
@@ -637,10 +639,10 @@ function createBaseContext(options: {
 					apifuseConfig,
 					upstream,
 				});
-	const tls =
+	const stealth =
 		options.forceFixtureReplay && options.fixtureReplay
-			? createFixtureTlsClient(options.fixtureReplay.rawText)
-			: createTlsClient(getProviderBaseUrl(options.provider), {
+			? createFixtureStealthClient(options.fixtureReplay.rawText)
+			: createStealthClient(getProviderBaseUrl(options.provider), {
 					apifuseConfig,
 					upstream,
 				});
@@ -657,10 +659,12 @@ function createBaseContext(options: {
 			getScopes: () => [],
 		},
 		http,
-		tls,
+		cache: createBypassProviderCache({ providerId: options.provider.id }),
+		stealth,
 		browser: createBrowserStub(),
 		trace: options.traceContext,
 		auth: createAuthStub(),
+		stt: createSttClientFromEnv(options.provider.stt),
 	};
 }
 
@@ -695,8 +699,8 @@ function createFixtureResponse(raw: unknown) {
 	};
 }
 
-function createFixtureTlsClient(rawText: string): TlsClient {
-	const createResponse = async (): Promise<TlsResponse> => ({
+function createFixtureStealthClient(rawText: string): StealthClient {
+	const createResponse = async (): Promise<StealthResponse> => ({
 		status: 200,
 		ok: true,
 		headers: { "content-type": "application/json" },
@@ -738,7 +742,7 @@ function buildInsights(
 ): string[] {
 	const insights: string[] = [];
 	const allSpans = runs.flatMap((run) => run.spans);
-	const tlsSpans = allSpans.filter((span) => span.name === "tls.fetch");
+	const stealthSpans = allSpans.filter((span) => span.name === "stealth.fetch");
 	const dnsSpans = allSpans.filter((span) => span.name === "dns");
 	const transform = breakdown.find(
 		(entry) => entry.name === "transformResponse",
@@ -746,7 +750,7 @@ function buildInsights(
 	const responseSizes = allSpans
 		.map((span) => span.attributes.response_size)
 		.filter((value): value is number => typeof value === "number");
-	const reuseFlags = tlsSpans
+	const reuseFlags = stealthSpans
 		.map((span) => span.attributes.connection_reused)
 		.filter((value): value is boolean => typeof value === "boolean");
 
@@ -756,8 +760,8 @@ function buildInsights(
 		);
 		insights.push(
 			reusePercent >= 80
-				? `✓ TLS connection reuse: ${reusePercent}% (good)`
-				: `⚠ TLS connection reuse: ${reusePercent}% — consider session reuse`,
+				? `✓ Stealth connection reuse: ${reusePercent}% (good)`
+				: `⚠ Stealth connection reuse: ${reusePercent}% — consider session reuse`,
 		);
 	}
 

package/bin/apifuse-record.ts

@@ -7,13 +7,15 @@ import { basename, dirname, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import {
+	createBypassProviderCache,
 	createHttpClient,
-	createTlsClient,
+	createStealthClient,
+	createSttClientFromEnv,
 	executeOperation,
 	type HttpClient,
 	type ProviderContext,
 	type ProviderDefinition,
-	type TlsClient,
+	type StealthClient,
 } from "../src";
 
 type CliArgs = {
@@ -37,6 +39,7 @@ export async function main() {
 	const parsedParams = parseParams(operation, args.params);
 
 	const capture = createCaptureContext(
+		provider,
 		resolveOperationBaseUrl(provider, operationName),
 	);
 
@@ -269,15 +272,18 @@ function resolveOperationBaseUrl(
 	return baseUrl;
 }
 
-function createCaptureContext(baseUrl: string) {
+function createCaptureContext(provider: ProviderRuntime, baseUrl: string) {
 	let capturedRaw: unknown;
 
 	const http = proxyHttpClient(createHttpClient(baseUrl), (response) => {
 		capturedRaw = response.data;
 	});
-	const tls = proxyTlsClient(createTlsClient(baseUrl), (response) => {
-		capturedRaw = normalizeCapturedTlsResponse(response);
-	});
+	const stealth = proxyStealthClient(
+		createStealthClient(baseUrl),
+		(response) => {
+			capturedRaw = normalizeCapturedStealthResponse(response);
+		},
+	);
 
 	const ctx: ProviderContext = {
 		env: {
@@ -291,7 +297,8 @@ function createCaptureContext(baseUrl: string) {
 			getScopes: () => [],
 		},
 		http,
-		tls,
+		cache: createBypassProviderCache({ providerId: provider.id }),
+		stealth,
 		browser: {
 			engine: "playwright-stealth",
 			newPage: async () => {
@@ -306,6 +313,7 @@ function createCaptureContext(baseUrl: string) {
 				throw new Error("Auth prompts are not available in apifuse record.");
 			},
 		},
+		stt: createSttClientFromEnv(provider.stt),
 	};
 
 	return {
@@ -335,59 +343,39 @@ function proxyHttpClient(
 	}) as HttpClient;
 }
 
-function proxyTlsClient(
-	client: TlsClient,
-	onResponse: (response: Awaited<ReturnType<TlsClient["fetch"]>>) => void,
-): TlsClient {
-	return new Proxy(client, {
-		get(target, prop, receiver) {
-			const value = Reflect.get(target, prop, receiver);
-
-			if (prop === "fetch" && typeof value === "function") {
-				return async (...args: unknown[]) => {
-					const response = await value.apply(target, args);
-					onResponse(response);
-					return response;
-				};
-			}
-
-			if (prop === "createSession" && typeof value === "function") {
-				return (...args: unknown[]) => {
-					const session = value.apply(target, args) as ReturnType<
-						TlsClient["createSession"]
-					>;
-					return proxyTlsSession(session, onResponse);
-				};
-			}
+type StealthSession = ReturnType<StealthClient["createSession"]>;
 
-			return value;
+function proxyStealthClient(
+	client: StealthClient,
+	onResponse: (response: Awaited<ReturnType<StealthClient["fetch"]>>) => void,
+): StealthClient {
+	return {
+		fetch: async (...args: Parameters<StealthClient["fetch"]>) => {
+			const response = await client.fetch(...args);
+			onResponse(response);
+			return response;
 		},
-	}) as TlsClient;
+		createSession: (...args: Parameters<StealthClient["createSession"]>) =>
+			proxyStealthSession(client.createSession(...args), onResponse),
+	};
 }
 
-function proxyTlsSession(
-	session: ReturnType<TlsClient["createSession"]>,
-	onResponse: (response: Awaited<ReturnType<TlsClient["fetch"]>>) => void,
-) {
-	return new Proxy(session, {
-		get(target, prop, receiver) {
-			const value = Reflect.get(target, prop, receiver);
-
-			if (prop === "fetch" && typeof value === "function") {
-				return async (...args: unknown[]) => {
-					const response = await value.apply(target, args);
-					onResponse(response);
-					return response;
-				};
-			}
-
-			return value;
+function proxyStealthSession(
+	session: StealthSession,
+	onResponse: (response: Awaited<ReturnType<StealthClient["fetch"]>>) => void,
+): StealthSession {
+	return {
+		fetch: async (...args: Parameters<StealthSession["fetch"]>) => {
+			const response = await session.fetch(...args);
+			onResponse(response);
+			return response;
 		},
-	}) as ReturnType<TlsClient["createSession"]>;
+		close: () => session.close(),
+	};
 }
 
-function normalizeCapturedTlsResponse(
-	response: Awaited<ReturnType<TlsClient["fetch"]>>,
+function normalizeCapturedStealthResponse(
+	response: Awaited<ReturnType<StealthClient["fetch"]>>,
 ) {
 	try {
 		return JSON.parse(response.body);

package/bin/apifuse-submit-check.ts

@@ -2,11 +2,19 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
-import { basename, dirname, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
+import { z } from "zod";
+
 import packageJson from "../package.json";
 import type { ProviderDefinition } from "../src";
+import {
+	loadProviderLocaleCatalogs,
+	type ProviderLocale,
+	validateProviderLocaleCatalogs,
+} from "../src/i18n";
+import { APIFUSE_DESCRIPTION_KEY_META_KEY } from "../src/schema";
 import { type CheckResult, runChecks } from "./apifuse-check";
 
 const TIERS = ["bronze", "silver", "gold", "diamond"] as const;
@@ -77,6 +85,11 @@ const CATEGORY_MAX_POINTS = {
 	docs: 10,
 } as const;
 
+const REQUIRED_PUBLIC_PROVIDER_LOCALES = [
+	"en",
+	"ko",
+] as const satisfies readonly ProviderLocale[];
+
 const HELP_TEXT = `Usage: apifuse submit-check [path] [--tier bronze|silver|gold|diamond] [--json] [--markdown <path>] [--smoke-note <text>]
 Alias: apifuse bounty-check [path]
 Default: apifuse submit-check .`;
@@ -220,6 +233,7 @@ export async function buildSubmitCheckReport(
 	checks.push(...scoreBaseChecks(baseChecks));
 
 	if (provider) {
+		checks.push(scoreLocaleCatalog(providerRoot, provider));
 		checks.push(scoreOperationMetadata(provider));
 		checks.push(scoreFixtureCoverage(provider));
 		checks.push(scoreHealthCoverage(provider));
@@ -322,12 +336,170 @@ function scoreBaseChecks(results: CheckResult[]): SubmitCheck[] {
 	];
 }
 
+function scoreLocaleCatalog(
+	providerRoot: string,
+	provider: ProviderDefinition,
+): SubmitCheck {
+	const requiredKeys = collectProviderRequiredLocaleKeys(provider);
+	if (requiredKeys.length === 0) {
+		return pass(
+			"locale-catalog",
+			"operations",
+			"No key-owned provider metadata or operation metadata requires locale catalog validation.",
+			0,
+		);
+	}
+
+	try {
+		const availableLocales = REQUIRED_PUBLIC_PROVIDER_LOCALES.filter((locale) =>
+			existsSync(join(providerRoot, "locales", `${locale}.json`)),
+		);
+		const catalogs = loadProviderLocaleCatalogs({
+			providerDir: providerRoot,
+			locales: availableLocales,
+		});
+		const validation = validateProviderLocaleCatalogs({
+			catalogs,
+			requiredLocales: REQUIRED_PUBLIC_PROVIDER_LOCALES,
+			requiredKeys,
+		});
+		if (!validation.ok) {
+			return blocker(
+				"locale-catalog",
+				"operations",
+				"Provider locale catalog is missing required public-provider copy.",
+				"Add provider-local locales/en.json and locales/ko.json values for every provider metadata key, operation descriptionKey, and .describeKey() or describeKey() schema field.",
+				0,
+				validation.issues.map(
+					(issue) => `${issue.locale}:${issue.key}: ${issue.message}`,
+				),
+			);
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return blocker(
+			"locale-catalog",
+			"operations",
+			"Provider locale catalog is missing required public-provider copy.",
+			"Add provider-local locales/en.json and locales/ko.json values for every provider metadata key, operation descriptionKey, and .describeKey() or describeKey() schema field.",
+			0,
+			[`*:*: ${message}`],
+		);
+	}
+
+	return pass(
+		"locale-catalog",
+		"operations",
+		"Required provider and operation locale keys resolve in locales/en.json and locales/ko.json.",
+		0,
+	);
+}
+
+function collectProviderRequiredLocaleKeys(
+	provider: ProviderDefinition,
+): string[] {
+	const keys = new Set<string>();
+
+	addLocaleKeys(keys, [
+		provider.meta.descriptionKey,
+		provider.meta.docTitleKey,
+		provider.meta.docDescriptionKey,
+		provider.meta.docSummaryKey,
+		provider.meta.docMarkdownKey,
+	]);
+
+	const publicProfile = provider.meta.publicProfile;
+	if (publicProfile) {
+		addLocaleKeys(keys, [
+			publicProfile.displayNameKey,
+			publicProfile.shortDescriptionKey,
+			publicProfile.longDescriptionKey,
+			publicProfile.setupSummaryKey,
+			...(publicProfile.capabilityKeys ?? []),
+			...(publicProfile.examplePromptKeys ?? []),
+			...(publicProfile.requirementKeys ?? []),
+			...(publicProfile.limitationKeys ?? []),
+		]);
+	}
+
+	for (const operation of Object.values(provider.operations)) {
+		addLocaleKeys(keys, [
+			operation.descriptionKey,
+			operation.docs?.titleKey,
+			operation.docs?.descriptionKey,
+			operation.docs?.summaryKey,
+			operation.docs?.markdownKey,
+			...(operation.whenToUseKeys ?? []),
+			...(operation.whenNotToUseKeys ?? []),
+			...collectSchemaDescriptionKeys(operation.input),
+			...collectSchemaDescriptionKeys(operation.output),
+		]);
+	}
+
+	return Array.from(keys);
+}
+
+function addLocaleKeys(keys: Set<string>, values: readonly unknown[]): void {
+	for (const key of values) {
+		if (typeof key === "string" && key.length > 0) {
+			keys.add(key);
+		}
+	}
+}
+
+function collectSchemaDescriptionKeys(schema: unknown): string[] {
+	if (!(schema instanceof z.ZodType)) {
+		return [];
+	}
+	const jsonSchema = z.toJSONSchema(schema);
+	if (!isRecord(jsonSchema)) {
+		return [];
+	}
+	const keys: string[] = [];
+	collectJsonSchemaDescriptionKeys(jsonSchema, keys);
+	return keys;
+}
+
+function collectJsonSchemaDescriptionKeys(
+	schema: Record<string, unknown>,
+	keys: string[],
+): void {
+	const descriptionKey = schema[APIFUSE_DESCRIPTION_KEY_META_KEY];
+	if (typeof descriptionKey === "string" && descriptionKey.length > 0) {
+		keys.push(descriptionKey);
+	}
+
+	for (const value of Object.values(schema)) {
+		if (isRecord(value)) {
+			collectJsonSchemaDescriptionKeys(value, keys);
+		} else if (Array.isArray(value)) {
+			for (const item of value) {
+				if (isRecord(item)) {
+					collectJsonSchemaDescriptionKeys(item, keys);
+				}
+			}
+		}
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function scoreOperationMetadata(provider: ProviderDefinition): SubmitCheck {
 	const operations = Object.entries(provider.operations);
 	const weakDescriptions = operations
-		.filter(
-			([, operation]) => (operation.description ?? "").trim().length < 150,
-		)
+		.filter(([, operation]) => {
+			// Hard-cut providers move operation copy into locale catalogs via
+			// descriptionKey instead of raw inline prose; the resolved text length
+			// is enforced at registry catalog-build time, matching how lintOperation
+			// skips the raw-description min-length rule when a descriptionKey is set.
+			const hasDescriptionKey =
+				typeof operation.descriptionKey === "string" &&
+				operation.descriptionKey.length > 0;
+			if (hasDescriptionKey) return false;
+			return true;
+		})
 		.map(([operationId]) => operationId);
 	const missingAnnotations = operations
 		.filter(([, operation]) => !operation.annotations)
@@ -520,7 +692,7 @@ function scoreSmokeEvidence(smokeNote: string | undefined): SubmitCheck {
 		maxPoints: CATEGORY_MAX_POINTS.smoke,
 		message: "No local smoke evidence was provided.",
 		remediation:
-			"Start `bun run dev`, call `/health` and at least one `POST /v1/{operation}`, then rerun with `--smoke-note` or paste notes in the bounty issue.",
+			"Start `bun run dev`, call `/health` and at least one `POST /v1/{operation}`, then rerun with `--smoke-note` or paste notes in the assigned workspace PR.",
 	};
 }
 
@@ -784,7 +956,7 @@ function blocker(
 
 export function renderText(report: SubmitCheckReport): string {
 	const lines = [
-		`ApiFuse Provider Submission Score: ${report.score.total} / ${report.score.max}`,
+		`APIFuse Provider Submission Score: ${report.score.total} / ${report.score.max}`,
 		`Verdict: ${report.score.verdict.toUpperCase()}`,
 		`Provider: ${report.provider.id}@${report.provider.version} (${report.provider.runtime}, auth: ${report.provider.authMode})`,
 		`Blockers: ${report.summary.blockers}  Warnings: ${report.summary.warnings}  Passed: ${report.summary.passed}`,
@@ -811,7 +983,7 @@ export function renderText(report: SubmitCheckReport): string {
 
 export function renderMarkdown(report: SubmitCheckReport): string {
 	const lines = [
-		"# ApiFuse Provider Submission Report",
+		"# APIFuse Provider Submission Report",
 		"",
 		`- **Provider**: ${report.provider.id}@${report.provider.version}`,
 		`- **SDK**: ${report.provider.sdkVersion}`,

package/bin/apifuse.ts

@@ -28,7 +28,7 @@ await module.main();
 
 function printHelp() {
 	console.log(`
-apifuse - ApiFuse Provider SDK CLI
+apifuse - APIFuse Provider SDK CLI
 
 Commands:`);
 	for (const name of COMMAND_ORDER) {

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.3",
+	"version": "2.1.0-beta.4",
 	"private": false,
 	"type": "module",
-	"description": "ApiFuse Provider SDK — Build providers with zero architectural constraints",
+	"description": "APIFuse Provider SDK — Build providers with zero architectural constraints",
 	"license": "MIT",
 	"main": "./src/index.ts",
 	"types": "./src/index.ts",
@@ -53,6 +53,11 @@
 			"default": "./src/testing/index.ts",
 			"import": "./src/testing/index.ts",
 			"types": "./src/testing/index.ts"
+		},
+		"./create": {
+			"default": "./src/cli/create.ts",
+			"import": "./src/cli/create.ts",
+			"types": "./src/cli/create.ts"
 		}
 	},
 	"scripts": {
@@ -66,20 +71,24 @@
 		"pack:smoke": "bun bin/apifuse-pack-smoke.ts"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.15",
+		"@biomejs/biome": "^2.5.0",
 		"@types/bun": "latest",
-		"@types/node": "^25.8.0",
+		"@types/node": "^25.9.3",
 		"typescript": "^6.0.3"
 	},
 	"dependencies": {
-		"@clack/prompts": "^1.4.0",
+		"@clack/prompts": "^1.5.1",
+		"@types/ms": "^2.1.0",
 		"ajv": "^8.17",
-		"hono": "^4.12.19",
+		"hono": "^4.12.25",
+		"impit": "0.14.1",
+		"ioredis": "^5.11.1",
+		"ms": "^2.1.3",
 		"playwright": "^1.55.1",
-		"playwright-stealth": "^0.0.1",
+		"playwright-extra": "^4.3.6",
+		"puppeteer-extra-plugin-stealth": "^2.11.2",
 		"re2-wasm": "^1.0",
 		"safe-regex": "^2.1",
-		"tlsclientwrapper": "^4.2.0",
 		"zod": "^4.4.3"
 	}
 }