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

package/package.json

@@ -1,94 +1,109 @@
 {
-	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.5",
-	"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,7 +72,7 @@ export const COMMAND_MANIFEST: Record<
 		usage:
 			'apifuse record [path] --operation <operation> --params \'{"value":"hello"}\'',
 		examples: [
-			'apifuse record providers/airkorea --operation realtime --params \'{"stationName":"종로구"}\'',
+			'apifuse record providers/korea-air-quality --operation realtime --params \'{"stationName":"종로구"}\'',
 		],
 		modulePath: "./apifuse-record",
 	},
@@ -80,7 +80,10 @@ 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: {
@@ -90,7 +93,7 @@ export const COMMAND_MANIFEST: Record<
 		usage:
 			"apifuse perf <path> --operation <operation> [--params '<json>'] [options]",
 		examples: [
-			'apifuse perf providers/airkorea --operation realtime --params \'{"stationName":"종로구"}\' --runs 5',
+			'apifuse perf providers/korea-air-quality --operation realtime --params \'{"stationName":"종로구"}\' --runs 5',
 		],
 		modulePath: "./apifuse-perf",
 	},

package/src/cli/create.ts

@@ -502,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"
+						: "",
 			}),
 		},
 		{
@@ -701,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.",
 			},
 		},
 	};
@@ -744,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":

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)]];
+			}),
+	);
+}

package/src/contract-serialization.ts

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { type ZodType, z } from "zod";
+import {
+	canonicalJson,
+	compactObject,
+	isRecord,
+	type JsonValue,
+	toJsonValue,
+} from "./contract-json";
+import type { SchemaLike } from "./types";
+
+export function describeSchema(schema: SchemaLike): JsonValue {
+	if (isZodSchema(schema)) {
+		const jsonSchema = zodJsonSchema(schema);
+		return compactObject({
+			kind: "schema",
+			vendor: "zod",
+			typeName: getSchemaTypeName(schema),
+			jsonSchema,
+			jsonSchemaHash:
+				jsonSchema === undefined
+					? undefined
+					: digest(canonicalJson(jsonSchema)),
+		});
+	}
+	const standard = isRecord(schema) ? schema["~standard"] : undefined;
+	if (isRecord(standard)) {
+		return compactObject({
+			kind: "schema",
+			standard: "standard-schema-v1",
+			vendor: typeof standard.vendor === "string" ? standard.vendor : "unknown",
+			version:
+				typeof standard.version === "number" ||
+				typeof standard.version === "string"
+					? standard.version
+					: undefined,
+		});
+	}
+	return compactObject({
+		kind: "schema",
+		vendor: "zod",
+		typeName: getSchemaTypeName(schema),
+	});
+}
+
+export function serializeSmsMatcher(
+	value: Record<string, unknown>,
+): Record<string, unknown> {
+	const code = value.code;
+	if (!isRecord(code)) return value;
+	const pattern = code.pattern;
+	if (!(pattern instanceof RegExp)) return value;
+	return {
+		...value,
+		code: {
+			...code,
+			pattern: {
+				source: pattern.source,
+				flags: pattern.flags,
+			},
+		},
+	};
+}
+
+function digest(value: string): string {
+	return createHash("sha256").update(value).digest("hex");
+}
+
+function isZodSchema(schema: SchemaLike): schema is ZodType {
+	return schema instanceof z.ZodType;
+}
+
+function zodJsonSchema(schema: ZodType): JsonValue | undefined {
+	try {
+		const jsonSchema = z.toJSONSchema(schema);
+		return toJsonValue(jsonSchema);
+	} catch (error) {
+		if (error instanceof Error) return undefined;
+		throw error;
+	}
+}
+
+function getSchemaTypeName(schema: SchemaLike): string | undefined {
+	if (!isRecord(schema)) return undefined;
+	const def = schema._def;
+	if (!isRecord(def)) return undefined;
+	const typeName = def.typeName ?? def.type;
+	return typeof typeName === "string" ? typeName : undefined;
+}

package/src/contract-types.ts

@@ -0,0 +1,52 @@
+import type { JsonValue } from "./contract-json";
+import type { ProviderDefinition } from "./types";
+
+export const PROVIDER_CONTRACT_SCHEMA_VERSION = "2026-06-23";
+
+export interface ProviderContractSnapshot {
+	readonly schemaVersion: typeof PROVIDER_CONTRACT_SCHEMA_VERSION;
+	readonly provider: {
+		readonly id: string;
+		readonly version: string;
+		readonly runtime: ProviderDefinition["runtime"];
+	};
+	readonly allowedHosts?: readonly string[];
+	readonly stealth?: JsonValue;
+	readonly proxy?: JsonValue;
+	readonly stt?: JsonValue;
+	readonly browser?: JsonValue;
+	readonly auth?: JsonValue;
+	readonly reviewed?: JsonValue;
+	readonly access?: JsonValue;
+	readonly secrets?: JsonValue;
+	readonly credential?: JsonValue;
+	readonly context?: JsonValue;
+	readonly meta: JsonValue;
+	readonly healthMonitor?: JsonValue;
+	readonly healthJourneys?: readonly JsonValue[];
+	readonly operations: readonly ProviderContractOperation[];
+}
+
+export interface ProviderContractOperation {
+	readonly id: string;
+	readonly descriptionKey?: JsonValue;
+	readonly docs?: JsonValue;
+	readonly whenToUseKeys?: JsonValue;
+	readonly whenNotToUseKeys?: JsonValue;
+	readonly derivations?: JsonValue;
+	readonly inputExamples?: JsonValue;
+	readonly annotations?: JsonValue;
+	readonly contract?: JsonValue;
+	readonly tags?: JsonValue;
+	readonly relatedOperations?: JsonValue;
+	readonly toolRouter?: JsonValue;
+	readonly observability?: JsonValue;
+	readonly transport?: JsonValue;
+	readonly inputSchema: JsonValue;
+	readonly outputSchema: JsonValue;
+	readonly fixtures?: JsonValue;
+	readonly upstream?: JsonValue;
+	readonly hints?: JsonValue;
+	readonly healthCheck?: JsonValue;
+	readonly healthCheckUnsupported?: JsonValue;
+}