@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.5

package/AUTHORING.md

@@ -18,6 +18,59 @@
 
 Provider code is the declaration input to the internal platform registry. The public SDK owns provider authoring/runtime ergonomics; internal docs, deploy, and discovery projections are built downstream from those declarations. `bun run lint:providers` enforces provider authoring standards.
 
+### User-input round-trips: never dead-end (`needs_input`)
+
+A mutation MUST NOT fail for a problem the end user can resolve by choosing among live options (a required menu/course selection, a form question, a stale-but-recoverable state token). Throwing an error there strands the consuming agent: consumer error-shaping layers routinely strip error metadata, and a model that only sees "error" narrates failure to the user instead of relaying the choice.
+
+Return the official success-shaped contract from `src/user-input.ts` instead (`ProviderNeedsInputPayload`, guard `isProviderNeedsInputPayload`):
+
+- `status: "needs_input"` plus `required_selections` — only the still-pending questions, with human-readable `label`s and `valid_options` the agent relays verbatim. The agent never chooses for the user; anything with no real choice (agreement checkboxes, single-option required groups) is the provider's job to auto-answer.
+- `selected_options` — selections already settled, echoed so the retry keeps them (copy them back and add the user's new answers).
+- a freshly minted provider state token in the same response, so the retry never races an expired token.
+
+No retry templates, next-action routing, or other agent choreography: provider payloads carry upstream-backed data only, and the consumer owns how the ask is phrased and how the retry call is shaped.
+
+Declare the union in the operation `output` schema (`z.union([CreatedSchema, NeedsInputSchema])`). Reserve hard errors for genuinely unrecoverable flows (payment-gated, unsupported input kinds) and state the concrete reason in the error `message` itself, not only in `details`. Reference implementation: `providers/catchtable` `reserve` in the platform monorepo.
+
+### Attempt tokens: the server carries the decisions
+
+When a mutation needs more than one user decision (or one decision plus a
+final go/no-go), do not make the agent re-send accumulated state across
+rounds — weak models drop or corrupt it. Split the operation into a
+**prepare/confirm pair** driven by a server-held attempt record:
+
+- The prepare operation is non-destructive. A start call takes only the
+  scalar intent fields; every response returns a fresh `attempt_token`
+  referencing a server-side record (`ctx.choice.issue` with
+  `storage.mode: "server"`) that stores every settled decision. Continue
+  calls take `attempt_token` plus only the NEW answers.
+- `needs_input` rounds list only the still-pending selections; settled
+  decisions may ride along in a display-only field but are never re-sent.
+- When nothing is pending, the prepare operation returns `status: "ready"`
+  with a human-readable summary — the consumer's user-facing confirmation.
+- The confirm operation is the only mutation and takes exactly
+  `{attempt_token}`. It re-validates everything live before executing and
+  returns `needs_input` (fresh token) instead of proceeding when upstream
+  drift invalidates a stored decision — never substitute a different option
+  for what the user picked.
+- Expired or foreign tokens fail factually (nothing happened; start a new
+  attempt with the scalar fields) — no answer salvage from a dead token.
+- **The provider must enforce consumption itself.** `ctx.choice` server
+  storage keeps tokens parseable until TTL — `parse` does not invalidate
+  them, so a confirm handler that only parses can be replayed into a second
+  booking or payment. After a successful execution, record the result under
+  the token's digest in `ctx.state` and make replays idempotent: a repeated
+  confirm returns the original created payload without touching upstream,
+  and later prepare rounds on the consumed token fail factually with the
+  existing reference. Record the result only after upstream success, so an
+  interrupted confirm stays retryable.
+
+The invariant behind all of it: complex flow state is the system's job, not
+the model's. The model carries exactly one opaque key between calls.
+Reference implementations: `providers/catchtable` `reserve`/`reserve-confirm`
+(including the consume-on-success guard) and `providers/modu-parking`
+payment state tokens in the platform monorepo.
+
 ### Description template
 
 Every operation `description` MUST be at least 150 characters and follow this structure:

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.5
+
+- Release candidate for main commit 82fa14e99a9af7edd44e3196aa3f4e87b4699edf.
+
+## 2.2.0-beta.4
+
+- Release candidate for main commit 73f2c6ec429c2fbce8ac458a67111e4844b99178.
+
 ## 2.2.0-beta.3
 
 - Release candidate for main commit 74e8e18b502dd9b02dbf0d3e702f917570312fc0.

package/bin/apifuse-check.ts

@@ -6,9 +6,9 @@ import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
 
-import type { ProviderDefinition } from "../src";
-import { lintProvider, type ProviderLintMode } from "../src/lint";
-import { safeParseSchemaSync } from "../src/schema";
+import type { ProviderDefinition } from "../src/index.js";
+import { lintProvider, type ProviderLintMode } from "../src/lint.js";
+import { safeParseSchemaSync } from "../src/schema.js";
 
 const HELP_TEXT = `Usage: apifuse check [path]
 Example: apifuse check providers/korea-air-quality
@@ -24,9 +24,7 @@ export type RunChecksOptions = {
 	lintMode?: ProviderLintMode;
 };
 
-type SafeParseResult =
-	| { success: true; data: unknown }
-	| { success: false; error: unknown };
+type SafeParseResult = { success: true; data: unknown } | { success: false; error: unknown };
 
 export async function main() {
 	const args = normalizeArgs(process.argv.slice(2));
@@ -142,17 +140,9 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
-function collectProviderSourceFiles(
-	providerRoot: string,
-): Record<string, string> {
+function collectProviderSourceFiles(providerRoot: string): Record<string, string> {
 	const sources: Record<string, string> = {};
-	const skipDirectories = new Set([
-		".git",
-		"node_modules",
-		"dist",
-		"build",
-		".next",
-	]);
+	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);
@@ -162,10 +152,7 @@ function collectProviderSourceFiles(
 				}
 				continue;
 			}
-			if (
-				!entry.isFile() ||
-				!isScannableProviderSourceFile(path.slice(providerRoot.length + 1))
-			) {
+			if (!entry.isFile() || !isScannableProviderSourceFile(path.slice(providerRoot.length + 1))) {
 				continue;
 			}
 			sources[path.slice(providerRoot.length + 1)] = readFileSync(path, "utf8");
@@ -175,10 +162,7 @@ function collectProviderSourceFiles(
 	return sources;
 }
 
-function checkIndex(
-	indexPath: string,
-	provider: ProviderDefinition | undefined,
-): CheckResult {
+function checkIndex(indexPath: string, provider: ProviderDefinition | undefined): CheckResult {
 	if (!existsSync(indexPath)) {
 		return {
 			message: "index.ts exists and exports default defineProvider",
@@ -200,9 +184,7 @@ function checkIndex(
 	};
 }
 
-function checkOperations(
-	provider: ProviderDefinition | undefined,
-): CheckResult {
+function checkOperations(provider: ProviderDefinition | undefined): CheckResult {
 	if (!provider) {
 		return {
 			message: "All operations have handler, input, output",
@@ -277,20 +259,14 @@ function checkSchemas(provider: ProviderDefinition | undefined): CheckResult {
 			continue;
 		}
 
-		const requestResult = parseFixture(
-			operation.input,
-			operation.fixtures.request,
-		);
+		const requestResult = parseFixture(operation.input, operation.fixtures.request);
 		if (!requestResult.success) {
 			failures.push(
 				`${operationId}: request fixture invalid (${formatSchemaError(requestResult.error)})`,
 			);
 		}
 
-		const responseResult = parseFixture(
-			operation.output,
-			operation.fixtures.response,
-		);
+		const responseResult = parseFixture(operation.output, operation.fixtures.response);
 		if (!responseResult.success) {
 			failures.push(
 				`${operationId}: response fixture invalid (${formatSchemaError(responseResult.error)})`,
@@ -317,13 +293,8 @@ function checkAuthoringLint(
 		};
 	}
 
-	const diagnostics = lintProvider(
-		{ ...provider, providerSourceFiles },
-		{ mode: lintMode },
-	);
-	const errors = diagnostics.filter(
-		(diagnostic) => diagnostic.level === "error",
-	);
+	const diagnostics = lintProvider({ ...provider, providerSourceFiles }, { mode: lintMode });
+	const errors = diagnostics.filter((diagnostic) => diagnostic.level === "error");
 	const details = diagnostics.map((diagnostic) => {
 		const field = diagnostic.field ? `${diagnostic.field}: ` : "";
 		return `${diagnostic.level.toUpperCase()} ${diagnostic.rule} ${field}${diagnostic.message}`;
@@ -336,9 +307,7 @@ function checkAuthoringLint(
 	};
 }
 
-function checkProviderMetadata(
-	provider: ProviderDefinition | undefined,
-): CheckResult {
+function checkProviderMetadata(provider: ProviderDefinition | undefined): CheckResult {
 	if (!provider) {
 		return {
 			message: "Provider metadata is declared in defineProvider",
@@ -425,18 +394,12 @@ function checkPackageJson(packageJsonPath: string): CheckResult {
 	}
 }
 
-function assertProviderDefinition(
-	value: unknown,
-): ProviderDefinition | undefined {
+function assertProviderDefinition(value: unknown): ProviderDefinition | undefined {
 	return isProviderDefinition(value) ? value : undefined;
 }
 
 function isProviderDefinition(value: unknown): value is ProviderDefinition {
-	if (
-		!isRecord(value) ||
-		!isRecord(value.meta) ||
-		!isRecord(value.operations)
-	) {
+	if (!isRecord(value) || !isRecord(value.meta) || !isRecord(value.operations)) {
 		return false;
 	}
 
@@ -457,8 +420,7 @@ function hasSchemaParser(value: unknown): boolean {
 	return (
 		isRecord(value) &&
 		(typeof value.safeParse === "function" ||
-			(isRecord(value["~standard"]) &&
-				typeof value["~standard"].validate === "function"))
+			(isRecord(value["~standard"]) && typeof value["~standard"].validate === "function"))
 	);
 }
 
@@ -470,9 +432,7 @@ function formatSchemaError(error: unknown): string {
 	if (Array.isArray(error)) {
 		return error
 			.map((issue) =>
-				isRecord(issue) && typeof issue.message === "string"
-					? issue.message
-					: String(issue),
+				isRecord(issue) && typeof issue.message === "string" ? issue.message : String(issue),
 			)
 			.join(", ");
 	}

package/bin/apifuse-create.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 
-import { main as runMain } from "../src/cli/create";
+import { main as runMain } from "../src/cli/create.js";
 
 export { runMain as main };
 

package/bin/apifuse-dev.ts

@@ -2,7 +2,7 @@
 
 import { existsSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
-import type { ProviderDefinition } from "../src";
+import type { ProviderDefinition } from "../src/index.js";
 import {
 	createBrowserClient,
 	createCredentialContext,
@@ -14,10 +14,10 @@ import {
 	createSttClientFromEnv,
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
 	ProviderError,
-} from "../src";
-import { createMemoryProviderRuntimeState } from "../src/runtime/state";
-import { createTraceContext } from "../src/runtime/trace";
-import type { BrowserClient, ProviderContext } from "../src/types";
+} from "../src/index.js";
+import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
+import { createTraceContext } from "../src/runtime/trace.js";
+import type { BrowserClient, ProviderContext } from "../src/types.js";
 
 const HELP_TEXT = `Usage: apifuse dev [path]
 Example: apifuse dev providers/korea-air-quality
@@ -33,12 +33,9 @@ export async function main() {
 
 	const providerPath = resolveProviderPath(args[0] ?? ".");
 	const providerModule = await import(resolve(providerPath, "index.ts"));
-	const provider = assertProviderDefinition(
-		providerModule.default,
-		providerPath,
-	);
+	const provider = assertProviderDefinition(providerModule.default, providerPath);
 
-	const { startDevServer } = await import("../src/dev");
+	const { startDevServer } = await import("../src/dev.js");
 	const port = Number(process.env.APIFUSE__RUNTIME__PORT) || 3900;
 
 	startDevServer(provider, { port });
@@ -57,8 +54,7 @@ export async function main() {
 
 	const firstOperation = Object.keys(provider.operations)[0];
 	if (firstOperation) {
-		const sampleInput =
-			provider.operations[firstOperation]?.fixtures?.request ?? {};
+		const sampleInput = provider.operations[firstOperation]?.fixtures?.request ?? {};
 		const sampleBody = JSON.stringify({
 			requestId: `req_local_${firstOperation}`,
 			input: sampleInput,
@@ -149,9 +145,7 @@ function renderHotReloadCommand(providerPath: string, port: number): string {
 	const devEntry = resolve(providerPath, "dev.ts");
 	if (existsSync(devEntry)) {
 		const relativeDevEntry = relative(process.cwd(), devEntry) || "dev.ts";
-		const portPrefix = process.env.APIFUSE__RUNTIME__PORT
-			? `APIFUSE__RUNTIME__PORT=${port} `
-			: "";
+		const portPrefix = process.env.APIFUSE__RUNTIME__PORT ? `APIFUSE__RUNTIME__PORT=${port} ` : "";
 		return `${portPrefix}bun --hot ${relativeDevEntry}`;
 	}
 	return "rerun `apifuse dev` after edits (no dev.ts entrypoint found)";
@@ -166,40 +160,28 @@ function createUnsupportedBrowserStub(): BrowserClient {
 		engine: "playwright-stealth",
 		async close() {},
 		async newPage() {
-			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',
-				},
-			);
+			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',
+			});
 		},
 		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',
-				},
-			);
+			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',
-				},
-			);
+			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',
-				},
-			);
+			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',
+			});
 		},
 	};
 }
