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

package/package.json

@@ -1,94 +1,109 @@
 {
-	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.4",
-	"private": false,
-	"type": "module",
-	"description": "APIFuse Provider SDK — Build providers with zero architectural constraints",
-	"license": "MIT",
-	"main": "./src/index.ts",
-	"types": "./src/index.ts",
-	"publishConfig": {
-		"access": "public"
-	},
-	"files": [
-		"src",
-		"!src/__tests__",
-		"!src/__tests__/**",
-		"!src/**/*.test.ts",
-		"!src/index.test.ts",
-		"bin",
-		"README.md",
-		"AUTHORING.md",
-		"CHANGELOG.md",
-		"SUBMISSION.md"
-	],
-	"keywords": [
-		"apifuse",
-		"provider",
-		"sdk",
-		"api",
-		"zod",
-		"hono"
-	],
-	"bin": {
-		"apifuse": "./bin/apifuse.ts"
-	},
-	"exports": {
-		".": {
-			"default": "./src/index.ts",
-			"import": "./src/index.ts",
-			"types": "./src/index.ts"
-		},
-		"./provider": {
-			"default": "./src/provider.ts",
-			"import": "./src/provider.ts",
-			"types": "./src/provider.ts"
-		},
-		"./server": {
-			"default": "./src/server/index.ts",
-			"import": "./src/server/index.ts",
-			"types": "./src/server/index.ts"
-		},
-		"./testing": {
-			"default": "./src/testing/index.ts",
-			"import": "./src/testing/index.ts",
-			"types": "./src/testing/index.ts"
-		},
-		"./create": {
-			"default": "./src/cli/create.ts",
-			"import": "./src/cli/create.ts",
-			"types": "./src/cli/create.ts"
-		}
-	},
-	"scripts": {
-		"lint": "biome check",
-		"lint:fix": "biome lint --write",
-		"format": "biome format --write",
-		"type-check": "tsgo --noEmit",
-		"test": "bun test",
-		"check": "bun run lint && bun run type-check",
-		"pack:check": "bun bin/apifuse-pack-check.ts",
-		"pack:smoke": "bun bin/apifuse-pack-smoke.ts"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "^2.5.0",
-		"@types/bun": "latest",
-		"@types/node": "^25.9.3",
-		"typescript": "^6.0.3"
-	},
-	"dependencies": {
-		"@clack/prompts": "^1.5.1",
-		"@types/ms": "^2.1.0",
-		"ajv": "^8.17",
-		"hono": "^4.12.25",
-		"impit": "0.14.1",
-		"ioredis": "^5.11.1",
-		"ms": "^2.1.3",
-		"playwright": "^1.55.1",
-		"playwright-extra": "^4.3.6",
-		"puppeteer-extra-plugin-stealth": "^2.11.2",
-		"re2-wasm": "^1.0",
-		"safe-regex": "^2.1",
-		"zod": "^4.4.3"
-	}
+  "name": "@apifuse/provider-sdk",
+  "version": "2.1.0-beta.6",
+  "private": false,
+  "type": "module",
+  "description": "APIFuse Provider SDK \u2014 Build providers with zero architectural constraints",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/__tests__",
+    "!src/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/index.test.ts",
+    "bin",
+    "README.md",
+    "AUTHORING.md",
+    "CHANGELOG.md",
+    "SUBMISSION.md"
+  ],
+  "keywords": [
+    "apifuse",
+    "provider",
+    "sdk",
+    "api",
+    "zod",
+    "hono"
+  ],
+  "bin": {
+    "apifuse": "./bin/apifuse.ts"
+  },
+  "exports": {
+    ".": {
+      "default": "./src/index.ts",
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    },
+    "./provider": {
+      "default": "./src/provider.ts",
+      "import": "./src/provider.ts",
+      "types": "./src/provider.ts"
+    },
+    "./contract": {
+      "default": "./src/contract.ts",
+      "import": "./src/contract.ts",
+      "types": "./src/contract.ts"
+    },
+    "./server": {
+      "default": "./src/server/index.ts",
+      "import": "./src/server/index.ts",
+      "types": "./src/server/index.ts"
+    },
+    "./testing": {
+      "default": "./src/testing/index.ts",
+      "import": "./src/testing/index.ts",
+      "types": "./src/testing/index.ts"
+    },
+    "./create": {
+      "default": "./src/cli/create.ts",
+      "import": "./src/cli/create.ts",
+      "types": "./src/cli/create.ts"
+    }
+  },
+  "scripts": {
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write",
+    "format": "biome format --write",
+    "type-check": "tsgo --noEmit",
+    "test": "bun test",
+    "check": "bun run lint && bun run type-check",
+    "pack:check": "bun bin/apifuse-pack-check.ts",
+    "pack:smoke": "bun bin/apifuse-pack-smoke.ts",
+    "release:guard": "bun scripts/guard-release-pr.ts",
+    "format:check": "biome format ."
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.0",
+    "@types/bun": "latest",
+    "@types/node": "^25.9.3",
+    "@typescript/native-preview": "7.0.0-dev.20260419.1"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "@types/ms": "^2.1.0",
+    "ajv": "^8.17",
+    "hono": "^4.12.25",
+    "impit": "0.14.1",
+    "ioredis": "^5.11.1",
+    "ms": "^2.1.3",
+    "playwright": "^1.55.1",
+    "playwright-extra": "^4.3.6",
+    "puppeteer-extra-plugin-stealth": "^2.11.2",
+    "re2-wasm": "^1.0",
+    "safe-regex": "^2.1",
+    "zod": "^4.4.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/APIFuseHQ/provider-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/APIFuseHQ/provider-sdk/issues"
+  },
+  "homepage": "https://github.com/APIFuseHQ/provider-sdk#readme"
 }

