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

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,10 @@
 # @apifuse/provider-sdk Changelog
 
+## 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/airkorea --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/airkorea --operation realtime --params '{"stationName":"종로구"}'
 ```
 
 `apifuse record` is for real upstream-backed operations that declare

package/bin/apifuse-perf.ts

@@ -43,6 +43,7 @@ type CliArgs = {
 	exportPath?: string;
 	flame: boolean;
 	operation: string;
+	params?: string;
 	runs: number;
 	warmup: number;
 };
@@ -81,6 +82,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/airkorea --operation realtime --params '{"stationName":"jongno"}' --runs 5`;
 
 export async function main() {
 	try {
@@ -94,7 +110,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 +204,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 +222,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 +248,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 +336,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 +346,7 @@ function parseArgs(argv: string[]): CliArgs {
 		exportPath,
 		flame,
 		operation,
+		params,
 		runs,
 		warmup,
 	};
@@ -411,7 +441,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;
@@ -1095,7 +1136,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);
 }
 

package/bin/apifuse-record.ts

@@ -15,7 +15,10 @@ import {
 	type HttpClient,
 	type ProviderContext,
 	type ProviderDefinition,
+	ProviderError,
 	type StealthClient,
+	TransportError,
+	ValidationError,
 } from "../src";
 
 type CliArgs = {
@@ -30,56 +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(
-		provider,
-		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,
+		);
 
-	void result;
+		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;
+	} catch (error) {
+		handleCliError(error);
+	}
 }
 
 function normalizeArgs(argv: string[]): string[] {
@@ -107,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;
@@ -158,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);

package/bin/apifuse-submit-check.ts

@@ -240,6 +240,7 @@ export async function buildSubmitCheckReport(
 		checks.push(scoreAuthSafety(provider));
 		checks.push(scoreSmokeEvidence(args.smokeNote));
 		checks.push(...scoreProviderDocs(providerRoot));
+		checks.push(scoreRepositoryDx(providerRoot));
 		checks.push(scoreSecrets(providerRoot));
 	} else {
 		checks.push(
@@ -287,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);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.4",
+	"version": "2.1.0-beta.5",
 	"private": false,
 	"type": "module",
 	"description": "APIFuse Provider SDK — Build providers with zero architectural constraints",

package/src/cli/commands.ts

@@ -72,7 +72,6 @@ export const COMMAND_MANIFEST: Record<
 		usage:
 			'apifuse record [path] --operation <operation> --params \'{"value":"hello"}\'',
 		examples: [
-			'apifuse record . --operation ping --params \'{"value":"hello"}\'',
 			'apifuse record providers/airkorea --operation realtime --params \'{"stationName":"종로구"}\'',
 		],
 		modulePath: "./apifuse-record",
@@ -88,10 +87,10 @@ export const COMMAND_MANIFEST: Record<
 		name: "perf",
 		summary:
 			"Profile a provider operation and export latency/trace diagnostics.",
-		usage: "apifuse perf <path> --operation <operation> [options]",
+		usage:
+			"apifuse perf <path> --operation <operation> [--params '<json>'] [options]",
 		examples: [
-			"apifuse perf . --operation ping",
-			"apifuse perf providers/airkorea --operation realtime --runs 5",
+			'apifuse perf providers/airkorea --operation realtime --params \'{"stationName":"종로구"}\' --runs 5',
 		],
 		modulePath: "./apifuse-perf",
 	},

package/src/cli/create.ts

