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

package/dist/types.js

@@ -0,0 +1,61 @@
+export const OPERATION_TIMEOUT_MS_MIN = 1;
+export const OPERATION_TIMEOUT_MS_MAX = 60_000;
+export const STREAM_HEARTBEAT_MS_MIN = 1_000;
+export const STREAM_HEARTBEAT_MS_MAX = 60_000;
+export const STREAM_IDLE_TIMEOUT_MS_MIN = 1_000;
+export const STREAM_IDLE_TIMEOUT_MS_MAX = 300_000;
+export const STREAM_MAX_DURATION_MS_MIN = 1_000;
+export const STREAM_MAX_DURATION_MS_MAX = 1_800_000;
+export const STREAM_CHUNK_BYTES_MIN = 1;
+export const STREAM_CHUNK_BYTES_MAX = 1_048_576;
+export const DEFAULT_OPERATION_TRANSPORT = {
+    kind: "json",
+};
+/**
+ * Common probe interval examples retained for discoverability/backwards
+ * compatibility. This list is not exhaustive; any positive `ms`-style duration
+ * string accepted by `@types/ms` (for example `2m`, `8h`, or `1 day`) is valid.
+ */
+export const PROBE_INTERVALS = [
+    "30s",
+    "1m",
+    "3m",
+    "5m",
+    "15m",
+    "30m",
+    "1h",
+    "2h",
+    "8h",
+    "24h",
+];
+export const HEALTH_CHECK_TIMEOUT_MS_MIN = 1;
+export const HEALTH_CHECK_TIMEOUT_MS_MAX = 60_000;
+export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN = 1;
+export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX = 60_000;
+export const HttpRetryPreset = {
+    Off: "off",
+    TransportTransient: "transport_transient",
+    SafeRead: "safe_read",
+    AggressiveRead: "aggressive_read",
+    RateLimitAware: "rate_limit_aware",
+};
+export const HttpRetryJitter = {
+    None: "none",
+    Full: "full",
+    Equal: "equal",
+};
+export const HttpRetryDelayStrategy = {
+    Fixed: "fixed",
+    Exponential: "exponential",
+};
+export const HttpRetryAfterPolicy = {
+    Ignore: "ignore",
+    /** Honor Retry-After up to maxDelayMs. */
+    Respect: "respect",
+    /** Honor Retry-After but also cap it to the SDK-computed backoff delay. */
+    Cap: "cap",
+};
+export const HttpRetryUnsafeMethodPolicy = {
+    Reject: "reject",
+    AllowExplicitUnsafe: "allow_explicit_unsafe",
+};

package/dist/utils/date.d.ts

@@ -0,0 +1,6 @@
+/** Convert various date formats to ISO 8601 string */
+export declare function toISODate(v: unknown, timezone: string): string;
+/** Get today's date as ISO 8601 string in given timezone */
+export declare function today(timezone: string): string;
+/** Get current hour as string in given timezone */
+export declare function currentHour(timezone: string): string;

package/dist/utils/date.js