package/src/ceremonies/index.ts

@@ -8,7 +8,12 @@ import {
 	TurnValidationError,
 	ValidationError,
 } from "../errors";
-import type { AuthFlowDefinition, AuthTurn, FlowContext } from "../types";
+import type {
+	AuthFlowDefinition,
+	AuthFlowInputHandler,
+	AuthTurn,
+	FlowContext,
+} from "../types";
 
 type TurnKind =
 	| "abort"
@@ -21,7 +26,7 @@ type TurnKind =
 	| "redirect"
 	| "retry";
 
-type CeremonyHandler = AuthFlowDefinition["start"];
+type CeremonyHandler = AuthFlowInputHandler;
 
 type JsonObject = Record<string, unknown>;
 
@@ -44,6 +49,7 @@ const authTurnSchema = {
 			additionalProperties: true,
 		},
 		hint: { type: "string" },
+		hintKey: { type: "string" },
 		timing: {
 			type: "object",
 			additionalProperties: false,

package/src/choice-token.ts

@@ -13,6 +13,7 @@ export type ProviderChoiceTokenErrorReason =
 	| "invalid_shape"
 	| "invalid_signature"
 	| "invalid_payload"
+	| "invalid_binding"
 	| "stale";
 
 export class ProviderChoiceTokenError extends Error {

package/src/cli/commands.ts

@@ -36,14 +36,14 @@ export const COMMAND_MANIFEST: Record<
 		summary:
 			"Start the local provider dev server with the standard provider server contract.",
 		usage: "apifuse dev [path]",
-		examples: ["apifuse dev .", "apifuse dev providers/airkorea"],
+		examples: ["apifuse dev .", "apifuse dev providers/korea-air-quality"],
 		modulePath: "./apifuse-dev",
 	},
 	check: {
 		name: "check",
 		summary: "Validate provider structure, metadata, fixtures, and schemas.",
 		usage: "apifuse check [path]",
-		examples: ["apifuse check .", "apifuse check providers/airkorea"],
+		examples: ["apifuse check .", "apifuse check providers/korea-air-quality"],
 		modulePath: "./apifuse-check",
 	},
 	"submit-check": {
@@ -72,8 +72,7 @@ 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":"종로구"}\'',
+			'apifuse record providers/korea-air-quality --operation realtime --params \'{"stationName":"종로구"}\'',
 		],
 		modulePath: "./apifuse-record",
 	},
@@ -81,17 +80,20 @@ export const COMMAND_MANIFEST: Record<
 		name: "test",
 		summary: "Run provider-focused tests and surface actionable failures.",
 		usage: "apifuse test [path] [--json] [--verbose]",
-		examples: ["apifuse test .", "apifuse test providers/airkorea --json"],
+		examples: [
+			"apifuse test .",
+			"apifuse test providers/korea-air-quality --json",
+		],
 		modulePath: "./apifuse-test",
 	},
 	perf: {
 		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/korea-air-quality --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),
