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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.1",
+	"version": "2.1.0-beta.3",
 	"private": false,
 	"type": "module",
 	"description": "ApiFuse Provider SDK — Build providers with zero architectural constraints",
@@ -19,7 +19,8 @@
 		"bin",
 		"README.md",
 		"AUTHORING.md",
-		"CHANGELOG.md"
+		"CHANGELOG.md",
+		"SUBMISSION.md"
 	],
 	"keywords": [
 		"apifuse",
@@ -65,20 +66,20 @@
 		"pack:smoke": "bun bin/apifuse-pack-smoke.ts"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.12",
+		"@biomejs/biome": "^2.4.15",
 		"@types/bun": "latest",
-		"@types/node": "^25.1.0",
+		"@types/node": "^25.8.0",
 		"typescript": "^6.0.3"
 	},
 	"dependencies": {
-		"@clack/prompts": "^1.2.0",
+		"@clack/prompts": "^1.4.0",
 		"ajv": "^8.17",
-		"hono": "^4.12.14",
+		"hono": "^4.12.19",
 		"playwright": "^1.55.1",
 		"playwright-stealth": "^0.0.1",
 		"re2-wasm": "^1.0",
 		"safe-regex": "^2.1",
 		"tlsclientwrapper": "^4.2.0",
-		"zod": "^4.3.6"
+		"zod": "^4.4.3"
 	}
 }

package/src/cli/commands.ts

@@ -2,6 +2,8 @@ export type ApifuseCommandName =
 	| "create"
 	| "dev"
 	| "check"
+	| "submit-check"
+	| "bounty-check"
 	| "record"
 	| "test"
 	| "perf";
@@ -46,6 +48,26 @@ export const COMMAND_MANIFEST: Record<
 		examples: ["apifuse check .", "apifuse check providers/airkorea"],
 		modulePath: "./apifuse-check",
 	},