@@ -0,0 +1,101 @@
+function getDateParts(date, timezone) {
+    const formatter = new Intl.DateTimeFormat("en-CA", {
+        timeZone: timezone,
+        hour12: false,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+    });
+    const parts = Object.fromEntries(formatter.formatToParts(date).map((part) => [part.type, part.value]));
+    return {
+        year: parts.year,
+        month: parts.month,
+        day: parts.day,
+        hour: parts.hour,
+        minute: parts.minute,
+        second: parts.second,
+    };
+}
+function getTimezoneOffsetMinutes(date, timezone) {
+    const parts = getDateParts(date, timezone);
+    const asUTC = Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour), Number(parts.minute), Number(parts.second));
+    return (asUTC - date.getTime()) / 60000;
+}
+function buildUtcInstantFromLocalParts(year, month, day, hour, minute, second, timezone) {
+    const guess = Date.UTC(year, month - 1, day, hour, minute, second);
+    let utc = guess;
+    for (let i = 0; i < 2; i += 1) {
+        const offset = getTimezoneOffsetMinutes(new Date(utc), timezone);
+        const nextUtc = guess - offset * 60_000;
+        if (nextUtc === utc) {
+            break;
+        }
+        utc = nextUtc;
+    }
+    return new Date(utc);
+}
+function formatOffset(offsetMinutes) {
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const abs = Math.abs(offsetMinutes);
+    const hours = String(Math.floor(abs / 60)).padStart(2, "0");
+    const minutes = String(abs % 60).padStart(2, "0");
+    return `${sign}${hours}:${minutes}`;
+}
+function formatIso(date, timezone) {
+    const parts = getDateParts(date, timezone);
+    const offset = getTimezoneOffsetMinutes(date, timezone);
+    return `${parts.year}-${parts.month}-${parts.day}T${parts.hour}:${parts.minute}:${parts.second}${formatOffset(offset)}`;
+}
+function parseDateValue(v, timezone) {
+    if (v instanceof Date) {
+        return Number.isNaN(v.getTime()) ? null : v;
+    }
+    if (typeof v === "number") {
+        const date = new Date(v);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
+    if (typeof v !== "string") {
+        return null;
+    }
+    const value = v.trim();
+    if (value === "") {
+        return null;
+    }
+    const compactDate = /^(\d{4})(\d{2})(\d{2})$/;
+    const compactDateTime = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})?$/;
+    const dashedDate = /^(\d{4})-(\d{2})-(\d{2})$/;
+    let match = value.match(compactDateTime);
+    if (match) {
+        const [, year, month, day, hour, minute, second = "00"] = match;
+        return buildUtcInstantFromLocalParts(Number(year), Number(month), Number(day), Number(hour), Number(minute), Number(second), timezone);
+    }
+    match = value.match(compactDate);
+    if (match) {
+        const [, year, month, day] = match;
+        return buildUtcInstantFromLocalParts(Number(year), Number(month), Number(day), 0, 0, 0, timezone);
+    }
+    match = value.match(dashedDate);
+    if (match) {
+        const [, year, month, day] = match;
+        return buildUtcInstantFromLocalParts(Number(year), Number(month), Number(day), 0, 0, 0, timezone);
+    }
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+/** Convert various date formats to ISO 8601 string */
+export function toISODate(v, timezone) {
+    const date = parseDateValue(v, timezone);
+    return date ? formatIso(date, timezone) : "";
+}
+/** Get today's date as ISO 8601 string in given timezone */
+export function today(timezone) {
+    const parts = getDateParts(new Date(), timezone);
+    return `${parts.year}-${parts.month}-${parts.day}`;
+}
+/** Get current hour as string in given timezone */
+export function currentHour(timezone) {
+    return getDateParts(new Date(), timezone).hour;
+}

package/dist/utils/parse.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Unwrap nested envelope by dot-path
+ * e.g., unwrapEnvelope({response: {body: {items: [...]}}}, 'response.body.items')
+ */
+export declare function unwrapEnvelope(data: unknown, path?: string): unknown;
+/**
+ * Pivot array by field — generalized version of pivotByCategory
+ * e.g., pivotByField([{type:'A', val:1},{type:'B', val:2}], 'type', 'val')
+ * → { A: 1, B: 2 }
+ */
+export declare function pivotByField(items: unknown[], keyField: string, valueField: string): Record<string, unknown>;
+/**
+ * Parse XML items from string — returns array
+ * Uses simple regex (no DOM), suitable for structured XML
+ */
+export declare function parseXmlItems(xml: string, tag: string): string[];

package/dist/utils/parse.js