@@ -474,6 +474,14 @@ export async function buildProviderCreatePlan(
 	};
 
 	const files: ProviderPlanFile[] = [
+		{
+			path: resolve(providerRoot, ".dockerignore"),
+			content: await renderTemplate(".dockerignore.tpl", {}),
+		},
+		{
+			path: resolve(providerRoot, ".gitignore"),
+			content: await renderTemplate(".gitignore.tpl", {}),
+		},
 		{
 			path: resolve(providerRoot, "index.ts"),
 			content: await renderTemplate("index.ts.tpl", templateValues),
@@ -574,6 +582,7 @@ export async function buildProviderCreatePlan(
 		providerRoot,
 		validationCommands: [
 			"bun run check",
+			"bun run type-check",
 			"bun run submit-check",
 			"bun run test",
 		],
@@ -605,7 +614,8 @@ function renderPackageJson(input: {
 			main: "./index.ts",
 			scripts: {
 				dev: "apifuse dev .",
-				check: "apifuse check .",
+				check: "apifuse check . && bun run type-check",
+				"type-check": "tsc --noEmit",
 				"submit-check":
 					"apifuse submit-check . --markdown submission-report.md",
 				test: "apifuse test .",
@@ -618,6 +628,7 @@ function renderPackageJson(input: {
 			},
 			devDependencies: {
 				"@types/bun": "latest",
+				typescript: "^6.0.3",
 			},
 		},
 		null,
@@ -636,6 +647,7 @@ function renderTsconfig(): string {
 				noEmit: true,
 				skipLibCheck: true,
 				resolveJsonModule: true,
+				types: ["bun"],
 			},
 			include: ["**/*.ts"],
 			exclude: ["node_modules"],
@@ -952,6 +964,14 @@ function printResult(
 		console.log(`Validation: (cd ${plan.providerRoot} && ${command})`);
 	}
 	console.log(`Next local dev: ${plan.nextDevCommand}`);
+	console.log(
+		"Submission evidence: run `bun run submit-check`, save the generated report, and note `/health` plus `POST /v1/{operation}` smoke results.",
+	);
+	if (plan.files.some((file) => file.content.includes('runtime: "browser"'))) {
+		console.log(
+			"Browser runtime: run `bunx playwright install chromium` locally or set `APIFUSE__CDP_POOL__URL` before browser-backed smoke tests.",
+		);
+	}
 }
 
 function escapeTemplate(value: string): string {

package/src/cli/templates/provider/.dockerignore.tpl

@@ -0,0 +1,22 @@
+node_modules/
+.git/
+.github/
+
+# Environment and local secrets
+.env
+.env.*
+!.env.example
+
+# Local reports and generated artifacts
+submission-report.md
+coverage/
+dist/
+.cache/
+.turbo/
+.bun/
+*.tsbuildinfo
+
+# OS/editor junk
+.DS_Store
+Thumbs.db
+*.swp

package/src/cli/templates/provider/.gitignore.tpl

@@ -0,0 +1,22 @@
+node_modules/
+
+# Environment and local secrets
+.env
+.env.*
+!.env.example
+
+# Build, coverage, cache, and local runtime artifacts
+coverage/
+dist/
+.cache/
+.turbo/
+.bun/
+*.tsbuildinfo
+
+# Bounty submission output
+submission-report.md
+
+# OS/editor junk
+.DS_Store
+Thumbs.db
+*.swp

package/src/cli/templates/provider/README.md.tpl

@@ -140,3 +140,21 @@ 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 parsed operation output. Use this shape in real operations:
+
+```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" };
+      }
+    },
+  }],
+}
+```

package/src/define.ts

@@ -181,7 +181,7 @@ type OperationMapConfig<TOperations extends Record<string, ProviderOperation>> =
 			infer TInput,
 			infer TOutput
 		>
-			? OperationConfig<TInput, TOutput>
+			? OperationConfig<TInput, TOutput> | OperationDefinition<TInput, TOutput>
 			: never;
 	};
 type StreamOperationConfig<
@@ -255,13 +255,13 @@ export interface ProviderConfig<
 		displayNameKey?: string;
 		descriptionKey: string;
 		category: string;
-		tags?: string[];
+		tags?: readonly string[];
 		icon?: string;
 		docTitleKey?: string;
 		docDescriptionKey?: string;
 		docSummaryKey?: string;
 		docMarkdownKey?: string;
-		normalizationNotesKeys?: string[];
+		normalizationNotesKeys?: readonly string[];
 		environment?: "staging";
 		purpose?: string;
 		purposeKey?: string;

package/src/lint.ts

@@ -54,7 +54,7 @@ export interface LintDiagnostic {
 
 function lintAllowedHosts(
 	providerId: string | undefined,
-	allowedHosts: string[] | undefined,
+	allowedHosts: readonly string[] | undefined,
 ): LintDiagnostic[] {
 	const prefix = providerId ? `Provider "${providerId}"` : "Provider";
 
@@ -114,7 +114,7 @@ function lintReviewed(
 	];
 }
 
-function hasReusableSecretKeys(keys: string[] | undefined): boolean {
+function hasReusableSecretKeys(keys: readonly string[] | undefined): boolean {
 	if (!keys) {
 		return false;
 	}
@@ -154,12 +154,12 @@ function lintAuthModel(provider: {
 	id?: string;
 	auth?: ProviderAuthLike;
 	credential?: {
-		keys?: string[];
+		keys?: readonly string[];
 		storesReusableSecret?: boolean;
 		justification?: string;
 	};
 	context?: {
-		keys?: string[];
+		keys?: readonly string[];
 	};
 	authFlowSource?: string;
 }): LintDiagnostic[] {
@@ -624,14 +624,14 @@ function lintStealthTransportUsage(provider: {
 export function lintOperation(op: {
 	description?: string;
 	descriptionKey?: string;
-	whenToUse?: string[];
-	whenToUseKeys?: string[];
-	whenNotToUse?: string[];
-	whenNotToUseKeys?: string[];
+	whenToUse?: readonly string[];
+	whenToUseKeys?: readonly string[];
+	whenNotToUse?: readonly string[];
+	whenNotToUseKeys?: readonly string[];
 	input: unknown;
 	output: unknown;
 	fixtures?: unknown;
-	inputExamples?: unknown[];
+	inputExamples?: readonly unknown[];
 	derivations?: Record<string, string>;
 }): LintDiagnostic[] {
 	const diagnostics: LintDiagnostic[] = [];
@@ -745,16 +745,16 @@ export function lintOperation(op: {
 
 export function lintProvider(provider: {
 	id?: string;
-	allowedHosts?: string[];
+	allowedHosts?: readonly string[];
 	stealth?: unknown;
 	auth?: ProviderAuthLike;
 	credential?: {
-		keys?: string[];
+		keys?: readonly string[];
 		storesReusableSecret?: boolean;
 		justification?: string;
 	};
 	context?: {
-		keys?: string[];
+		keys?: readonly string[];
 	};
 	authFlowSource?: string;
 	operations?: Record<
@@ -762,14 +762,14 @@ export function lintProvider(provider: {
 		{
 			description?: string;
 			descriptionKey?: string;
-			whenToUse?: string[];
-			whenToUseKeys?: string[];
-			whenNotToUse?: string[];
-			whenNotToUseKeys?: string[];
+			whenToUse?: readonly string[];
+			whenToUseKeys?: readonly string[];
+			whenNotToUse?: readonly string[];
+			whenNotToUseKeys?: readonly string[];
 			input: unknown;
 			output: unknown;
 			fixtures?: unknown;
-			inputExamples?: unknown[];
+			inputExamples?: readonly unknown[];
 			derivations?: Record<string, string>;
 			handler?: unknown;
 			source?: string;

package/src/runtime/trace.ts

@@ -64,7 +64,7 @@ type InternalTraceContext = TraceContext & {
 function buildOTLPExportOptions(
 	config?: TraceConfig,
 ): OTLPExportOptions | undefined {
-	if (!config || config.exporter !== "otlp") {
+	if (config?.exporter !== "otlp") {
 		return undefined;
 	}
 

package/src/types.ts

@@ -798,15 +798,15 @@ export interface ProviderPublicProfile {
 	longDescriptionKey?: ProviderLocaleKeyInput;
 	logo?: ProviderLogoProfile;
 	category?: string;
-	tags?: string[];
-	capabilityKeys?: ProviderLocaleKeyInput[];
-	examplePromptKeys?: ProviderLocaleKeyInput[];
+	tags?: readonly string[];
+	capabilityKeys?: readonly ProviderLocaleKeyInput[];
+	examplePromptKeys?: readonly ProviderLocaleKeyInput[];
 	setupSummaryKey?: ProviderLocaleKeyInput;
 	connectionMode?: ProviderPublicConnectionMode;
-	requirementKeys?: ProviderLocaleKeyInput[];
-	limitationKeys?: ProviderLocaleKeyInput[];
+	requirementKeys?: readonly ProviderLocaleKeyInput[];
+	limitationKeys?: readonly ProviderLocaleKeyInput[];
 	availability?: {
-		regions?: string[];
+		regions?: readonly string[];
 		supportLevel?: ProviderSupportLevel;
 	};
 	/**
@@ -823,13 +823,13 @@ export interface ProviderMeta {
 	displayNameKey?: ProviderLocaleKeyInput;
 	descriptionKey: ProviderLocaleKeyInput;
 	category: string;
-	tags?: string[];
+	tags?: readonly string[];
 	icon?: string;
 	docTitleKey?: ProviderLocaleKeyInput;
 	docDescriptionKey?: ProviderLocaleKeyInput;
 	docSummaryKey?: ProviderLocaleKeyInput;
 	docMarkdownKey?: ProviderLocaleKeyInput;
-	normalizationNotesKeys?: ProviderLocaleKeyInput[];
+	normalizationNotesKeys?: readonly ProviderLocaleKeyInput[];
 	environment?: "staging";
 	purpose?: string;
 	purposeKey?: ProviderLocaleKeyInput;
@@ -1373,13 +1373,13 @@ export interface OperationDefinition<
 > {
 	descriptionKey?: ProviderLocaleKeyInput;
 	docs?: OperationDocMeta;
-	whenToUseKeys?: ProviderLocaleKeyInput[];
-	whenNotToUseKeys?: ProviderLocaleKeyInput[];
+	whenToUseKeys?: readonly ProviderLocaleKeyInput[];
+	whenNotToUseKeys?: readonly ProviderLocaleKeyInput[];
 	derivations?: Record<string, string>;
-	inputExamples?: OperationInputExample[];
+	inputExamples?: readonly OperationInputExample[];
 	annotations?: OperationAnnotations;
 	contract?: OperationContractMetadata;
-	tags?: string[];
+	tags?: readonly string[];
 	relatedOperations?: OperationRelationships;
 	toolRouter?: OperationToolRouterMetadata;
 	observability?: OperationObservabilityConfig;
@@ -1396,6 +1396,10 @@ export interface OperationDefinition<
 		request: InferSchemaOutput<TInput>;
 		response: InferSchemaOutput<TOutput>;
 	};
+	upstream?: {
+		baseUrl?: string;
+		proxy?: boolean | ProviderProxyPolicy;
+	};
 	hints?: Record<string, string>;
 	healthCheck?: HealthCheckSuite<
 		InferSchemaOutput<TInput>,