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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.1.0-beta.6
+
+- Public repository clean-import release for `APIFuseHQ/provider-sdk`.
+- Preserves the monorepo SDK exports required by ApiFuse provider registry cutover, including `./contract` and provider i18n helpers.
+
+
 ## 2.1.0-beta.5
 
 - Republish the bounty workspace DX hardening that accepts generated readonly metadata and factored `defineOperation()` maps during standalone TypeScript checks.

package/README.md

@@ -216,11 +216,11 @@ Operations declare non-functional metadata via `annotations`:
 apifuse create <name>
 apifuse dev [path]
 apifuse check [path]
-apifuse record providers/airkorea --operation realtime --params '{"stationName":"종로구"}'
+apifuse record providers/korea-air-quality --operation realtime --params '{"stationName":"종로구"}'
 apifuse test [path]
 apifuse submit-check [path] --tier bronze --markdown submission-report.md
 apifuse bounty-check [path]
-apifuse perf providers/airkorea --operation realtime --params '{"stationName":"종로구"}'
+apifuse perf providers/korea-air-quality --operation realtime --params '{"stationName":"종로구"}'
 ```
 
 `apifuse record` is for real upstream-backed operations that declare

package/SUBMISSION.md

@@ -48,8 +48,9 @@ Fix all blockers before submitting:
 - Missing `healthCheck` or `healthCheckUnsupported` on any Operation.
 - Credential-backed auth mode without declared credential keys.
 - High-confidence secret or token material in source, README, package metadata, or fixtures.
+- SDK-native source blockers: prefixed Provider ids, `vendor/` SDK shims or imports, raw `.describe()` prose instead of `describeKey`, raw global `fetch()` calls, and excessive `as Type` assertions.
 
-Warnings do not fail the command, but they should be addressed when practical. For example, the generated starter `ping` operation warns because it is not a real upstream-backed bounty Operation.
+Warnings do not fail the command, but they should be addressed when practical. For example, the generated starter `ping` operation warns because it is not a real upstream-backed bounty Operation. SDK-native warnings also flag moderate `as Type` assertion counts and credentialed Providers that never reference `ctx.credential`.
 
 ## Safe local smoke evidence
 

package/bin/apifuse-check.ts

@@ -1,17 +1,17 @@
 #!/usr/bin/env bun
 
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
 
 import type { ProviderDefinition } from "../src";
-import { lintProvider } from "../src/lint";
+import { lintProvider, type ProviderLintMode } from "../src/lint";
 import { safeParseSchemaSync } from "../src/schema";
 
 const HELP_TEXT = `Usage: apifuse check [path]
-Example: apifuse check providers/airkorea
+Example: apifuse check providers/korea-air-quality
 Default: apifuse check .`;
 
 export type CheckResult = {
@@ -20,6 +20,10 @@ export type CheckResult = {
 	details?: string[];
 };
 
+export type RunChecksOptions = {
+	lintMode?: ProviderLintMode;
+};
+
 type SafeParseResult =
 	| { success: true; data: unknown }
 	| { success: false; error: unknown };
@@ -104,7 +108,10 @@ function resolveFromParents(inputPath: string): string {
 	}
 }
 
-export async function runChecks(providerRoot: string): Promise<CheckResult[]> {
+export async function runChecks(
+	providerRoot: string,
+	options: RunChecksOptions = {},
+): Promise<CheckResult[]> {
 	const indexPath = resolve(providerRoot, "index.ts");
 	const dockerfilePath = resolve(providerRoot, "Dockerfile");
 	const packageJsonPath = resolve(providerRoot, "package.json");
@@ -113,19 +120,61 @@ export async function runChecks(providerRoot: string): Promise<CheckResult[]> {
 		? await import(pathToFileURL(indexPath).href)
 		: undefined;
 	const provider = assertProviderDefinition(providerModule?.default);
+	const providerSourceFiles = collectProviderSourceFiles(providerRoot);
 
 	return [
 		checkIndex(indexPath, provider),
 		checkOperations(provider),
 		checkFixtures(provider),
 		checkSchemas(provider),
-		checkAuthoringLint(provider),
+		checkAuthoringLint(provider, providerSourceFiles, options.lintMode),
 		checkProviderMetadata(provider),
 		checkDockerfile(dockerfilePath),
 		checkPackageJson(packageJsonPath),
 	];
 }
 
+function isScannableProviderSourceFile(relativePath: string): boolean {
+	return (
+		/\.(?:ts|tsx|js|jsx|mjs|cjs|sh|bash)$/.test(relativePath) ||
+		/(?:^|\/)Dockerfile(?:\.|$)/.test(relativePath) ||
+		/(?:^|\/)entrypoint(?:\.|$)/.test(relativePath)
+	);
+}
+
+function collectProviderSourceFiles(
+	providerRoot: string,
+): Record<string, string> {
+	const sources: Record<string, string> = {};
+	const skipDirectories = new Set([
+		".git",
+		"node_modules",
+		"dist",
+		"build",
+		".next",
+	]);
+	const visit = (directory: string) => {
+		for (const entry of readdirSync(directory, { withFileTypes: true })) {
+			const path = resolve(directory, entry.name);
+			if (entry.isDirectory()) {
+				if (!skipDirectories.has(entry.name)) {
+					visit(path);
+				}
+				continue;
+			}
+			if (
+				!entry.isFile() ||
+				!isScannableProviderSourceFile(path.slice(providerRoot.length + 1))
+			) {
+				continue;
+			}
+			sources[path.slice(providerRoot.length + 1)] = readFileSync(path, "utf8");
+		}
+	};
+	visit(providerRoot);
+	return sources;
+}
+
 function checkIndex(
 	indexPath: string,
 	provider: ProviderDefinition | undefined,
@@ -258,6 +307,8 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 
 function checkAuthoringLint(
 	provider: ProviderDefinition | undefined,
+	providerSourceFiles: Record<string, string>,
+	lintMode: ProviderLintMode = "official",
 ): CheckResult {
 	if (!provider) {
 		return {
@@ -266,7 +317,10 @@ function checkAuthoringLint(
 		};
 	}
 
-	const diagnostics = lintProvider(provider);
+	const diagnostics = lintProvider(
+		{ ...provider, providerSourceFiles },
+		{ mode: lintMode },
+	);
 	const errors = diagnostics.filter(
 		(diagnostic) => diagnostic.level === "error",
 	);

package/bin/apifuse-dev.ts

@@ -9,16 +9,18 @@ import {
 	createEnvContext,
 	createHttpClient,
 	createProviderCache,
+	createProviderChoiceContext,
 	createStealthClient,
 	createSttClientFromEnv,
+	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
 	ProviderError,
 } from "../src";
-import { createUnsupportedProviderRuntimeState } from "../src/runtime/state";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state";
 import { createTraceContext } from "../src/runtime/trace";
 import type { BrowserClient, ProviderContext } from "../src/types";
 
 const HELP_TEXT = `Usage: apifuse dev [path]