@@ -0,0 +1,51 @@
+/**
+ * Unwrap nested envelope by dot-path
+ * e.g., unwrapEnvelope({response: {body: {items: [...]}}}, 'response.body.items')
+ */
+export function unwrapEnvelope(data, path) {
+    if (!path || path.trim() === "") {
+        return data;
+    }
+    const segments = path.split(".").filter(Boolean);
+    let current = data;
+    for (const segment of segments) {
+        if (!current || typeof current !== "object") {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Pivot array by field — generalized version of pivotByCategory
+ * e.g., pivotByField([{type:'A', val:1},{type:'B', val:2}], 'type', 'val')
+ * → { A: 1, B: 2 }
+ */
+export function pivotByField(items, keyField, valueField) {
+    const result = {};
+    for (const item of items) {
+        if (!item || typeof item !== "object") {
+            continue;
+        }
+        const record = item;
+        const key = record[keyField];
+        const value = record[valueField];
+        if (key === undefined || key === null || value === undefined) {
+            continue;
+        }
+        result[String(key)] = value;
+    }
+    return result;
+}
+/**
+ * Parse XML items from string — returns array
+ * Uses simple regex (no DOM), suitable for structured XML
+ */
+export function parseXmlItems(xml, tag) {
+    const matches = [
+        ...xml.matchAll(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`, "gi")),
+    ];
+    return matches
+        .map((match) => match[1].replace(/<[^>]+>/g, "").trim())
+        .filter((item) => item.length > 0);
+}

package/dist/utils/text.d.ts

@@ -0,0 +1,4 @@
+/** Remove HTML tags from string */
+export declare function stripHtml(html: string): string;
+/** Truncate string to maxLength with optional suffix */
+export declare function truncate(str: string, maxLength: number, suffix?: string): string;

package/dist/utils/text.js

@@ -0,0 +1,14 @@
+/** Remove HTML tags from string */
+export function stripHtml(html) {
+    return html
+        .replace(/<[^>]*>/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** Truncate string to maxLength with optional suffix */
+export function truncate(str, maxLength, suffix = "...") {
+    if (str.length <= maxLength) {
+        return str;
+    }
+    return `${str.slice(0, maxLength)}${suffix}`;
+}

package/dist/utils/transform.d.ts

@@ -0,0 +1,8 @@
+/** Parse any value to number (returns 0 if not parseable) */
+export declare function toNumber(v: unknown): number;
+/** Parse any value to float */
+export declare function toFloat(v: unknown, decimals?: number): number;
+/** Parse any value to integer */
+export declare function toInt(v: unknown): number;
+/** Parse any value to boolean (handles "true", "1", "yes", true, 1) */
+export declare function toBoolean(v: unknown): boolean;

package/dist/utils/transform.js

@@ -0,0 +1,48 @@
+/** Parse any value to number (returns 0 if not parseable) */
+export function toNumber(v) {
+    if (typeof v === "number") {
+        return Number.isFinite(v) ? v : 0;
+    }
+    if (typeof v === "boolean") {
+        return v ? 1 : 0;
+    }
+    if (typeof v === "string") {
+        const cleaned = v.replaceAll(",", "").trim();
+        if (cleaned === "") {
+            return 0;
+        }
+        const parsed = Number(cleaned);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    return 0;
+}
+/** Parse any value to float */
+export function toFloat(v, decimals) {
+    const parsed = toNumber(v);
+    if (!Number.isFinite(parsed)) {
+        return 0;
+    }
+    if (decimals === undefined) {
+        return parsed;
+    }
+    const factor = 10 ** decimals;
+    return Math.round(parsed * factor) / factor;
+}
+/** Parse any value to integer */
+export function toInt(v) {
+    return Math.round(toNumber(v));
+}
+/** Parse any value to boolean (handles "true", "1", "yes", true, 1) */
+export function toBoolean(v) {
+    if (typeof v === "boolean") {
+        return v;
+    }
+    if (typeof v === "number") {
+        return v === 1;
+    }
+    if (typeof v === "string") {
+        const normalized = v.trim().toLowerCase();
+        return ["true", "1", "yes", "y"].includes(normalized);
+    }
+    return false;
+}

package/package.json

@@ -1,16 +1,17 @@
 {
 	"name": "@apifuse/provider-sdk",
-	"version": "2.1.0-beta.1",
+	"version": "2.1.0-beta.10",
 	"private": false,
 	"type": "module",
-	"description": "ApiFuse Provider SDK — Build providers with zero architectural constraints",
+	"description": "APIFuse Provider SDK — Build providers with zero architectural constraints",
 	"license": "MIT",
-	"main": "./src/index.ts",
-	"types": "./src/index.ts",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"publishConfig": {
 		"access": "public"
 	},
 	"files": [
+		"dist",
 		"src",
 		"!src/__tests__",
 		"!src/__tests__/**",
@@ -19,7 +20,8 @@
 		"bin",
 		"README.md",
 		"AUTHORING.md",
-		"CHANGELOG.md"
+		"CHANGELOG.md",
+		"SUBMISSION.md"
 	],
 	"keywords": [
 		"apifuse",
@@ -34,51 +36,76 @@
 	},
 	"exports": {
 		".": {
-			"default": "./src/index.ts",
-			"import": "./src/index.ts",
-			"types": "./src/index.ts"
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
 		},
 		"./provider": {
-			"default": "./src/provider.ts",
-			"import": "./src/provider.ts",
-			"types": "./src/provider.ts"
+			"types": "./dist/provider.d.ts",
+			"import": "./dist/provider.js",
+			"default": "./dist/provider.js"
+		},
+		"./contract": {
+			"types": "./dist/contract.d.ts",
+			"import": "./dist/contract.js",
+			"default": "./dist/contract.js"
 		},
 		"./server": {
-			"default": "./src/server/index.ts",
-			"import": "./src/server/index.ts",
-			"types": "./src/server/index.ts"
+			"types": "./dist/server/index.d.ts",
+			"import": "./dist/server/index.js",
+			"default": "./dist/server/index.js"
 		},
 		"./testing": {
-			"default": "./src/testing/index.ts",
-			"import": "./src/testing/index.ts",
-			"types": "./src/testing/index.ts"
+			"types": "./dist/testing/index.d.ts",
+			"import": "./dist/testing/index.js",
+			"default": "./dist/testing/index.js"
+		},
+		"./create": {
+			"types": "./dist/cli/create.d.ts",
+			"import": "./dist/cli/create.js",
+			"default": "./dist/cli/create.js"
 		}
 	},
 	"scripts": {
-		"lint": "biome check",
+		"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"
+		"check": "bun run lint && bun run type-check && bun run build",
+		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
+		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
+		"release:guard": "bun scripts/guard-release-pr.ts",
+		"format:check": "biome format .",
+		"build": "tsgo -p tsconfig.build.json && rm -rf dist/cli/templates && cp -R src/cli/templates dist/cli/templates"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.4.12",
+		"@biomejs/biome": "^2.5.0",
 		"@types/bun": "latest",
-		"@types/node": "^25.1.0",
-		"typescript": "^6.0.3"
+		"@types/node": "^25.9.3",
+		"@typescript/native-preview": "7.0.0-dev.20260419.1"
 	},
 	"dependencies": {
-		"@clack/prompts": "^1.2.0",
+		"@clack/prompts": "^1.5.1",
+		"@types/ms": "^2.1.0",
 		"ajv": "^8.17",
-		"hono": "^4.12.14",
+		"hono": "^4.12.25",
+		"impit": "0.14.1",
+		"ioredis": "^5.11.1",
+		"ms": "^2.1.3",
 		"playwright": "^1.55.1",
-		"playwright-stealth": "^0.0.1",
+		"playwright-extra": "^4.3.6",
+		"puppeteer-extra-plugin-stealth": "^2.11.2",
 		"re2-wasm": "^1.0",
 		"safe-regex": "^2.1",
-		"tlsclientwrapper": "^4.2.0",
-		"zod": "^4.3.6"
-	}
+		"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

@@ -0,0 +1,165 @@
+import {
+	createCipheriv,
+	createDecipheriv,
+	createHash,
+	createHmac,
+	randomBytes,
+	timingSafeEqual,
+} from "node:crypto";
+
+export type ProviderChoiceTokenPayload = Record<string, unknown>;
+
+export type ProviderChoiceTokenErrorReason =
+	| "invalid_shape"
+	| "invalid_signature"
+	| "invalid_payload"
+	| "invalid_binding"
+	| "stale";
+
+export class ProviderChoiceTokenError extends Error {
+	readonly reason: ProviderChoiceTokenErrorReason;
+
+	constructor(reason: ProviderChoiceTokenErrorReason, message: string) {
+		super(message);
+		this.name = "ProviderChoiceTokenError";
+		this.reason = reason;
+	}
+}
+
+export interface CreateProviderChoiceTokenOptions<
+	TPayload extends ProviderChoiceTokenPayload,
+> {
+	prefix: string;
+	payload: TPayload;
+	secret: string;
+}
+
+export interface ParseProviderChoiceTokenOptions {
+	token: string;
+	prefix: string;
+	secret: string;
+}
+
+export interface FreshProviderChoiceIssuedAtOptions {
+	ttlMs: number;
+	nowMs?: number;
+	futureToleranceMs?: number;
+}
+
+export function createProviderChoiceToken<
+	TPayload extends ProviderChoiceTokenPayload,
+>(options: CreateProviderChoiceTokenOptions<TPayload>): string {
+	const iv = randomBytes(12);
+	const cipher = createCipheriv(
+		"aes-256-gcm",
+		choiceEncryptionKey(options.secret),
+		iv,
+	);
+	const encryptedPayload = Buffer.concat([
+		cipher.update(JSON.stringify(options.payload), "utf8"),
+		cipher.final(),
+	]).toString("base64url");
+	const authTag = cipher.getAuthTag().toString("base64url");
+	const encodedIv = iv.toString("base64url");
+	const signature = signProviderChoiceTokenBody(
+		`${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}`,
+		options.secret,
+	);
+	return `${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}.${signature}`;
+}
+
+export function parseProviderChoiceToken(
+	options: ParseProviderChoiceTokenOptions,
+): ProviderChoiceTokenPayload {
+	const [
+		actualPrefix,
+		encodedIv,
+		encryptedPayload,
+		authTag,
+		signature,
+		...extra
+	] = options.token.split(".");
+	if (
+		actualPrefix !== options.prefix ||
+		!encodedIv ||
+		!encryptedPayload ||
+		!authTag ||
+		!signature ||
+		extra.length > 0
+	) {
+		throw new ProviderChoiceTokenError(
+			"invalid_shape",
+			"Provider choice token shape is invalid.",
+		);
+	}
+
+	const signedBody = `${options.prefix}.${encodedIv}.${encryptedPayload}.${authTag}`;
+	const expectedSignature = signProviderChoiceTokenBody(
+		signedBody,
+		options.secret,
+	);
+	const actualBuffer = Buffer.from(signature);
+	const expectedBuffer = Buffer.from(expectedSignature);
+	if (
+		actualBuffer.length !== expectedBuffer.length ||
+		!timingSafeEqual(actualBuffer, expectedBuffer)
+	) {
+		throw new ProviderChoiceTokenError(
+			"invalid_signature",
+			"Provider choice token signature is invalid.",
+		);
+	}
+
+	try {
+		const decipher = createDecipheriv(
+			"aes-256-gcm",
+			choiceEncryptionKey(options.secret),
+			Buffer.from(encodedIv, "base64url"),
+		);
+		decipher.setAuthTag(Buffer.from(authTag, "base64url"));
+		const decrypted = Buffer.concat([
+			decipher.update(Buffer.from(encryptedPayload, "base64url")),
+			decipher.final(),
+		]).toString("utf8");
+		const parsed = JSON.parse(decrypted);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+			throw new Error("payload is not an object");
+		}
+		return Object.fromEntries(Object.entries(parsed));
+	} catch {
+		throw new ProviderChoiceTokenError(
+			"invalid_payload",
+			"Provider choice token payload is invalid.",
+		);
+	}
+}
+
+export function assertFreshProviderChoiceIssuedAt(
+	issuedAtMs: unknown,
+	options: FreshProviderChoiceIssuedAtOptions,
+): number {
+	const parsed =
+		typeof issuedAtMs === "number" ? issuedAtMs : Number(issuedAtMs);
+	const nowMs = options.nowMs ?? Date.now();
+	const futureToleranceMs = options.futureToleranceMs ?? 30_000;
+	if (
+		!Number.isFinite(parsed) ||
+		parsed <= 0 ||
+		nowMs - parsed > options.ttlMs ||
+		parsed - nowMs > futureToleranceMs
+	) {
+		throw new ProviderChoiceTokenError(
+			"stale",
+			"Provider choice token is stale.",
+		);
+	}
+	return parsed;
+}
+
+function choiceEncryptionKey(secret: string): Buffer {
+	return createHash("sha256").update(secret).digest();
+}
+
+function signProviderChoiceTokenBody(body: string, secret: string): string {
+	return createHmac("sha256", secret).update(body).digest("base64url");
+}