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

package/AUTHORING.md

@@ -53,6 +53,30 @@ description:
 
 Use `defineOperation()` when an operation is large enough to live beside helper functions or in a separate module. It preserves the same type inference as inline `defineProvider()` operations and can be placed directly in the provider `operations` map. `defineProvider()` accepts Zod and Standard Schema v1-compatible schemas. If config validation fails, the SDK names the field to fix, for example `runtime`, `auth.mode`, `operations.<id>.handler`, or `operations.<id>.fixtures.response`.
 
+### Health assertion context
+
+`healthCheck.cases[].assertions` receives a `HealthCheckAssertionContext` with
+`data`, `status`, `durationMs`, and optional `meta`. `data` is typed from the
+operation output schema, so assertions should inspect normalized output instead
+of reaching into transport internals.
+
+<!-- @magic-start:sample -->
+```ts
+healthCheck: {
+  interval: "5m",
+  cases: [{
+    name: "lookup baseline",
+    input: { q: "btc" },
+    assertions: ({ data, status, durationMs }) => {
+      if (status !== 200 || data.results.length === 0 || durationMs > 3000) {
+        return { status: "degraded", label: "lookup baseline changed" };
+      }
+    },
+  }],
+}
+```
+<!-- @magic-end:sample -->
+
 ### Strongly recommended (warn-level rules)
 
 - `description` includes "use" AND "when" phrasing

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @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.
+- Ensure new bounty workspaces can install the public SDK version that matches their generated scaffold and pass `bun run check` immediately after bootstrap.
+
 ## 2.1.0-beta.4
 
 - Align `apifuse create` with the bounty program topology: external contributors use the standalone one-provider-repository scaffold even when their assigned repo contains workspace-like files.

package/README.md

