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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.2",
+	"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",

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

@@ -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,6 +572,8 @@ function renderPackageJson(input: {
 			scripts: {
 				dev: "apifuse dev .",
 				check: "apifuse check .",
+				"submit-check":
+					"apifuse submit-check . --markdown submission-report.md",
 				test: "apifuse test .",
 				record: "apifuse record .",
 				"perf:sample": "apifuse perf . --operation ping --runs 3",

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

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);

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;