@@ -494,6 +502,15 @@ export async function buildProviderCreatePlan(
 			path: resolve(providerRoot, "operations", "ping.ts"),
 			content: await renderTemplate("operations/ping.ts.tpl", {
 				DISPLAY_NAME: escapeTemplate(options.displayName),
+				HANDLER_CTX: options.runtime === "browser" ? "ctx" : "_ctx",
+				BROWSER_HANDLER_BLOCK:
+					options.runtime === "browser"
+						? '\n    const page = await ctx.browser.newPage();\n    await page.goto("https://example.com");\n    const title = await page.title();\n    const frames = await page.frames();\n    await page.close();\n'
+						: "",
+				BROWSER_RESPONSE_FIELDS:
+					options.runtime === "browser"
+						? ",\n      pageTitle: title,\n      frameCount: frames.length"
+						: "",
 			}),
 		},
 		{
@@ -574,6 +591,7 @@ export async function buildProviderCreatePlan(
 		providerRoot,
 		validationCommands: [
 			"bun run check",
+			"bun run type-check",
 			"bun run submit-check",
 			"bun run test",
 		],
@@ -605,7 +623,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 +637,7 @@ function renderPackageJson(input: {
 			},
 			devDependencies: {
 				"@types/bun": "latest",
+				typescript: "^6.0.3",
 			},
 		},
 		null,
@@ -636,6 +656,7 @@ function renderTsconfig(): string {
 				noEmit: true,
 				skipLibCheck: true,
 				resolveJsonModule: true,
+				types: ["bun"],
 			},
 			include: ["**/*.ts"],
 			exclude: ["node_modules"],
@@ -689,6 +710,14 @@ function renderStarterLocaleCatalog(
 					locale === "ko"
 						? "생성된 provider가 샘플 payload를 round-trip했음을 보여주는 사람이 읽을 수 있는 확인 메시지"
 						: "Human-readable confirmation that the generated provider round-tripped the sample payload.",
+				pageTitle:
+					locale === "ko"
+						? "browser 런타임 provider일 때 로드된 페이지의 제목 (해당되지 않으면 생략)"
+						: "Title of the loaded page when the provider uses the browser runtime; omitted otherwise.",
+				frameCount:
+					locale === "ko"
+						? "browser 런타임 provider일 때 로드된 페이지의 frame 개수 (해당되지 않으면 생략)"
+						: "Number of frames in the loaded page when the provider uses the browser runtime; omitted otherwise.",
 			},
 		},
 	};
@@ -732,6 +761,17 @@ function renderAuthBlock(authMode: CreateAuthMode): string {
         },
         hint: "Generated placeholder credential flow completed. Replace this with real auth logic.",
       }),
