@leavepulse/control-sdk 0.3.31

package/runtime/device.ts

@@ -0,0 +1,199 @@
+// LeavePulse SDK — OAuth device-flow (RFC 8628) polling helper.
+//
+// `auth.device.start` / `approve` / `token` are the raw generated calls. This
+// wraps the token poll loop: call `token` every `interval` seconds, back off on
+// `slow_down`, and resolve once the user approves (or reject on expiry/denial).
+// Framework-agnostic — the caller passes the poll function and the device_code.
+//
+// `beginDeviceFlow` is the higher-level headless facade: it runs `start`,
+// surfaces the user-facing URL + code, and exposes `.poll()` which honours the
+// returned interval and maps the approved grant into a RefreshingCredential.
+
+import type { RefreshFn } from "./credentials";
+import { RefreshingCredential } from "./credentials";
+
+/** The poll status the token endpoint returns (RFC 8628 §3.5). */
+export type DevicePollStatus =
+	| "approved"
+	| "pending"
+	| "slow_down"
+	| "expired"
+	| "denied";
+
+/** Minimal shape of a `auth.device.token` response the poller needs. */
+export interface DeviceTokenResponse {
+	status: DevicePollStatus;
+	access_token?: string | null;
+	token_type?: string | null;
+	expires_in?: number | null;
+	refresh_token?: string | null;
+	refresh_token_expires_in?: number | null;
+}
+
+export interface DevicePollOptions {
+	/** Initial seconds between polls (the `interval` from `start`). Default 5. */
+	intervalSeconds?: number;
+	/** Seconds added to the interval on each `slow_down`. Default 5. */
+	slowDownStepSeconds?: number;
+	/** Abort the poll loop (e.g. user cancelled). */
+	signal?: AbortSignal;
+}
+
+/** Raised when a device authorization can't complete. */
+export class DeviceFlowError extends Error {
+	constructor(readonly status: "expired" | "denied" | "aborted") {
+		super(`device authorization ${status}`);
+		this.name = "DeviceFlowError";
+	}
+}
+
+const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
+	new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new DeviceFlowError("aborted"));
+			return;
+		}
+		const timer = setTimeout(resolve, ms);
+		signal?.addEventListener(
+			"abort",
+			() => {
+				clearTimeout(timer);
+				reject(new DeviceFlowError("aborted"));
+			},
+			{ once: true },
+		);
+	});
+
+/**
+ * Poll `token` until the user approves the device. Resolves with the approved
+ * token response, or throws `DeviceFlowError` on expiry/denial/abort.
+ *
+ * @param token  a function that performs one `auth.device.token` call.
+ */
+export async function pollDeviceToken(
+	token: () => Promise<DeviceTokenResponse>,
+	options: DevicePollOptions = {},
+): Promise<DeviceTokenResponse> {
+	const step = (options.slowDownStepSeconds ?? 5) * 1000;
+	let interval = (options.intervalSeconds ?? 5) * 1000;
+	for (;;) {
+		if (options.signal?.aborted) throw new DeviceFlowError("aborted");
+		const response = await token();
+		switch (response.status) {
+			case "approved":
+				return response;
+			case "pending":
+				break;
+			case "slow_down":
+				interval += step;
+				break;
+			case "expired":
+				throw new DeviceFlowError("expired");
+			case "denied":
+				throw new DeviceFlowError("denied");
+		}
+		await sleep(interval, options.signal);
+	}
+}
+
+/** Shape of a `auth.device.start` response (RFC 8628 §3.2, wire snake_case). */
+export interface DeviceStartResponse {
+	/** Opaque code the client polls `token` with. */
+	device_code: string;
+	/** Short code the user enters in the frontend (`device.vue`). */
+	user_code: string;
+	/** URL the user opens to approve. */
+	verification_uri: string;
+	/** `verification_uri` with the `user_code` pre-filled, when provided. */
+	verification_uri_complete?: string | null;
+	/** Seconds until the device code expires. */
+	expires_in: number;
+	/** Recommended seconds between polls. */
+	interval?: number | null;
+}
+
+/** Options for {@link beginDeviceFlow}'s `.poll()`. */
+export interface BeginDeviceFlowOptions {
+	/**
+	 * Performs the refresh-token exchange for the credential returned by
+	 * `.poll()`. Omit to leave wiring to the integration layer — the returned
+	 * credential then throws if a refresh is attempted. Keep transport-agnostic.
+	 */
+	refreshFn?: RefreshFn;
+	/** Refresh this many seconds before the access token expires (default 30). */
+	leewaySeconds?: number;
+	/** Abort the poll loop (e.g. user cancelled). */
+	signal?: AbortSignal;
+	/** Override the `slow_down` interval step (default 5s). */
+	slowDownStepSeconds?: number;
+}
+
+/** A started device authorization: user-facing fields plus a `.poll()` that
+ * blocks until approval and yields a refreshing credential. */
+export interface DeviceFlowHandle {
+	/** Short code the user confirms in the frontend. */
+	readonly userCode: string;
+	/** URL the user opens to approve the device. */
+	readonly verificationUri: string;
+	/** `verificationUri` with the code pre-filled, when the server supplied it. */
+	readonly verificationUriComplete?: string;
+	/** Seconds until the device code expires. */
+	readonly expiresIn: number;
+	/** The `device_code` to poll with (exposed for advanced callers). */
+	readonly deviceCode: string;
+	/**
+	 * Poll `token` (honouring `interval`/`slow_down`/`expires_in`) until the
+	 * user approves, then resolve with a {@link RefreshingCredential} seeded
+	 * from the grant. Throws {@link DeviceFlowError} on expiry/denial/abort.
+	 */
+	poll(): Promise<RefreshingCredential>;
+}
+
+/**
+ * Begin RFC 8628 device authorization headlessly. Calls `start()`, returns the
+ * user-facing URL + code immediately, and exposes `.poll()` which runs the
+ * existing {@link pollDeviceToken} loop with the server-advised `interval` and
+ * maps the approved grant into a {@link RefreshingCredential}.
+ *
+ * @param start a function performing one `auth.device.start` call.
+ * @param poll  a function performing one `auth.device.token` call for a given
+ *              `device_code`.
+ */
+export async function beginDeviceFlow(
+	start: () => Promise<DeviceStartResponse>,
+	poll: (deviceCode: string) => Promise<DeviceTokenResponse>,
+	options: BeginDeviceFlowOptions = {},
+): Promise<DeviceFlowHandle> {
+	const started = await start();
+	const interval = started.interval ?? undefined;
+	return {
+		userCode: started.user_code,
+		verificationUri: started.verification_uri,
+		verificationUriComplete: started.verification_uri_complete ?? undefined,
+		expiresIn: started.expires_in,
+		deviceCode: started.device_code,
+		async poll(): Promise<RefreshingCredential> {
+			const approved = await pollDeviceToken(() => poll(started.device_code), {
+				intervalSeconds: interval,
+				slowDownStepSeconds: options.slowDownStepSeconds,
+				signal: options.signal,
+			});
+			if (!approved.access_token || !approved.refresh_token) {
+				throw new DeviceFlowError("denied");
+			}
+			return new RefreshingCredential({
+				accessToken: approved.access_token,
+				refreshToken: approved.refresh_token,
+				expiresIn: approved.expires_in,
+				leewaySeconds: options.leewaySeconds,
+				refreshFn:
+					options.refreshFn ??
+					(() => {
+						throw new Error(
+							"device-flow credential has no refreshFn; provide one in beginDeviceFlow options",
+						);
+					}),
+			});
+		},
+	};
+}