+	"submit-check": {
+		name: "submit-check",
+		summary:
+			"Score provider bounty submission readiness and emit checklist evidence.",
+		usage:
+			"apifuse submit-check [path] [--tier bronze|silver|gold|diamond] [--json] [--markdown <path>] [--smoke-note <text>]",
+		examples: [
+			"apifuse submit-check .",
+			"apifuse submit-check . --tier silver --markdown submission-report.md",
+		],
+		modulePath: "./apifuse-submit-check",
+	},
+	"bounty-check": {
+		name: "bounty-check",
+		summary: "Alias for submit-check.",
+		usage:
+			"apifuse bounty-check [path] [--tier bronze|silver|gold|diamond] [--json] [--markdown <path>] [--smoke-note <text>]",
+		examples: ["apifuse bounty-check . --markdown submission-report.md"],
+		modulePath: "./apifuse-submit-check",
+	},
 	record: {
 		name: "record",
 		summary: "Call a provider operation and capture upstream raw fixture data.",
@@ -81,6 +103,7 @@ export const COMMAND_ORDER: ApifuseCommandName[] = [
 	"create",
 	"dev",
 	"check",
+	"submit-check",
 	"record",
 	"test",
 	"perf",

package/src/cli/create.ts

@@ -479,7 +479,7 @@ export async function buildProviderCreatePlan(
 				RUNTIME: options.runtime,
 				BROWSER_BLOCK:
 					options.runtime === "browser"
-						? ',\n  browser: {\n    engine: "nodriver",\n  }'
+						? ',\n  browser: {\n    engine: "playwright-stealth",\n  }'
 						: "",
 				SECRETS_BLOCK: renderSecretsBlock(options.authMode),
 				CREDENTIAL_BLOCK: renderCredentialBlock(options.authMode),
@@ -538,7 +538,11 @@ export async function buildProviderCreatePlan(
 		packageName,
 		preset: options.preset,
 		providerRoot,
-		validationCommands: ["bun run check", "bun run test"],
+		validationCommands: [
+			"bun run check",
+			"bun run submit-check",
+			"bun run test",
+		],
 		workspaceRoot: resolvedWorkspaceRoot,
 	};
 }
@@ -568,9 +572,10 @@ function renderPackageJson(input: {
 			scripts: {
 				dev: "apifuse dev .",
 				check: "apifuse check .",
-				"record:sample":
-					'apifuse record . --operation ping --params \'{"value":"hello"}\'',
+				"submit-check":
+					"apifuse submit-check . --markdown submission-report.md",
 				test: "apifuse test .",
+				record: "apifuse record .",
 				"perf:sample": "apifuse perf . --operation ping --runs 3",
 				start: "bun start.ts",
 			},

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

@@ -8,6 +8,48 @@ Generated with `apifuse create`.
 bun run dev
 bun run check
 bun run test
+bun run submit-check
+```
+
+
+## Pre-submission report
+
+Before posting bounty evidence, run:
+
+```bash
+bun run submit-check
+```
+
+This writes `submission-report.md` with a review-readiness score, blockers,
+warnings, health coverage notes, fixture/schema evidence, and remediation. A
+score is not a payout guarantee; blockers must be fixed before maintainer
+review. The generated `ping` starter intentionally warns until you replace it
+with real upstream-backed Operations. The full public-only checklist is shipped
+in `node_modules/@apifuse/provider-sdk/SUBMISSION.md`.
+
+
+## Operation guide
+
+### Parameters
+
+Starter `ping` accepts `{ "value": string }`. Replace this section with each
+real operation's input schema, required fields, formats, limits, and examples
+before submitting bounty evidence.
+
+### Response
+
+Starter `ping` returns `{ "ok": boolean, "message": string }`. Replace this
+section with the normalized response fields, units, enum values, pagination,
+and upstream caveats for each real operation.
+
+### Example
+
+```json
+{
+	"requestId": "req_local_ping",
+	"input": { "value": "hello" },
+	"headers": {}
+}
 ```
 
 ## Provider server contract
@@ -21,13 +63,55 @@ bun run test
 - `POST /auth/poll`
 - `POST /auth/disconnect`
 
+## Local smoke
+
+```bash
+curl -s http://localhost:3900/health
+curl -s -X POST http://localhost:3900/v1/ping \
+  -H 'Content-Type: application/json' \
+  -d '{"requestId":"req_local_ping","input":{"value":"hello"},"headers":{}}'
+```
+
+The `POST /v1/{operation}` body is a request envelope:
+
+- `requestId` is required and can be any unique local debugging string.
+- `input` contains the operation input shape.
+- `headers` is optional.
+- `connection` is optional; omit it for no-auth/public operations. For
+  credential debugging, pass `{ "id", "mode", "secrets", "metadata",
+  "externalRef" }` with local-only secret values.
+
+Structured errors return an `error` object with `code`, `message`,
+`requestId`, and optional `details`; validation failures include field paths in
+`details`, and the `apifuse dev` terminal prints a structured provider log.
+
+## Debugging checklist
+
+- `invalid_request`: include `requestId` and `input`; omit `connection` for
+  public/no-auth operations and never send `connection: null`.
+- Credentials: declare `credential.keys`, pass local-only values through
+  `connection.secrets`, and read them with `ctx.credential`.
+- Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
+  carry returned `contextPatch` values into the next request's `context`.
+- TLS/browser runtime: if Bun blocks native dependency lifecycle scripts, run
+  `bun pm untrusted` and trust SDK dependencies such as `koffi` before debugging
+  `ctx.tls`; for TypeScript browser Providers use
+  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only),
+  then install local Chromium with `bunx playwright install chromium` or set
+  `CDP_POOL_URL`.
+
 ## Next steps
 
 1. Replace the sample `ping` operation with real upstream logic.
-2. Record a real fixture with `bun run record:sample` or a provider-specific equivalent.
+2. Once the real operation declares `upstream.baseUrl` and uses `ctx.http` or
+   `ctx.tls`, record a fixture with:
+   `bun run record -- --operation <operation> --params '<json-input>'`.
 3. Replace the starter `healthCheckUnsupported` with a real `healthCheck` for read-only upstream operations when safe.
 4. Extend tests and operation metadata until the provider is bounty-ready.
 
+`apifuse record` is not expected to work with the generated local-only `ping`
+operation because it intentionally has no upstream response to capture.
+
 ## Health-check authorship
 
 Every operation must declare exactly one of:

package/src/cli/templates/provider/index.ts.tpl

@@ -4,7 +4,6 @@ const InputSchema = z
   .object({
     value: z
       .string()
-      .default("hello")
       .describe("Sample input value used to verify the generated provider scaffold is wired correctly."),
   })
   .describe("Input payload for the generated ping operation.");

package/src/define.ts

@@ -185,6 +185,96 @@ function validateOperationIds(
 			);
 	}
 }
+const OPERATION_CONTRACT_VERSION_REGEX =
+	/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const VALID_OPERATION_LIFECYCLES = [
+	"stable",
+	"beta",
+	"deprecated",
+	"removed",
+] as const;
+
+function assertNonEmptyString(
+	value: unknown,
+	field: string,
+	providerId: string,
+	operationName: string,
+): asserts value is string {
+	if (typeof value !== "string" || value.trim().length === 0) {
+		throw new ValidationError(
+			`Provider "${providerId}" operation "${operationName}" has invalid ${field}: must be a non-empty string.`,
+			{ fix: `Set ${field} to a non-empty customer-facing value.` },
+		);
+	}
+}
+
+function validateOperationContracts(
+	providerId: string,
+	operations: Record<string, ProviderOperation>,
+): void {
+	for (const [operationName, operation] of Object.entries(operations)) {
+		const contract = operation.contract;
+		if (contract === undefined) continue;
+		if (!contract || typeof contract !== "object") {
+			throw new ValidationError(
+				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.contract: must be an object.`,
+				{
+					fix: `Remove operations.${operationName}.contract or provide { version, lifecycle, deprecation }.`,
+				},
+			);
+		}
+		if (
+			contract.version !== undefined &&
+			(typeof contract.version !== "string" ||
+				!OPERATION_CONTRACT_VERSION_REGEX.test(contract.version))
+		) {
+			throw new ValidationError(
+				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.contract.version: expected semver major.minor.patch.`,
+				{ fix: `Use an operation contract version such as "1.0.0".` },
+			);
+		}
+		if (contract.lifecycle !== undefined) {
+			assertLiteralField(
+				contract.lifecycle,
+				`operations.${operationName}.contract.lifecycle`,
+				VALID_OPERATION_LIFECYCLES,
+				providerId,
+			);
+		}
+		if (
+			contract.lifecycle === "deprecated" ||
+			contract.lifecycle === "removed"
+		) {
+			if (!contract.deprecation || typeof contract.deprecation !== "object") {
+				throw new ValidationError(
+					`Provider "${providerId}" operation "${operationName}" is ${contract.lifecycle} but lacks operations.${operationName}.contract.deprecation metadata.`,
+					{
+						fix: `Add announcedAt, removalAfter, and migrationGuide to operations.${operationName}.contract.deprecation.`,
+					},
+				);
+			}
+			assertNonEmptyString(
+				contract.deprecation.announcedAt,
+				`operations.${operationName}.contract.deprecation.announcedAt`,
+				providerId,
+				operationName,
+			);
+			assertNonEmptyString(
+				contract.deprecation.removalAfter,
+				`operations.${operationName}.contract.deprecation.removalAfter`,
+				providerId,
+				operationName,
+			);
+			assertNonEmptyString(
+				contract.deprecation.migrationGuide,
+				`operations.${operationName}.contract.deprecation.migrationGuide`,
+				providerId,
+				operationName,
+			);
+		}
+	}
+}
+
 function validateOperationAnnotations(
 	providerId: string,
 	operations: Record<string, ProviderOperation>,
@@ -622,6 +712,7 @@ export function defineProvider<
 		);
 	validateOperationIds(config.id, config.operations);
 	validateOperationAnnotations(config.id, config.operations);
+	validateOperationContracts(config.id, config.operations);
 	validateOperationHealthChecks(config.id, config.operations);
 	validateProviderHealthMonitor(config.id, config.healthMonitor);
 	validateOperationFixtures(config.id, config.operations);
@@ -629,7 +720,7 @@ export function defineProvider<
 		throw new ProviderError(
 			`Provider "${config.id}" must define browser.engine when runtime is "browser"`,
 			{
-				fix: 'Add browser: { engine: "nodriver" } or another supported engine',
+				fix: 'Add browser: { engine: "playwright-stealth" } for TypeScript providers, or another supported engine for your runtime',
 			},
 		);
 	if (config.browser && config.runtime !== "browser")

package/src/index.ts

@@ -75,10 +75,13 @@ export type {
 	HttpResponse,
 	InferSchemaOutput,
 	OperationAnnotations,
+	OperationContractMetadata,
 	OperationDefinition,
+	OperationDeprecationMetadata,
 	OperationDocMeta,
 	OperationErrorCode,
 	OperationInputExample,
+	OperationLifecycle,
 	OperationRelationships,
 	ProbeInterval,
 	ProviderContext,

package/src/server/serve.ts

@@ -259,7 +259,7 @@ function publicProviderErrorMessage(error: ProviderError): string {
 	return error.message;
 }
 
-function toStatusCode(error: unknown): 400 | 404 | 500 | 502 | 504 {
+function toStatusCode(error: unknown): 400 | 404 | 429 | 500 | 502 | 504 {
 	if (error instanceof z.ZodError) {
 		return 400;
 	}
@@ -269,8 +269,17 @@ function toStatusCode(error: unknown): 400 | 404 | 500 | 502 | 504 {
 	}
 
 	if (error instanceof ProviderError) {
-		if (error.code === "NOT_FOUND" || error.code === "NO_DATA") {
-			return 404;
+		switch (error.code) {
+			case "NOT_FOUND":
+			case "not_found":
+			case "NO_DATA":
+				return 404;
+			case "RATE_LIMITED":
+			case "UPSTREAM_RATE_LIMIT":
+			case "LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR":
+				return 429;
+			case "UPSTREAM_ERROR":
+				return 502;
 		}
 
 		return 400;

package/src/types.ts

@@ -537,6 +537,25 @@ export interface ContextDeclaration {
 	keys: string[];
 }
 
+export type OperationLifecycle = "stable" | "beta" | "deprecated" | "removed";
+
+export interface OperationDeprecationMetadata {
+	announcedAt: string;
+	removalAfter: string;
+	replacement?: string;
+	migrationGuide: string;
+}
+
+export interface OperationContractMetadata {
+	/**
+	 * Callable operation contract version. Defaults to 1.0.0 for the clean
+	 * pre-GA baseline; it intentionally does not fall back to provider.version.
+	 */
+	version?: string;
+	lifecycle?: OperationLifecycle;
+	deprecation?: OperationDeprecationMetadata;
+}
+
 export interface OperationDefinition<
 	TInput extends SchemaLike = SchemaLike,
 	TOutput extends SchemaLike = SchemaLike,
@@ -548,6 +567,7 @@ export interface OperationDefinition<
 	derivations?: Record<string, string>;
 	inputExamples?: OperationInputExample[];
 	annotations?: OperationAnnotations;
+	contract?: OperationContractMetadata;
 	tags?: string[];
 	relatedOperations?: OperationRelationships;
 	input: TInput;