@@ -149,6 +149,9 @@ const search = defineOperation({
   async handler(ctx, input) {
     return { count: input.q.length }
   },
+  healthCheckUnsupported: {
+    reason: "Example operation only; replace with a real upstream probe.",
+  },
 })
 
 export default defineProvider({
@@ -174,6 +177,24 @@ Every operation must declare exactly one of:
 The generated `ping` operation uses `healthCheckUnsupported` only because it is
 a local scaffold check, not a real upstream API probe.
 
+`healthCheck.cases[].assertions` receives `{ data, status, durationMs, meta }`.
+`data` is the operation output parsed by the declared output schema:
+
+```ts
+healthCheck: {
+  interval: "5m",
+  cases: [{
+    name: "search responds",
+    input: { q: "weather" },
+    assertions: ({ data, status, durationMs }) => {
+      if (status !== 200 || data.count < 1 || durationMs > 3000) {
+        return { status: "degraded", label: "unexpected search baseline" }
+      }
+    },
+  }],
+}
+```
+
 ### Operation annotations
 
 Operations declare non-functional metadata via `annotations`:
@@ -195,11 +216,11 @@ Operations declare non-functional metadata via `annotations`:
 apifuse create <name>
 apifuse dev [path]
 apifuse check [path]
-apifuse record [path] --operation <operation> --params '{"value":"hello"}'
+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 <path> --operation <operation>
+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,
@@ -43,6 +45,7 @@ type CliArgs = {
 	exportPath?: string;
 	flame: boolean;
 	operation: string;
+	params?: string;
 	runs: number;
 	warmup: number;
 };
@@ -81,6 +84,21 @@ const DEFAULT_RUNS = 10;
 const DEFAULT_WARMUP = 2;
 const DEFAULT_CONCURRENCY = 1;
 const BAR_WIDTH = 20;
+const HELP_TEXT = `Usage: apifuse perf <provider-path> --operation <operation> [options]
+
+Options:
+  --operation, -o <name>   operation to profile (required)
+  --params, -p <json>      JSON input template; falls back to fixtures.request or {}
+  --runs, -n <number>      number of runs (default: 10)
+  --warmup <number>        warmup runs (default: 2)
+  --concurrency, -c <n>    concurrent requests (default: 1)
+  --compare-proxy          run with proxy on/off and compare
+  --export <path>          export results to JSON file
+  --flame                  generate flamegraph SVG
+  --help, -h               show this help
+
+Example:
+  apifuse perf providers/korea-air-quality --operation realtime --params '{"stationName":"jongno"}' --runs 5`;
 
 export async function main() {
 	try {
@@ -94,7 +112,11 @@ export async function main() {
 		const inputSchema = getOperationSchema(provider, operation, "input");
 		const outputSchema = getOperationSchema(provider, operation, "output");
 		const fixtureReplay = await loadFixtureReplay(providerDirectory);
-		const inputTemplate = resolveInputTemplate(provider, inputSchema);
+		const inputTemplate = resolveInputTemplate(
+			provider,
+			inputSchema,
+			args.params,
+		);
 
 		const directSuite = await runProfileSuite({
 			args,
@@ -184,6 +206,7 @@ function parseArgs(argv: string[]): CliArgs {
 	let compareProxy = false;
 	let exportPath: string | undefined;
 	let flame = false;
+	let params: string | undefined;
 
 	for (let index = 0; index < argv.length; index += 1) {
 		const arg = argv[index];
@@ -201,6 +224,11 @@ function parseArgs(argv: string[]): CliArgs {
 			continue;
 		}
 
+		if (arg === "--help" || arg === "-h") {
+			console.log(HELP_TEXT);
+			process.exit(0);
+		}
+
 		if (arg === "--compare-proxy") {
 			compareProxy = true;
 			continue;
@@ -222,6 +250,22 @@ function parseArgs(argv: string[]): CliArgs {
 			continue;
 		}
 
+		if (arg === "--params" || arg === "-p") {
+			params = requireArgValue(argv, index, arg);
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith("--params=")) {
+			params = arg.slice("--params=".length);
+			continue;
+		}
+
+		if (arg.startsWith("-p=")) {
+			params = arg.slice("-p=".length);
+			continue;
+		}
+
 		if (arg.startsWith("-o=")) {
 			operation = arg.slice("-o=".length);
 			continue;
@@ -294,20 +338,7 @@ function parseArgs(argv: string[]): CliArgs {
 	}
 
 	if (!providerPath || !operation) {
-		throw new Error(
-			[
-				"Usage: apifuse perf <provider-path> [options]",
-				"",
-				"Options:",
-				"  --operation, -o <name>   operation to profile (required)",
-				"  --runs, -n <number>      number of runs (default: 10)",
-				"  --warmup <number>        warmup runs (default: 2)",
-				"  --concurrency, -c <n>    concurrent requests (default: 1)",
-				"  --compare-proxy          run with proxy on/off and compare",
-				"  --export <path>          export results to JSON file",
-				"  --flame                  generate flamegraph SVG",
-			].join("\n"),
-		);
+		throw new Error(HELP_TEXT);
 	}
 
 	return {
@@ -317,6 +348,7 @@ function parseArgs(argv: string[]): CliArgs {
 		exportPath,
 		flame,
 		operation,
+		params,
 		runs,
 		warmup,
 	};
@@ -411,7 +443,18 @@ function isSchema(value: unknown): value is { parse(input: unknown): unknown } {
 function resolveInputTemplate(
 	provider: ProviderDefinition,
 	inputSchema: { parse(input: unknown): unknown },
+	params: string | undefined,
 ): unknown {
+	if (params !== undefined) {
+		try {
+			return inputSchema.parse(JSON.parse(params));
+		} catch (error) {
+			throw new Error(
+				`Failed to parse --params JSON or validate input: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		}
+	}
+
 	const firstOp = Object.values(provider.operations)[0];
 	if (firstOp?.fixtures?.request !== undefined) {
 		return firstOp.fixtures.request;
@@ -647,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,
+		}),
 	};
 }
 
@@ -724,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.",
@@ -732,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",
+				},
+			);
+		},
 	};
 }
 
@@ -1095,7 +1175,7 @@ function cloneValue<T>(value: T): T {
 
 function handleCliError(error: unknown): never {
 	const message = error instanceof Error ? error.message : String(error);
-	console.error(message);
+	console.error(`[apifuse perf] ${message}`);
 	process.exit(1);
 }