package/runtime/errors.ts

@@ -0,0 +1,225 @@
+// LeavePulse SDK — error hierarchy (discord.py-style).
+//
+// Every failure is a `LeavePulseError`. HTTP failures are an `HTTPException`
+// subclass chosen by status code, so callers can `catch (e) { if (e instanceof
+// NotFound) ... }`. The backend speaks RFC 7807 problem+json (service-toolkit /
+// awesome_errors), so the parsed `problem` carries the machine-readable `code`,
+// human `detail`, validation `fields`, and `requestId` for support.
+
+import type { TransportRequest } from "./transport";
+
+/** RFC 7807 problem details as emitted by the LeavePulse backend. */
+export interface ProblemDetails {
+	/** URI identifying the problem type (`urn:<service>:error:<code>`). */
+	type?: string;
+	/** Short human-readable summary. */
+	title?: string;
+	/** HTTP status code. */
+	status?: number;
+	/** Human-readable explanation specific to this occurrence. */
+	detail?: string;
+	/** URI identifying this specific occurrence. */
+	instance?: string;
+	/** Stable machine-readable error code, UPPER_SNAKE (e.g. `RESOURCE_NOT_FOUND`). */
+	code?: string;
+	/** ISO-8601 timestamp. */
+	timestamp?: string;
+	/** Correlation id for support / log lookup. */
+	requestId?: string;
+	/** Originating service name. */
+	service?: string;
+	/** Extra structured context. For validation failures it holds
+	 * `{ errors: [{ key, message, source }], path }`. */
+	details?: Record<string, unknown>;
+}
+
+/** A single per-field validation failure, normalized from the backend's
+ * `details.errors` array (Litestar's `{ key, message, source }` shape). */
+export interface FieldError {
+	/** The offending field path (e.g. `email`, `body.address.city`). */
+	field: string;
+	/** Human-readable validation message. */
+	message: string;
+	/** Where it came from: `body` | `query` | `path` | `cookie` | … */
+	source?: string;
+}
+
+/** Extract normalized per-field validation errors from a problem's `details`.
+ * The backend (awesome_errors + Litestar) reports them as
+ * `details.errors = [{ key, message, source }]`; older/other shapes
+ * (`details.fields` object, `{ loc, msg }` pydantic-style) are tolerated. */
+export function fieldErrorsOf(problem: ProblemDetails | null): FieldError[] {
+	const details = problem?.details;
+	if (!details || typeof details !== "object") return [];
+	const raw = (details as { errors?: unknown; fields?: unknown }).errors;
+
+	const fromEntry = (entry: unknown): FieldError | null => {
+		if (!entry || typeof entry !== "object") return null;
+		const e = entry as Record<string, unknown>;
+		const loc = e.key ?? e.field ?? e.path ?? e.loc;
+		const field = Array.isArray(loc) ? loc.join(".") : String(loc ?? "");
+		const message = String(e.message ?? e.msg ?? e.detail ?? "");
+		const source = e.source != null ? String(e.source) : undefined;
+		if (!field && !message) return null;
+		return { field, message, source };
+	};
+
+	if (Array.isArray(raw)) {
+		return raw.map(fromEntry).filter((x): x is FieldError => x !== null);
+	}
+	// Legacy `details.fields = { email: "msg" }` object shape.
+	const fields = (details as { fields?: unknown }).fields;
+	if (fields && typeof fields === "object" && !Array.isArray(fields)) {
+		return Object.entries(fields as Record<string, unknown>).map(
+			([field, message]) => ({ field, message: String(message) }),
+		);
+	}
+	return [];
+}
+
+/** Base class for every error the SDK raises. */
+export class LeavePulseError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = new.target.name;
+	}
+}
+
+/** The server returned a payload that doesn't match the expected shape (e.g. a
+ * resource with no id to identity-map on). Distinct from an HTTP error: the
+ * request succeeded but the body is unusable. */
+export class MalformedResponse extends LeavePulseError {
+	constructor(
+		message: string,
+		readonly payload: unknown,
+	) {
+		super(message);
+	}
+}
+
+/** Any non-2xx HTTP response. Subclasses narrow by status. */
+export class HTTPException extends LeavePulseError {
+	readonly status: number;
+	readonly request: TransportRequest;
+	readonly problem: ProblemDetails | null;
+	/** Raw response body text when it wasn't valid problem+json. */
+	readonly raw: string;
+
+	constructor(
+		status: number,
+		request: TransportRequest,
+		problem: ProblemDetails | null,
+		raw: string,
+	) {
+		const code = problem?.code ? ` [${problem.code}]` : "";
+		const detail = problem?.detail ?? problem?.title ?? raw;
+		super(
+			`${request.method} ${request.path} → ${status}${code}${detail ? `: ${detail}` : ""}`,
+		);
+		this.status = status;
+		this.request = request;
+		this.problem = problem;
+		this.raw = raw;
+	}
+
+	/** Machine-readable error code, when the server supplied one
+	 * (UPPER_SNAKE, e.g. `RESOURCE_NOT_FOUND`). */
+	get code(): string | undefined {
+		return this.problem?.code;
+	}
+
+	/** Whether the server's stable error code matches `code` — a transport-
+	 * agnostic check that survives status-code remapping (`err.is("SESSION_EXPIRED")`). */
+	is(code: string): boolean {
+		return this.problem?.code === code;
+	}
+
+	/** Correlation id for support, when present. */
+	get requestId(): string | undefined {
+		return this.problem?.requestId;
+	}
+
+	/** Normalized per-field validation errors, when the backend reported them
+	 * (populated for 400/422 validation failures). */
+	get fieldErrors(): FieldError[] {
+		return fieldErrorsOf(this.problem);
+	}
+}
+
+/** 400 — malformed request / failed validation. */
+export class BadRequest extends HTTPException {}
+
+/** 422 — semantic validation failure (the backend's primary validation status,
+ * carrying `details.errors`). Separate class so callers can target it, but it
+ * shares `fieldErrors` with `BadRequest`. */
+export class UnprocessableEntity extends HTTPException {}
+
+/** 401 — authentication required or failed. */
+export class Unauthorized extends HTTPException {}
+/** 403 — authenticated but not permitted. */
+export class Forbidden extends HTTPException {}
+/** 404 — resource not found. */
+export class NotFound extends HTTPException {}
+/** 409 — state conflict (e.g. duplicate, already-exists). */
+export class Conflict extends HTTPException {}
+
+/** 429 — rate limited. `retryAfter` is the server-advised wait in seconds. */
+export class RateLimited extends HTTPException {
+	constructor(
+		status: number,
+		request: TransportRequest,
+		problem: ProblemDetails | null,
+		raw: string,
+		readonly retryAfter: number | undefined,
+	) {
+		super(status, request, problem, raw);
+	}
+}
+
+/** 5xx — the server failed to fulfil a valid request. */
+export class ServerError extends HTTPException {}
+
+/** Parse a response body as RFC 7807 problem+json; `null` if it isn't JSON. */
+export function parseProblem(raw: string): ProblemDetails | null {
+	if (!raw) return null;
+	try {
+		const obj = JSON.parse(raw) as Record<string, unknown>;
+		if (!obj || typeof obj !== "object") return null;
+		// The wire uses snake_case (`request_id`); expose camelCase too.
+		return {
+			...obj,
+			requestId: (obj.request_id ?? obj.requestId) as string | undefined,
+		} as ProblemDetails;
+	} catch {
+		return null;
+	}
+}
+
+/** Build the right `HTTPException` subclass from a failed response. */
+export function httpErrorFor(
+	status: number,
+	request: TransportRequest,
+	raw: string,
+	retryAfter?: number,
+): HTTPException {
+	const problem = parseProblem(raw);
+	switch (status) {
+		case 400:
+			return new BadRequest(status, request, problem, raw);
+		case 401:
+			return new Unauthorized(status, request, problem, raw);
+		case 403:
+			return new Forbidden(status, request, problem, raw);
+		case 404:
+			return new NotFound(status, request, problem, raw);
+		case 409:
+			return new Conflict(status, request, problem, raw);
+		case 422:
+			return new UnprocessableEntity(status, request, problem, raw);
+		case 429:
+			return new RateLimited(status, request, problem, raw, retryAfter);
+		default:
+			if (status >= 500) return new ServerError(status, request, problem, raw);
+			return new HTTPException(status, request, problem, raw);
+	}
+}

