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

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,109 +1,111 @@
 {
-  "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"
+	"name": "@apifuse/provider-sdk",
+	"version": "2.1.0-beta.9",
+	"private": false,
+	"type": "module",
+	"description": "APIFuse Provider SDK — Build providers with zero architectural constraints",
+	"license": "MIT",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"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": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./provider": {
+			"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": {
+			"types": "./dist/server/index.d.ts",
+			"import": "./dist/server/index.js",
+			"default": "./dist/server/index.js"
+		},
+		"./testing": {
+			"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 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 && 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"
+	},
+	"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/runtime/stealth.ts

@@ -340,7 +340,8 @@ export async function normalizeResponse(
 	const cookies = new CookieJarImpl(
 		setCookieHeadersFromResponse(response.headers),
 	);
-	const body = await response.text();
+	const bodyBytes = await response.arrayBuffer();
+	const body = new TextDecoder().decode(bodyBytes);
 
 	return {
 		status: response.status,
@@ -352,6 +353,12 @@ export async function normalizeResponse(
 		json<T>(): Promise<T> {
 			return Promise.resolve(JSON.parse(body));
 		},
+		arrayBuffer(): Promise<ArrayBuffer> {
+			return Promise.resolve(bodyBytes.slice(0));
+		},
+		bytes(): Promise<Uint8Array> {
+			return Promise.resolve(new Uint8Array(bodyBytes.slice(0)));
+		},
 	};
 }
 

package/src/types.ts

@@ -1015,6 +1015,8 @@ export interface DeclarativeStealthResponse {
 	tlsInfo?: { protocol?: string; cipher?: string; [key: string]: unknown };
 	cookies: CookieJar;
 	json<T>(): Promise<T>;
+	arrayBuffer(): Promise<ArrayBuffer>;
+	bytes(): Promise<Uint8Array>;
 }
 
 export type StealthResponse = DeclarativeStealthResponse;