-Example: apifuse dev providers/airkorea
+Example: apifuse dev providers/korea-air-quality
 Default: apifuse dev .`;
 
 export async function main() {
@@ -76,22 +78,35 @@ export async function main() {
 export function createProviderContext(provider: ProviderDefinition): {
 	ctx: ProviderContext;
 } {
+	const env = createEnvContext([
+		...(provider.secrets?.map((secret) => secret.name) ?? []),
+		PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	]);
+	const credential = createCredentialContext();
+	const state = createMemoryProviderRuntimeState();
 	const ctx: ProviderContext = {
-		env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
-		credential: createCredentialContext(),
+		env,
+		credential,
 		auth: createUnsupportedAuthStub(),
 		browser:
 			provider.runtime === "browser"
 				? createBrowserClient({
+						allowedHosts: provider.allowedHosts,
 						engine: provider.browser?.engine ?? "playwright-stealth",
 					})
 				: createUnsupportedBrowserStub(),
 		http: createHttpClient(),
 		cache: createProviderCache({ providerId: provider.id }),
-		state: createUnsupportedProviderRuntimeState(),
+		state,
 		trace: createTraceContext(),
 		stealth: createStealthClient("http://localhost"),
 		stt: createSttClientFromEnv(provider.stt),
+		choice: createProviderChoiceContext({
+			providerId: provider.id,
+			env,
+			credential,
+			state,
+		}),
 	};
 
 	return { ctx };
@@ -149,6 +164,7 @@ function shellSingleQuote(value: string): string {
 function createUnsupportedBrowserStub(): BrowserClient {
 	return {
 		engine: "playwright-stealth",
+		async close() {},
 		async newPage() {
 			throw new ProviderError(
 				"Browser runtime is not enabled for this provider",
@@ -158,6 +174,33 @@ function createUnsupportedBrowserStub(): BrowserClient {
 				},
 			);
 		},
+		async rawPage() {
+			throw new ProviderError(
+				"Browser runtime is not enabled for this provider",
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+					fix: 'Set provider runtime to "browser" and APIFUSE__CDP_POOL__URL to use ctx.browser.rawPage',
+				},
+			);
+		},
+		async withIsolatedContext() {
+			throw new ProviderError(
+				"Browser runtime is not enabled for this provider",
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+					fix: 'Set provider runtime to "browser" to use ctx.browser.withIsolatedContext',
+				},
+			);
+		},
+		async solveChallenge() {
+			throw new ProviderError(
+				"Browser runtime is not enabled for this provider",
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+					fix: 'Set provider runtime to "browser" to use ctx.browser.solveChallenge',
+				},
+			);
+		},
 	};
 }
 

package/bin/apifuse-perf.ts

@@ -10,6 +10,7 @@ import {
 	type ApiFuseConfig,
 	createBypassProviderCache,
 	createHttpClient,
+	createProviderChoiceContext,
 	createStealthClient,
 	createSttClientFromEnv,
 	executeOperation,
@@ -29,6 +30,7 @@ import {
 	groupSpansByName,
 	type PerfStats,
 } from "../src/runtime/perf";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state";
 import {
 	createTraceContext,
 	resolveTraceContextOptions,
@@ -96,7 +98,7 @@ Options:
   --help, -h               show this help
 
 Example:
-  apifuse perf providers/airkorea --operation realtime --params '{"stationName":"jongno"}' --runs 5`;
+  apifuse perf providers/korea-air-quality --operation realtime --params '{"stationName":"jongno"}' --runs 5`;
 
 export async function main() {
 	try {
@@ -688,24 +690,36 @@ function createBaseContext(options: {
 					upstream,
 				});
 
+	const env = {
+		get: (key: string) => process.env[key],
+	};
+	const credential = {
+		mode: "none" as const,
+		get: () => undefined,
+		getAll: () => ({}),
+		getAccessToken: () => undefined,
+		getScopes: () => [],
+	};
+	const state = createMemoryProviderRuntimeState();
 	return {
-		env: {
-			get: (key: string) => process.env[key],
-		},
-		credential: {
-			mode: "none",
-			get: () => undefined,
-			getAll: () => ({}),
-			getAccessToken: () => undefined,
-			getScopes: () => [],
-		},
+		env,
+		credential,
+		request: { headers: {} },
 		http,
 		cache: createBypassProviderCache({ providerId: options.provider.id }),
+		state,
 		stealth,
 		browser: createBrowserStub(),
 		trace: options.traceContext,
 		auth: createAuthStub(),
 		stt: createSttClientFromEnv(options.provider.stt),
+		choice: createProviderChoiceContext({
+			providerId: options.provider.id,
+			env,
+			request: { headers: {} },
+			credential,
+			state,
+		}),
 	};
 }
 
@@ -765,6 +779,7 @@ function createFixtureStealthClient(rawText: string): StealthClient {
 function createBrowserStub(): BrowserClient {
 	return {
 		engine: "playwright-stealth",
+		async close() {},
 		async newPage() {
 			throw new ProviderError(
 				"Browser runtime is not supported by apifuse perf yet.",
@@ -773,6 +788,30 @@ function createBrowserStub(): BrowserClient {
 				},
 			);
 		},
+		async rawPage() {
+			throw new ProviderError(
+				"Browser runtime is not supported by apifuse perf yet.",
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+				},
+			);
+		},
+		async withIsolatedContext() {
+			throw new ProviderError(
+				"Browser runtime is not supported by apifuse perf yet.",
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+				},
+			);
+		},
+		async solveChallenge() {
+			throw new ProviderError(
+				"Browser runtime is not supported by apifuse perf yet.",
+				{
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+				},
+			);
+		},
 	};
 }
 

package/bin/apifuse-record.ts

@@ -9,6 +9,7 @@ import { pathToFileURL } from "node:url";
 import {
 	createBypassProviderCache,
 	createHttpClient,
+	createProviderChoiceContext,
 	createStealthClient,
 	createSttClientFromEnv,
 	executeOperation,
@@ -20,6 +21,7 @@ import {
 	TransportError,
 	ValidationError,
 } from "../src";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state";
 
 type CliArgs = {
 	append: boolean;
@@ -46,7 +48,7 @@ Options:
   --help, -h               show this help
 
 Example:
-  apifuse record providers/airkorea --operation realtime --params '{"stationName":"jongno"}'`;
+  apifuse record providers/korea-air-quality --operation realtime --params '{"stationName":"jongno"}'`;
 
 export async function main() {
 	try {
@@ -351,25 +353,40 @@ function createCaptureContext(provider: ProviderRuntime, baseUrl: string) {
 		},
 	);
 
+	const env = {
+		get: (key: string) => process.env[key],
+	};
+	const credential = {
+		mode: "none" as const,
+		get: () => undefined,
+		getAll: () => ({}),
+		getAccessToken: () => undefined,
+		getScopes: () => [],
+	};
+	const state = createMemoryProviderRuntimeState();
 	const ctx: ProviderContext = {
-		env: {
-			get: (key) => process.env[key],
-		},
-		credential: {
-			mode: "none",
-			get: () => undefined,
-			getAll: () => ({}),
-			getAccessToken: () => undefined,
-			getScopes: () => [],
-		},
+		env,
+		credential,
+		request: { headers: {} },
 		http,
 		cache: createBypassProviderCache({ providerId: provider.id }),
+		state,
 		stealth,
 		browser: {
 			engine: "playwright-stealth",
+			close: async () => {},
 			newPage: async () => {
 				throw new Error("Browser client is not available in apifuse record.");
 			},
+			rawPage: async () => {
+				throw new Error("Browser client is not available in apifuse record.");
+			},
+			withIsolatedContext: async () => {
+				throw new Error("Browser client is not available in apifuse record.");
+			},
+			solveChallenge: async () => {
+				throw new Error("Browser client is not available in apifuse record.");
+			},
 		},
 		trace: {
 			span: async (_name, fn) => fn(),
@@ -380,6 +397,13 @@ function createCaptureContext(provider: ProviderRuntime, baseUrl: string) {
 			},
 		},
 		stt: createSttClientFromEnv(provider.stt),
+		choice: createProviderChoiceContext({
+			providerId: provider.id,
+			env,
+			request: { headers: {} },
+			credential,
+			state,
+		}),
 	};
 
 	return {