@@ -216,10 +198,7 @@ function createUnsupportedAuthStub() {
 	};
 }
 
-function assertProviderDefinition(
-	value: unknown,
-	providerPath: string,
-): ProviderDefinition {
+function assertProviderDefinition(value: unknown, providerPath: string): ProviderDefinition {
 	if (!isProviderDefinition(value)) {
 		throw new Error(
 			`Expected ${resolve(providerPath, "index.ts")} to export default defineProvider(...)`,
@@ -230,11 +209,7 @@ function assertProviderDefinition(
 }
 
 function isProviderDefinition(value: unknown): value is ProviderDefinition {
-	if (
-		!isRecord(value) ||
-		!isRecord(value.meta) ||
-		!isRecord(value.operations)
-	) {
+	if (!isRecord(value) || !isRecord(value.meta) || !isRecord(value.operations)) {
 		return false;
 	}
 

package/bin/apifuse-pack-smoke.ts

@@ -1,19 +1,7 @@
 #!/usr/bin/env bun
 
-import {
-	type ChildProcess,
-	execFileSync,
-	spawn,
-	spawnSync,
-} from "node:child_process";
-import {
-	existsSync,
-	mkdirSync,
-	mkdtempSync,
-	readFileSync,
-	rmSync,
-	writeFileSync,
-} from "node:fs";
+import { type ChildProcess, execFileSync, spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -41,9 +29,7 @@ const PING_RESPONSE_SCHEMA = z.object({
 
 const KEEP_TEMP = process.env.APIFUSE__PACK_SMOKE__KEEP_TEMP === "1";
 
-const tempRoot = mkdtempSync(
-	join(tmpdir(), "apifuse-provider-sdk-pack-smoke-"),
-);
+const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-smoke-"));
 const packDir = join(tempRoot, "pack");
 const consumerDir = join(tempRoot, "consumer");
 const externalWorkspaceDir = join(tempRoot, "external-workspace");
@@ -81,15 +67,7 @@ try {
 
 	run(
 		"bun",
-		[
-			cliBin,
-			"create",
-			"dx-smoke",
-			"--yes",
-			"--json",
-			"--sdk-specifier",
-			tarballSpecifier,
-		],
+		[cliBin, "create", "dx-smoke", "--yes", "--json", "--sdk-specifier", tarballSpecifier],
 		consumerDir,
 	);
 
@@ -99,11 +77,7 @@ try {
 	run("bun", ["run", "test"], generatedProviderDir);
 	assertGeneratedReadme(generatedProviderDir);
 	await smokeGeneratedDevServer(generatedProviderDir);
-	assertExternalWorkspaceTopology(
-		cliBin,
-		externalWorkspaceDir,
-		tarballSpecifier,
-	);
+	assertExternalWorkspaceTopology(cliBin, externalWorkspaceDir, tarballSpecifier);
 
 	console.log(
 		`Provider SDK packed-artifact smoke passed: ${tarballPath} -> ${generatedProviderDir}`,
@@ -148,15 +122,8 @@ function assertExternalWorkspaceTopology(
 		externalWorkspaceDir,
 	);
 
-	const generatedProviderDir = join(
-		externalWorkspaceDir,
-		"external-workspace-smoke",
-	);
-	const forbiddenProviderDir = join(
-		externalWorkspaceDir,
-		"providers",
-		"external-workspace-smoke",
-	);
+	const generatedProviderDir = join(externalWorkspaceDir, "external-workspace-smoke");
+	const forbiddenProviderDir = join(externalWorkspaceDir, "providers", "external-workspace-smoke");
 	if (!existsSync(generatedProviderDir)) {
 		throw new Error(
 			"Public create must generate a one-provider repository at <name>/ even when providers/ exists.",
@@ -168,9 +135,7 @@ function assertExternalWorkspaceTopology(
 		);
 	}
 
-	const packageJson = JSON.parse(
-		readFileSync(join(generatedProviderDir, "package.json"), "utf8"),
-	);
+	const packageJson = JSON.parse(readFileSync(join(generatedProviderDir, "package.json"), "utf8"));
 	const sdkDependency = packageJson?.dependencies?.["@apifuse/provider-sdk"];
 	if (sdkDependency !== tarballSpecifier) {
 		throw new Error(
@@ -178,9 +143,7 @@ function assertExternalWorkspaceTopology(
 		);
 	}
 	if (JSON.stringify(packageJson).includes("workspace:")) {
-		throw new Error(
-			"External bounty workspace scaffold must not contain workspace: dependencies.",
-		);
+		throw new Error("External bounty workspace scaffold must not contain workspace: dependencies.");
 	}
 
 	run("bun", ["install"], generatedProviderDir);
@@ -199,30 +162,20 @@ function assertExternalWorkspaceTopology(
 		},
 	);
 	if (monorepoAttempt.status === 0) {
-		throw new Error(
-			"--preset monorepo must reject outside the private APIFuse monorepo.",
-		);
+		throw new Error("--preset monorepo must reject outside the private APIFuse monorepo.");
 	}
 	const rejectionOutput = `${monorepoAttempt.stdout}\n${monorepoAttempt.stderr}`;
-	if (
-		!rejectionOutput.includes(
-			"Monorepo preset is internal to the APIFuse repository",
-		)
-	) {
+	if (!rejectionOutput.includes("Monorepo preset is internal to the APIFuse repository")) {
 		throw new Error(`Unexpected monorepo rejection output: ${rejectionOutput}`);
 	}
 }
 
 function packSdk(destination: string): { filename: string } {
-	const raw = execFileSync(
-		"npm",
-		["pack", "--json", "--pack-destination", destination],
-		{
-			cwd: process.cwd(),
-			encoding: "utf8",
-			stdio: ["ignore", "pipe", "inherit"],
-		},
-	);
+	const raw = execFileSync("npm", ["pack", "--json", "--pack-destination", destination], {
+		cwd: process.cwd(),
+		encoding: "utf8",
+		stdio: ["ignore", "pipe", "inherit"],
+	});
 	const parsed = PACK_RESULT_SCHEMA.parse(JSON.parse(raw));
 	const first = parsed[0];
 	if (!first) {
@@ -252,29 +205,19 @@ function run(command: string, args: string[], cwd: string): void {
 function assertGeneratedReadme(providerDir: string): void {
 	const readme = readFileSync(join(providerDir, "README.md"), "utf8");
 	if (!readme.includes('"requestId":"req_local_ping"')) {
-		throw new Error(
-			"Generated README is missing requestId in local smoke docs.",
-		);
+		throw new Error("Generated README is missing requestId in local smoke docs.");
 	}
 	if (readme.includes('"connection":null')) {
-		throw new Error(
-			"Generated README must not document connection:null for no-auth local smoke.",
-		);
+		throw new Error("Generated README must not document connection:null for no-auth local smoke.");
 	}
 	if (!readme.includes("bunx playwright install chromium")) {
-		throw new Error(
-			"Generated README is missing browser runtime troubleshooting guidance.",
-		);
+		throw new Error("Generated README is missing browser runtime troubleshooting guidance.");
 	}
 	if (!readme.includes("impit")) {
-		throw new Error(
-			"Generated README is missing impit stealth runtime guidance.",
-		);
+		throw new Error("Generated README is missing impit stealth runtime guidance.");
 	}
 	if (!readme.includes("bun run submit-check")) {
-		throw new Error(
-			"Generated README must document the submit-check pre-submission workflow.",
-		);
+		throw new Error("Generated README must document the submit-check pre-submission workflow.");
 	}
 	if (!readme.includes("bun run record -- --operation <operation>")) {
 		throw new Error(
@@ -368,9 +311,7 @@ async function waitForHttp(
 
 	while (Date.now() < deadline) {
 		if (server.exitCode !== null) {
-			throw new Error(
-				`Dev server exited early with code ${server.exitCode}\n${getOutput()}`,
-			);
+			throw new Error(`Dev server exited early with code ${server.exitCode}\n${getOutput()}`);
 		}
 
 		try {