package/runtime/etag-store.ts

@@ -0,0 +1,252 @@
+// LeavePulse SDK — ETag cache store (RFC 7232 conditional requests).
+//
+// `transport.conditional()` is the raw mechanism: it sends `If-None-Match` and
+// reports modified / not_modified / not_found, but doesn't remember anything.
+// This module adds the *policy*: an `EtagStore` keeps `{etag, body}` per key,
+// and `fetchCached` ties it to the transport — serve the cached body on `304`,
+// store the new body on `200`. Two stores ship (in-memory, localStorage);
+// implement `EtagStore` for anything else (SQLite, IndexedDB, …).
+
+import { NotFound } from "./errors";
+import type {
+	ConditionalResult,
+	Transport,
+	TransportRequest,
+} from "./transport";
+
+/** A cached conditional response: the validator and the body it belongs to. */
+export interface EtagEntry<T = unknown> {
+	etag: string;
+	body: T;
+}
+
+/**
+ * Pluggable storage for ETag cache entries. Sync or async — `fetchCached`
+ * awaits every call, so a synchronous store (Map) and an async one (IndexedDB,
+ * SQLite) satisfy the same interface.
+ */
+export interface EtagStore {
+	get<T>(
+		key: string,
+	): EtagEntry<T> | undefined | Promise<EtagEntry<T> | undefined>;
+	set<T>(key: string, entry: EtagEntry<T>): void | Promise<void>;
+	delete(key: string): void | Promise<void>;
+}
+
+/** The default cache key for a request: method + path (+ query). */
+export function defaultCacheKey(req: TransportRequest): string {
+	const channel = req.channel ?? "platform";
+	return `${channel} ${req.method} ${req.path}`;
+}
+
+/** In-process cache. Lives for the process; ideal for SSR and tests. */
+export class MemoryEtagStore implements EtagStore {
+	private readonly map = new Map<string, EtagEntry>();
+
+	get<T>(key: string): EtagEntry<T> | undefined {
+		return this.map.get(key) as EtagEntry<T> | undefined;
+	}
+
+	set<T>(key: string, entry: EtagEntry<T>): void {
+		this.map.set(key, entry);
+	}
+
+	delete(key: string): void {
+		this.map.delete(key);
+	}
+}
+
+/**
+ * Browser-persistent cache backed by `localStorage`. Entries survive reloads;
+ * a parse/quota failure degrades to a cache miss rather than throwing, so a
+ * full or corrupt store never breaks a request.
+ */
+export class LocalStorageEtagStore implements EtagStore {
+	/** @param prefix namespaces keys to avoid clashing with other data. */
+	constructor(
+		private readonly storage: Storage,
+		private readonly prefix = "lp.etag:",
+	) {}
+
+	get<T>(key: string): EtagEntry<T> | undefined {
+		const raw = this.storage.getItem(this.prefix + key);
+		if (raw === null) return undefined;
+		try {
+			return JSON.parse(raw) as EtagEntry<T>;
+		} catch {
+			return undefined;
+		}
+	}
+
+	set<T>(key: string, entry: EtagEntry<T>): void {
+		try {
+			this.storage.setItem(this.prefix + key, JSON.stringify(entry));
+		} catch {
+			// Quota exceeded / unavailable — skip caching, the request still works.
+		}
+	}
+
+	delete(key: string): void {
+		try {
+			this.storage.removeItem(this.prefix + key);
+		} catch {
+			// ignore
+		}
+	}
+}
+
+/**
+ * Browser-persistent cache backed by IndexedDB. Unlike `localStorage` it is
+ * asynchronous and not bound by the ~5 MB string quota, so it suits caching
+ * larger response bodies across sessions. Every operation degrades to a
+ * cache miss / no-op on failure (private mode, blocked storage, version
+ * conflicts), so a broken store never breaks a request.
+ */
+export class IndexedDbEtagStore implements EtagStore {
+	private dbPromise: Promise<IDBDatabase | null> | undefined;
+
+	/**
+	 * @param dbName   database name (one per app is plenty).
+	 * @param storeName object store holding the etag entries.
+	 */
+	constructor(
+		private readonly dbName = "lp-etag-cache",
+		private readonly storeName = "entries",
+	) {}
+
+	private openDb(): Promise<IDBDatabase | null> {
+		if (this.dbPromise) return this.dbPromise;
+		this.dbPromise = new Promise<IDBDatabase | null>((resolve) => {
+			const idb = typeof indexedDB !== "undefined" ? indexedDB : undefined;
+			if (!idb) {
+				resolve(null);
+				return;
+			}
+			let request: IDBOpenDBRequest;
+			try {
+				request = idb.open(this.dbName, 1);
+			} catch {
+				resolve(null);
+				return;
+			}
+			request.onupgradeneeded = () => {
+				const db = request.result;
+				if (!db.objectStoreNames.contains(this.storeName)) {
+					db.createObjectStore(this.storeName);
+				}
+			};
+			request.onsuccess = () => resolve(request.result);
+			request.onerror = () => resolve(null);
+			request.onblocked = () => resolve(null);
+		});
+		return this.dbPromise;
+	}
+
+	private async withStore<R>(
+		mode: IDBTransactionMode,
+		run: (store: IDBObjectStore) => IDBRequest,
+	): Promise<R | undefined> {
+		const db = await this.openDb();
+		if (!db) return undefined;
+		return new Promise<R | undefined>((resolve) => {
+			let req: IDBRequest;
+			try {
+				req = run(
+					db.transaction(this.storeName, mode).objectStore(this.storeName),
+				);
+			} catch {
+				resolve(undefined);
+				return;
+			}
+			req.onsuccess = () => resolve(req.result as R | undefined);
+			req.onerror = () => resolve(undefined);
+		});
+	}
+
+	async get<T>(key: string): Promise<EtagEntry<T> | undefined> {
+		return this.withStore<EtagEntry<T>>("readonly", (store) => store.get(key));
+	}
+
+	async set<T>(key: string, entry: EtagEntry<T>): Promise<void> {
+		await this.withStore("readwrite", (store) => store.put(entry, key));
+	}
+
+	async delete(key: string): Promise<void> {
+		await this.withStore("readwrite", (store) => store.delete(key));
+	}
+}
+
+export interface FetchCachedOptions {
+	/** Override the cache key (default: channel + method + path). */
+	key?: string;
+}
+
+/**
+ * Fetch a resource through the ETag cache: send the stored validator, return
+ * the cached body unchanged on `304`, store and return the fresh body on `200`,
+ * and return `null` on `404` (evicting any stale entry).
+ */
+export async function fetchCached<T>(
+	transport: Transport,
+	store: EtagStore,
+	req: TransportRequest,
+	options: FetchCachedOptions = {},
+): Promise<T | null> {
+	const key = options.key ?? defaultCacheKey(req);
+	const cached = await store.get<T>(key);
+	const result: ConditionalResult<T> = await transport.conditional<T>({
+		...req,
+		ifNoneMatch: cached?.etag,
+	});
+
+	switch (result.status) {
+		case "not_modified": {
+			// Server confirmed the cached copy is current — return it.
+			if (cached) return cached.body;
+			// We held a validator but no body (e.g. the store instance differs
+			// between SSR and client hydration, or the entry was evicted). The
+			// `304` carries no body, so re-fetch unconditionally to recover the
+			// full payload instead of reporting a phantom miss (which would
+			// surface as a bogus 404 in fetchCachedOrThrow).
+			const fresh = await transport.conditional<T>(req);
+			if (fresh.status === "modified") {
+				if (fresh.etag) {
+					await store.set<T>(key, { etag: fresh.etag, body: fresh.data });
+				}
+				return fresh.data;
+			}
+			if (fresh.status === "not_found") {
+				await store.delete(key);
+				return null;
+			}
+			return null;
+		}
+		case "modified":
+			if (result.etag) {
+				await store.set<T>(key, { etag: result.etag, body: result.data });
+			}
+			return result.data;
+		case "not_found":
+			await store.delete(key);
+			return null;
+	}
+}
+
+/**
+ * Like {@link fetchCached} but for endpoints that always yield a value: a `404`
+ * (null) is surfaced as a {@link NotFound} error, matching what a plain
+ * `transport.request` would throw. Generated GET methods route through this so
+ * their return type stays non-nullable.
+ */
+export async function fetchCachedOrThrow<T>(
+	transport: Transport,
+	store: EtagStore,
+	req: TransportRequest,
+	options: FetchCachedOptions = {},
+): Promise<T> {
+	const body = await fetchCached<T>(transport, store, req, options);
+	if (body === null) {
+		throw new NotFound(404, req, null, "");
+	}
+	return body;
+}

package/runtime/json.ts

@@ -0,0 +1,25 @@
+import { isInteger, parse } from "lossless-json";
+
+/**
+ * Parse a JSON response body, keeping integers beyond `Number.MAX_SAFE_INTEGER`
+ * as strings so 64-bit Snowflake ids survive intact (a plain `JSON.parse` would
+ * round them through a lossy `number`). All other numbers stay regular numbers.
+ *
+ * The transport uses this instead of `response.json()` so every SDK consumer
+ * gets precise ids without any per-call handling.
+ */
+export function parseJson(text: string): unknown {
+	if (text.length === 0) return undefined;
+	return parse(text, undefined, {
+		parseNumber(value: string) {
+			if (isInteger(value)) {
+				const num = Number(value);
+				if (num > Number.MAX_SAFE_INTEGER || num < Number.MIN_SAFE_INTEGER) {
+					return value;
+				}
+				return num;
+			}
+			return Number.parseFloat(value);
+		},
+	});
+}