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

package/bin/apifuse-record.ts

@@ -7,13 +7,18 @@ 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,
+	ProviderError,
+	type StealthClient,
+	TransportError,
+	ValidationError,
 } from "../src";
 
 type CliArgs = {
@@ -28,55 +33,77 @@ type ProviderRuntime = ProviderDefinition;
 
 type MutableRecord = Record<string, unknown>;
 
-export async function main() {
-	const args = parseArgs(normalizeArgs(process.argv.slice(2)));
-	const location = resolveProviderLocation(args.providerPath);
-	const provider = await loadProvider(location.rootDir);
-	const operationName = resolveOperationName(provider, args.operation);
-	const operation = provider.operations[operationName];
-	const parsedParams = parseParams(operation, args.params);
-
-	const capture = createCaptureContext(
-		resolveOperationBaseUrl(provider, operationName),
-	);
+const HELP_TEXT = `Usage: apifuse record [path] --operation <operation> --params '<json>'
 
-	console.log(`[apifuse record] Calling ${operationName} on ${provider.id}...`);
+Calls a real upstream-backed operation through ctx.http or ctx.stealth and writes __fixtures__/raw.json.
 
-	const result = await executeOperation(
-		provider,
-		operationName,
-		capture.ctx,
-		parsedParams,
-	);
-	const captured = capture.getCapturedRaw();
+Options:
+  --operation, -o <name>   operation to call
+  --params, -p <json>      JSON input passed to the operation (default: {})
+  --append                 append to an existing array fixture
+  --sanitize               redact common token/header fields (default)
+  --no-sanitize            write the captured upstream payload as-is
+  --help, -h               show this help
 
-	if (captured === undefined) {
-		throw new Error(
-			`No upstream response was captured for ${provider.id}.${operationName}.`,
+Example:
+  apifuse record providers/airkorea --operation realtime --params '{"stationName":"jongno"}'`;
+
+export async function main() {
+	try {
+		const args = parseArgs(normalizeArgs(process.argv.slice(2)));
+		const location = resolveProviderLocation(args.providerPath);
+		const provider = await loadProvider(location.rootDir);
+		const operationName = resolveOperationName(provider, args.operation);
+		const operation = provider.operations[operationName];
+		const parsedParams = parseParams(operation, args.params);
+
+		const capture = createCaptureContext(
+			provider,
+			resolveOperationBaseUrl(provider, operationName),
 		);
-	}
 
-	const rawPayload = args.sanitize ? sanitizeFixture(captured) : captured;
-	const fixturePath = resolve(location.rootDir, "__fixtures__", "raw.json");
-	const nextPayload = await prepareFixturePayload(
-		fixturePath,
-		rawPayload,
-		args.append,
-	);
+		console.log(
+			`[apifuse record] Calling ${operationName} on ${provider.id}...`,
+		);
 
-	await mkdir(dirname(fixturePath), { recursive: true });
-	await writeFile(fixturePath, `${JSON.stringify(nextPayload, null, 2)}\n`);
+		const result = await executeOperation(
+			provider,
+			operationName,
+			capture.ctx,
+			parsedParams,
+		);
+		const captured = capture.getCapturedRaw();
 
-	console.log(
-		`[apifuse record] Captured response (${formatBytes(
-			Buffer.byteLength(JSON.stringify(rawPayload)),
-		)})`,
-	);
-	console.log(
-		`[apifuse record] Saved to ${relative(process.cwd(), fixturePath)}`,
-	);
+		if (captured === undefined) {
+			throw new Error(
+				`No upstream response was captured for ${provider.id}.${operationName}.`,
+			);
+		}
+
+		const rawPayload = args.sanitize ? sanitizeFixture(captured) : captured;
+		const fixturePath = resolve(location.rootDir, "__fixtures__", "raw.json");
+		const nextPayload = await prepareFixturePayload(
+			fixturePath,
+			rawPayload,
+			args.append,
+		);
+
+		await mkdir(dirname(fixturePath), { recursive: true });
+		await writeFile(fixturePath, `${JSON.stringify(nextPayload, null, 2)}\n`);
+
+		console.log(
+			`[apifuse record] Captured response (${formatBytes(
+				Buffer.byteLength(JSON.stringify(rawPayload)),
+			)})`,
+		);
+		console.log(
+			`[apifuse record] Saved to ${relative(process.cwd(), fixturePath)}`,
+		);
 
-	void result;
+		void result;
+	} catch (error) {
+		handleCliError(error);
+	}
 }
 
 function normalizeArgs(argv: string[]): string[] {
@@ -104,6 +131,11 @@ function parseArgs(argv: string[]): CliArgs {
 			continue;
 		}
 
+		if (arg === "--help" || arg === "-h") {
+			console.log(HELP_TEXT);
+			process.exit(0);
+		}
+
 		if (arg.startsWith("--operation=")) {
 			operation = arg.slice("--operation=".length);
 			continue;
@@ -155,6 +187,43 @@ function parseArgs(argv: string[]): CliArgs {
 	return { append, providerPath, operation, params, sanitize };
 }
 
+function handleCliError(error: unknown): never {
+	const message = formatCliError(error);
+	console.error(`[apifuse record] ${message}`);
+	process.exit(1);
+}
+
+function formatCliError(error: unknown): string {
+	if (error instanceof TransportError) {
+		return [
+			error.message,
+			error.upstreamStatus ? `status=${error.upstreamStatus}` : undefined,
+			error.options?.retryable !== undefined
+				? `retryable=${String(error.options.retryable)}`
+				: undefined,
+			error.fix ? `fix=${error.fix}` : undefined,
+		]
+			.filter(Boolean)
+			.join(" ");
+	}
+
+	if (error instanceof ProviderError || error instanceof ValidationError) {
+		return [
+			error.message,
+			error.code ? `code=${error.code}` : undefined,
+			error.fix,
+		]
+			.filter(Boolean)
+			.join(" ");
+	}
+
+	if (error instanceof Error) {
+		return error.message;
+	}
+
+	return String(error);
+}
+
 function resolveProviderLocation(inputPath?: string) {
 	const originalInput = inputPath ?? process.cwd();
 	const resolvedInput = resolve(process.cwd(), originalInput);
@@ -269,15 +338,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 +363,8 @@ function createCaptureContext(baseUrl: string) {
 			getScopes: () => [],
 		},
 		http,
-		tls,
+		cache: createBypassProviderCache({ providerId: provider.id }),
+		stealth,
 		browser: {
 			engine: "playwright-stealth",
 			newPage: async () => {
@@ -306,6 +379,7 @@ function createCaptureContext(baseUrl: string) {
 				throw new Error("Auth prompts are not available in apifuse record.");
 			},
 		},
+		stt: createSttClientFromEnv(provider.stt),
 	};
 
 	return {
@@ -335,59 +409,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,12 +233,14 @@ 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));
 		checks.push(scoreAuthSafety(provider));
 		checks.push(scoreSmokeEvidence(args.smokeNote));
 		checks.push(...scoreProviderDocs(providerRoot));
+		checks.push(scoreRepositoryDx(providerRoot));
 		checks.push(scoreSecrets(providerRoot));
 	} else {
 		checks.push(
@@ -273,6 +288,69 @@ export async function buildSubmitCheckReport(
 	};
 }
 
+function scoreRepositoryDx(providerRoot: string): SubmitCheck {
+	const missing: string[] = [];
+	if (!existsSync(resolve(providerRoot, ".gitignore"))) {
+		missing.push(".gitignore");
+	}
+
+	const packageJsonPath = resolve(providerRoot, "package.json");
+	const packageScripts = readPackageScripts(packageJsonPath);
+	if (typeof packageScripts?.["type-check"] !== "string") {
+		missing.push("package.json scripts.type-check");
+	}
+	if (!checkScriptRunsTypeCheck(packageScripts?.check)) {
+		missing.push("package.json scripts.check includes type-check");
+	}
+
+	if (missing.length === 0) {
+		return pass(
+			"repository-dx",
+			"docs",
+			"Repository includes generated-provider DX guardrails.",
+			0,
+		);
+	}
+
+	return {
+		id: "repository-dx",
+		category: "docs",
+		level: "warn",
+		status: "warn",
+		points: 0,
+		maxPoints: 0,
+		message: `Generated repository DX guardrails are missing: ${missing.join(", ")}.`,
+		remediation:
+			"Regenerate with the current `apifuse create` template or add .gitignore plus `type-check: tsc --noEmit` and include it from `check`.",
+		evidence: missing,
+	};
+}
+
+function readPackageScripts(
+	packageJsonPath: string,
+): Record<string, unknown> | undefined {
+	if (!existsSync(packageJsonPath)) {
+		return undefined;
+	}
+
+	try {
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+		if (!isRecord(packageJson) || !isRecord(packageJson.scripts)) {
+			return undefined;
+		}
+		return packageJson.scripts;
+	} catch {
+		return undefined;
+	}
+}
+
+function checkScriptRunsTypeCheck(checkScript: unknown): boolean {
+	return (
+		typeof checkScript === "string" &&
+		/(?:^|&&|;)\s*bun\s+run\s+type-check(?:\s|$)/.test(checkScript)
+	);
+}
+
 async function safeRunChecks(providerRoot: string): Promise<CheckResult[]> {
 	try {
 		return await runChecks(providerRoot);
@@ -322,12 +400,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 +756,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 +1020,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 +1047,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) {