+      refresh: async () => ({
+        kind: "complete",
+        turnId: crypto.randomUUID(),
+        data: {
+          credential: {
+            username: "replace-with-refreshed-username",
+            password: "replace-with-refreshed-password",
+          },
+        },
+        hint: "Return refreshed credential data here, or throw AuthError with code AUTH_REQUIRED when silent refresh is not possible.",
+      }),
     },
   }`;
 		case "oauth2":
@@ -952,6 +992,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/cli/templates/provider/operations/ping.ts.tpl

@@ -6,10 +6,11 @@ export const pingOperation = defineOperation({
   descriptionKey: "operations.ping.description",
   input: pingInputSchema,
   output: pingOutputSchema,
-  handler: async (_ctx, input) => {
+  handler: async ({{HANDLER_CTX}}, input) => {
+    {{BROWSER_HANDLER_BLOCK}}
     return {
       ok: true,
-      message: "{{DISPLAY_NAME}} received: " + input.value,
+      message: "{{DISPLAY_NAME}} received: " + input.value{{BROWSER_RESPONSE_FIELDS}},
     };
   },
   fixtures: {

package/src/cli/templates/provider/schemas/ping.ts.tpl

@@ -11,6 +11,14 @@ export const pingOutputSchema = describeKey(
   z.object({
     ok: describeKey(z.boolean(), "schemaDescriptions.output.ok"),
     message: describeKey(z.string(), "schemaDescriptions.output.message"),
+    pageTitle: describeKey(
+      z.string().optional(),
+      "schemaDescriptions.output.pageTitle",
+    ),
+    frameCount: describeKey(
+      z.number().int().nonnegative().optional(),
+      "schemaDescriptions.output.frameCount",
+    ),
   }),
   "schemaDescriptions.output.root",
 );

package/src/config/loader.ts

@@ -16,6 +16,8 @@ export const DEFAULT_PROXY_LIFETIME_ENV =
 	"APIFUSE__PROXY__DEFAULT_LIFETIME_MINUTES";
 export const PROVIDER_CACHE_REDIS_URL_ENV =
 	"APIFUSE__PROVIDER__CACHE_REDIS_URL";
+export const PROVIDER_STATE_REDIS_URL_ENV =
+	"APIFUSE__PROVIDER__STATE_REDIS_URL";
 export const REDIS_URL_ENV = "APIFUSE__REDIS__URL";
 
 export type ProxyOptions = {
@@ -175,6 +177,19 @@ const SMARTPROXY_EXTRACTION_SOFT_REFRESH_MS = 10_000;
 
 function redisUrlFromEnv(): string | undefined {
 	return (
+		process.env.APIFUSE__PROVIDER__CACHE_REDIS_URL?.trim() ||
+		process.env[REDIS_URL_ENV]?.trim() ||
+		undefined
+	);
+}
+
+export function providerCacheRedisUrlFromEnv(): string | undefined {
+	return redisUrlFromEnv();
+}
+
+export function providerStateRedisUrlFromEnv(): string | undefined {
+	return (
+		process.env[PROVIDER_STATE_REDIS_URL_ENV]?.trim() ||
 		process.env[PROVIDER_CACHE_REDIS_URL_ENV]?.trim() ||
 		process.env[REDIS_URL_ENV]?.trim() ||
 		undefined
@@ -620,7 +635,10 @@ function selectProxyPoolIndex(poolSize: number, attempt = 0): number {
 	if (poolSize <= 1) {
 		return 0;
 	}
-	return Math.max(0, Math.floor(attempt)) % poolSize;
+	const normalizedAttempt = Number.isFinite(attempt)
+		? Math.max(0, Math.floor(attempt))
+		: 0;
+	return normalizedAttempt % poolSize;
 }
 
 function buildSmartproxyCacheKey(

package/src/contract-json.ts

@@ -0,0 +1,75 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue =
+	| JsonPrimitive
+	| readonly JsonValue[]
+	| { readonly [key: string]: JsonValue };
+
+export function canonicalJson(value: unknown): string {
+	return JSON.stringify(canonicalize(toJsonValue(value) ?? null));
+}
+
+export function toJsonValue(value: unknown): JsonValue | undefined {
+	if (
+		value === null ||
+		typeof value === "string" ||
+		typeof value === "boolean"
+	) {
+		return value;
+	}
+	if (typeof value === "number") {
+		return Number.isFinite(value) ? value : undefined;
+	}
+	if (Array.isArray(value)) {
+		return value.flatMap((item) => {
+			const json = toJsonValue(item);
+			return json === undefined ? [] : [json];
+		});
+	}
+	if (!isRecord(value)) return undefined;
+	return compactObject(
+		Object.fromEntries(
+			Object.entries(value).flatMap(([key, item]) => {
+				const json = toJsonValue(item);
+				return json === undefined ? [] : [[key, json]];
+			}),
+		),
+	);
+}
+
+export function compactObject(
+	value: Record<string, JsonValue | undefined>,
+): JsonValue {
+	return Object.fromEntries(
+		Object.entries(value).filter((entry): entry is [string, JsonValue] => {
+			const [, item] = entry;
+			return item !== undefined;
+		}),
+	);
+}
+
+export function copyRecordWithout(
+	value: unknown,
+	ignoredKeys: ReadonlySet<string>,
+): Record<string, unknown> {
+	if (!isRecord(value)) return {};
+	return Object.fromEntries(
+		Object.entries(value).filter(([key]) => !ignoredKeys.has(key)),
+	);
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function canonicalize(value: JsonValue): JsonValue {
+	if (Array.isArray(value)) return value.map(canonicalize);
+	if (!isRecord(value)) return value;
+	return Object.fromEntries(
+		Object.entries(value)
+			.sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
+			.flatMap(([key, item]) => {
+				const json = toJsonValue(item);
+				return json === undefined ? [] : [[key, canonicalize(json)]];
+			}),
+	);
+}