@zeyolabs/kit 0.0.0-stage → 2026.11.6

package/utils/errors.ts

@@ -0,0 +1,67 @@
+import { HttpStatus } from './http-status';
+
+/**
+ * An error carrying an HTTP status and message, with no framework types. Callers map it to their
+ * own response representation. An optional structured `body` overrides the default `{ error }`
+ * payload, e.g. a validation failure that returns field-level errors.
+ */
+export class ServiceError extends Error {
+	constructor(
+		readonly status: number,
+		message: string,
+		readonly body?: Record<string, unknown>
+	) {
+		super(message);
+		this.name = 'ServiceError';
+	}
+}
+
+export const Error400 = (message: string) => new ServiceError(HttpStatus.BadRequest, message);
+export const Error401 = (message: string) => new ServiceError(HttpStatus.Unauthorized, message);
+export const Error402 = (message: string) => new ServiceError(HttpStatus.PaymentRequired, message);
+export const Error403 = (message: string) => new ServiceError(HttpStatus.Forbidden, message);
+export const Error404 = (message: string) => new ServiceError(HttpStatus.NotFound, message);
+/** The request contradicts the resource's current state. */
+export const Error409 = (message: string) => new ServiceError(HttpStatus.Conflict, message);
+/** Request validation failure; `body` carries the structured (field-level) errors. */
+export const ErrorFields = (body: Record<string, unknown>, message = 'Validation failed') =>
+	new ServiceError(HttpStatus.BadRequest, message, body);
+/** Use for rate-limit rejections. */
+export const Error429 = (message: string) => new ServiceError(HttpStatus.TooManyRequests, message);
+/** A deliberate 500 (config/invariant failure). */
+export const Error500 = (message: string) =>
+	new ServiceError(HttpStatus.InternalServerError, message);
+/** Use when a required dependency is down (fail closed). */
+export const Error503 = (message: string) =>
+	new ServiceError(HttpStatus.ServiceUnavailable, message);
+
+/**
+ * Map any thrown value to a client-safe HTTP status + message. A `ServiceError` carries its own
+ * status/message (a deliberate, client-facing failure). Anything else is unexpected and collapses
+ * to a generic 500; its message is never surfaced. `expected` lets callers pick the log level.
+ */
+export function toHttpError(err: unknown): {
+	body?: Record<string, unknown>;
+	expected: boolean;
+	message: string;
+	status: number;
+} {
+	if (err instanceof ServiceError) {
+		return { body: err.body, expected: true, message: err.message, status: err.status };
+	}
+	return {
+		expected: false,
+		message: 'Internal server error',
+		status: HttpStatus.InternalServerError,
+	};
+}
+
+/** Extract an HTTP status from an unknown thrown value, or null if it has none. */
+export function getHttpStatus(error: unknown): null | number {
+	if (typeof error !== 'object' || error === null) return null;
+	const e = error as { body?: { code?: string }; status?: number | string; statusCode?: number };
+	const status = e.status ?? e.statusCode;
+	if (typeof status === 'number') return status;
+	if (status === 'BAD_REQUEST' || e.body?.code === 'BAD_REQUEST') return 400;
+	return null;
+}

package/utils/form.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+
+export type FormResponseType = 'error' | 'ok' | 'warning';
+export type FormResult<T> = {
+	data: T;
+	message?: string;
+	type: FormResponseType;
+};
+
+/** Utility functions to return form responses */
+export const FormResult = {
+	/** Returns a form error with data and a message */
+	errData<T>(info: { data: T; message?: string }): FormResult<T> {
+		return {
+			...info,
+			type: 'error',
+		};
+	},
+
+	/** Returns a form error with a message */
+	err(message?: string): FormResult<void> {
+		return {
+			data: undefined,
+			message,
+			type: 'error',
+		};
+	},
+
+	/** Returns a form warning with data and a message */
+	warnData<T>(info: { data: T; message?: string }): FormResult<T> {
+		return {
+			...info,
+			type: 'warning',
+		};
+	},
+
+	/** Returns a form warning with a message */
+	warn(message?: string): FormResult<void> {
+		return {
+			data: undefined,
+			message,
+			type: 'warning',
+		};
+	},
+
+	/** Returns a form ok with data and a message */
+	okData<T>(info: { data: T; message?: string }): FormResult<T> {
+		return {
+			...info,
+			type: 'ok',
+		};
+	},
+
+	/** Returns a form ok with a message */
+	ok(message?: string): FormResult<void> {
+		return {
+			data: undefined,
+			message,
+			type: 'ok',
+		};
+	},
+};
+
+/**
+ * Number field — parses string or number input to any finite number (unbounded).
+ * Accepts numbers directly because `convert_formdata` parses `n:`-prefixed fields
+ * via `parseFloat`, so preflight validation receives an already-parsed number.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const formInt = z.any().transform((input: any, ctx) => {
+	if (input === undefined || (typeof input === 'string' && input.trim() === '')) {
+		ctx.issues.push({
+			code: 'invalid_type',
+			expected: 'number',
+			input,
+			message: 'number is required',
+		});
+		return z.NEVER;
+	}
+	const n = typeof input === 'number' ? input : Number(input);
+	if (!Number.isFinite(n)) {
+		ctx.issues.push({
+			code: 'invalid_type',
+			expected: 'number',
+			input,
+			message: 'invalid number',
+		});
+		return z.NEVER;
+	}
+	return n;
+}) as z.ZodType<number, number | string>;
+
+/** `<Form>`/remote-function field primitives that genuinely depend on SvelteKit's FormData
+ *  conversion conventions (`b:`/`n:`-prefixed field coercion, `RemoteFormInput`'s empty-string
+ *  handling) — a plain object of schemas/functions (a Library, same pattern as `Crypto`/`Schema`
+ *  in the kit), kept here rather than in `kit` because these aren't portable facts. */
+export const SchemaForm = {
+	/** Boolean field — SvelteKit converts `b:`-prefixed checkbox inputs to `boolean`; defaults to
+	 *  `false` */
+	Boolean: z
+		.boolean()
+		.optional()
+		.transform((v) => v ?? false)
+		.pipe(z.boolean()),
+
+	Int: formInt,
+
+	/** Number field — finite number bound to 0 or greater */
+	Number: formInt.pipe(z.number().min(0, 'must be 0 or greater')),
+
+	/**
+	 * Wraps any string-or-number schema so an empty input becomes `null`.
+	 * Usage: `SchemaForm.nullable(Schema.Text.min(3))`, `SchemaForm.nullable(SchemaForm.Number)`.
+	 *
+	 * Transport-agnostic at runtime — parses both a `<Form>` value (FormData: empty field = `''`)
+	 * and a JSON body (absent/optional field = real `null` or `undefined`). All three (`''`, `null`,
+	 * `undefined`) normalise to `null`; a value passes through to the wrapped schema. So the same
+	 * helper can back a `<Form>` *and* a JSON API/command body for an optional scalar field.
+	 *
+	 * The declared **input type stays `number | string`** on purpose: `<Form>`'s `RemoteFormInput`
+	 * forbids `null`/`undefined` field values, so widening the type would break form usage. `null`/
+	 * `undefined` are accepted at runtime (the union below) without being exposed in the type —
+	 * JSON parsing is runtime validation anyway, so the narrower type costs the JSON path nothing.
+	 */
+	nullable<T extends z.ZodType<unknown, number | string>>(schema: T) {
+		return z
+			.union([z.string(), z.number(), z.null(), z.undefined()])
+			.transform((v): null | number | string => {
+				// Empty form field (''), absent/empty n:-field (undefined), or JSON null → null.
+				if (v == null || (typeof v === 'string' && v.trim() === '')) return null;
+				return v;
+			})
+			.pipe(schema.nullable()) as z.ZodType<null | z.infer<T>, number | string>;
+	},
+};

package/utils/http-status.ts

@@ -0,0 +1,42 @@
+export const SuccessCode = {
+	Accepted: 202, // Request accepted but not yet processed. Use for async/queued operations.
+	Created: 201, // Resource was created. Use for POST requests that result in a new resource.
+	NoContent: 204, // Success with no body to return. Use for DELETE or actions with no response data.
+	OK: 200, // Standard success. Use for GET, PUT, or PATCH requests that return a body.
+} as const;
+
+export const RedirectCode = {
+	Found: 302, // Temporary redirect. Client should continue using the original URL.
+	MovedPermanently: 301, // Resource has permanently moved. Clients should update their bookmarks.
+	PermanentRedirect: 308, // Permanent redirect preserving the original HTTP method.
+	SeeOther: 303, // Redirect to a different resource, always with GET. Use after POST to prevent re-submission.
+	TemporaryRedirect: 307, // Temporary redirect preserving the original HTTP method.
+} as const;
+
+export const ClientErrorCode = {
+	BadRequest: 400, // Malformed request syntax or invalid parameters.
+	Conflict: 409, // Request conflicts with the current state (e.g. duplicate resource).
+	Forbidden: 403, // Authenticated but not authorised to access this resource.
+	Gone: 410, // Resource permanently deleted and no longer available.
+	MethodNotAllowed: 405, // HTTP method is not supported for this endpoint.
+	NotFound: 404, // Resource does not exist.
+	PaymentRequired: 402, // Payment is required to access this resource.
+	TooManyRequests: 429, // Rate limit exceeded.
+	Unauthorized: 401, // Authentication required or credentials are invalid.
+	UnprocessableEntity: 422, // Request is well-formed but contains semantic errors.
+} as const;
+
+export const ServerErrorCode = {
+	BadGateway: 502, // Upstream service returned an invalid response.
+	GatewayTimeout: 504, // Upstream service did not respond in time.
+	InternalServerError: 500, // Unexpected server-side failure.
+	NotImplemented: 501, // Endpoint or feature not yet implemented.
+	ServiceUnavailable: 503, // Server is temporarily unavailable (overloaded or down for maintenance).
+} as const;
+
+export const HttpStatus = {
+	...SuccessCode,
+	...RedirectCode,
+	...ClientErrorCode,
+	...ServerErrorCode,
+} as const;

package/utils/money.ts

@@ -0,0 +1,10 @@
+/**
+ * Format an amount held in minor units (pence, cents, ...) for display. Store money as integer
+ * minor units and only format at the edge. The divisor follows the currency's own fraction digits,
+ * so zero-decimal currencies (JPY) and three-decimal ones (KWD) come out right.
+ */
+export function formatMinorUnits(amount: number, currency: string, locale: string): string {
+	const formatter = new Intl.NumberFormat(locale, { currency, style: 'currency' });
+	const digits = formatter.resolvedOptions().maximumFractionDigits ?? 2;
+	return formatter.format(amount / 10 ** digits);
+}

package/utils/public-host.ts

@@ -0,0 +1,66 @@
+export function parseIPv4(ip: string): null | number[] {
+	const parts = ip.split('.').map(Number);
+	return parts.length === 4 && parts.every((n) => Number.isInteger(n) && n >= 0 && n <= 255)
+		? parts
+		: null;
+}
+
+function parseIPv6(ip: string): null | number[] {
+	let text = ip;
+	const lastColon = text.lastIndexOf(':');
+	if (text.includes('.')) {
+		const v4 = parseIPv4(text.slice(lastColon + 1));
+		if (!v4) return null;
+		text = `${text.slice(0, lastColon + 1)}${((v4[0] << 8) | v4[1]).toString(16)}:${((v4[2] << 8) | v4[3]).toString(16)}`;
+	}
+	const halves = text.split('::');
+	if (halves.length > 2) return null;
+	const head = halves[0] ? halves[0].split(':') : [];
+	const tail = halves[1] ? halves[1].split(':') : [];
+	const fill = halves.length === 2 ? 8 - head.length - tail.length : 0;
+	if (fill < 0 || (halves.length === 1 && head.length !== 8)) return null;
+	const groups = [...head, ...Array<string>(fill).fill('0'), ...tail].map((g) =>
+		/^[0-9a-f]{1,4}$/i.test(g) ? parseInt(g, 16) : NaN
+	);
+	return groups.length === 8 && groups.every((g) => !Number.isNaN(g)) ? groups : null;
+}
+
+// Not publicly routable: this-network, RFC1918, CGNAT (covers Alibaba metadata 100.100.100.200),
+// loopback, link-local (covers AWS/GCP/Azure metadata 169.254.169.254), IETF/benchmark, multicast+reserved.
+function isPrivateIPv4([a, b, c]: number[]): boolean {
+	return (
+		a === 0 ||
+		a === 10 ||
+		(a === 100 && b >= 64 && b <= 127) ||
+		a === 127 ||
+		(a === 169 && b === 254) ||
+		(a === 172 && b >= 16 && b <= 31) ||
+		(a === 192 && b === 0 && c === 0) ||
+		(a === 192 && b === 168) ||
+		(a === 198 && (b === 18 || b === 19)) ||
+		a >= 224
+	);
+}
+
+// Unparseable input counts as private: fail closed.
+export function isPrivateAddress(address: string): boolean {
+	const v4 = parseIPv4(address);
+	if (v4) return isPrivateIPv4(v4);
+	const g = parseIPv6(address);
+	if (!g) return true;
+	// ::/96 (incl. :: and ::1) and ::ffff:0:0/96 embed an IPv4 address in the last 32 bits.
+	if (g.slice(0, 5).every((x) => x === 0) && (g[5] === 0 || g[5] === 0xffff)) {
+		return isPrivateIPv4([g[6] >> 8, g[6] & 0xff, g[7] >> 8, g[7] & 0xff]);
+	}
+	// fc00::/7 unique-local (covers AWS fd00:ec2::254), fe80::/10 link-local, ff00::/8 multicast.
+	return (g[0] & 0xfe00) === 0xfc00 || (g[0] & 0xffc0) === 0xfe80 || (g[0] & 0xff00) === 0xff00;
+}
+
+/** Whether a URL hostname could be a public destination, judged without DNS: an IP literal must
+ *  be publicly routable and `localhost` is out. A name that resolves to a private address is
+ *  caught at delivery time instead. */
+export function isPublicHost(hostname: string): boolean {
+	const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+	if (host === 'localhost' || host.endsWith('.localhost')) return false;
+	return parseIPv4(host) || host.includes(':') ? !isPrivateAddress(host) : true;
+}

package/utils/schema.ts

@@ -0,0 +1,176 @@
+import {
+	CalendarDate as calendarImport,
+	parseDate,
+	parseTime,
+	Time as timeImport,
+	ZonedDateTime,
+} from '@internationalized/date';
+import { z } from 'zod';
+
+import { Datetime, Days } from './datetime';
+import { Normalize, titleCase } from './strings/normalize';
+
+const NAME_MAX = 50;
+
+const uuid = z.uuid();
+
+const SORT_DIRECTIONS = ['asc', 'desc'] as const;
+export type SortDirection = (typeof SORT_DIRECTIONS)[number];
+
+function normalizeSlug(input: string): string {
+	return input
+		.trim()
+		.toLowerCase()
+		.replace(/^\/+/, '') // remove leading slashes
+		.replace(/\/+$/, ''); // remove trailing slashes
+}
+
+const slug = z
+	.string()
+	.min(1)
+	.transform(normalizeSlug)
+	.refine((s) => !s.includes('/'), { message: 'Slug must not contain slashes' })
+	.refine((s) => /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(s), { message: 'Invalid slug format' });
+
+/** Reusable zod primitives — a plain object of schemas/functions (a Library, same pattern as
+ *  `Crypto`), not a service: nothing here reads a binding or holds state. */
+export const Schema = {
+	// Phone: allows "+", digits, and spaces only
+	Phone: z
+		.string()
+		.regex(/^[+0-9 ]+$/, 'invalid phone number. Only +, digits, and spaces are allowed.'),
+
+	/** 6-digit hex color string (without leading `#`) */
+	HexColor: z
+		.string({ error: 'please pick a color' })
+		.regex(/^[0-9a-fA-F]{6}$/, 'invalid hex color, expected RRGGBB'),
+
+	// Datetime types
+
+	Day: z.enum(Days),
+
+	Time: z.instanceof(timeImport, { error: 'invalid time' }),
+
+	CalendarDate: z.instanceof(calendarImport, { error: 'invalid date' }),
+
+	/** ISO 8601 date string ("YYYY-MM-DD") parsed to a `CalendarDate` — the wire-string sibling of
+	 *  `CalendarDate` above (which validates an already-decoded instance). */
+	DateFromString: z.string().transform((text, ctx) => {
+		try {
+			return parseDate(text);
+		} catch {
+			ctx.issues.push({
+				code: 'invalid_format',
+				format: 'date',
+				input: text,
+				message: 'invalid date format, expected YYYY-MM-DD',
+			});
+			return z.NEVER;
+		}
+	}),
+
+	/** ISO 8601 time string ("HH:mm") parsed to a `Time` — the wire-string sibling of `Time` above. */
+	TimeFromString: z.string().transform((text, ctx) => {
+		try {
+			return parseTime(text);
+		} catch {
+			ctx.issues.push({
+				code: 'invalid_format',
+				format: 'time',
+				input: text,
+				message: 'invalid time format, expected HH:mm',
+			});
+			return z.NEVER;
+		}
+	}),
+
+	/** The one domain datetime type: a value is ALWAYS a ZonedDateTime. This schema just accepts
+	 *  the two wire forms it can arrive in — an already-decoded ZonedDateTime (transport) or a
+	 *  ClickHouse `unix_timestamp` epoch (a number, or a quoted string depending on server
+	 *  settings) — and yields a ZonedDateTime either way. */
+	ZonedDateTime: z.union([
+		z.instanceof(ZonedDateTime),
+		z.coerce.number().transform(Datetime.zonedFromUnixSeconds),
+	]),
+
+	/** A `ZonedDateTime` that crosses a serialization boundary (a queue) as unix seconds. */
+	ZonedDateTimeWire: z.codec(z.number().int(), z.instanceof(ZonedDateTime), {
+		decode: Datetime.zonedFromUnixSeconds,
+		encode: Datetime.toUnixSeconds,
+	}),
+
+	UUID: uuid,
+	UUIDs: z.array(uuid),
+
+	// Positive integer for primary keys — mirrors auto-increment DB ids (>= 1)
+	Id: z.number().int().positive(),
+
+	// Like `Id`, but also accepts the non-positive sentinel ids a handful of reserved rows use
+	// (e.g. `ORG_ACCOUNT_ID = 0`, `MARKETING_ACCOUNT_ID = -1`) — anywhere a real
+	// auto-generated row and a reserved shared row can both appear.
+	SignedId: z.number().int(),
+
+	StringId: z.string().min(1),
+
+	// `.trim()` MUST run before the `z.email()` format check, not after: zod validates a schema's
+	// own built-in format before any transform chained onto it runs, so `z.email().trim()` would
+	// reject padded input outright instead of trimming it.
+	Email: z.string().trim().max(100).toLowerCase().pipe(z.email('invalid email address')),
+
+	Emails: z.array(z.email()),
+
+	SearchTerm: z.string().min(2, 'Search term must be at least 2 characters long'),
+
+	/** A person's first/last name — title-cased ("SHELDON" / "mark" → "Sheldon" / "Mark"). Not for
+	 *  free text (account/campaign/list names use `Text` instead — title-casing would mangle
+	 *  brand names/acronyms). */
+	Name: z.string().trim().min(1).max(NAME_MAX).transform(titleCase),
+
+	/** Non-empty text field (trimmed, min 1 character) */
+	Text: z.string().trim().min(1, 'text cannot be empty'),
+
+	Domain: z
+		.string()
+		.min(1)
+		.transform(Normalize.domain)
+		.refine((domain) => domain !== '', { message: 'Invalid domain' }),
+
+	Slug: slug,
+
+	PaginationSchema: z.object({
+		limit: z.number(),
+		offset: z.number(),
+	}),
+
+	// Direction half of a server-side column sort — pair with a per-view sort-key enum so an
+	// unknown column is rejected at the schema boundary instead of reaching the query builder.
+	SortDirection: z.enum(SORT_DIRECTIONS),
+
+	/** Requires a non-empty file upload. */
+	File: z.instanceof(File).refine((f) => f.size > 0, 'file is required'),
+
+	// Zod utilities
+
+	/** Type string which is trimmed before being validated against `typeTo`. */
+	trimTo<T extends z.ZodType<string, string>>(typeTo: T) {
+		return z.string().trim().pipe(typeTo);
+	},
+
+	/** A fixed-length numeric PIN string (default 6 digits). */
+	pin(length = 6) {
+		return z.string().regex(new RegExp(`^\\d{${length}}$`), `pin must be ${length} digits`);
+	},
+
+	/** Constrained to one of the provided string options. */
+	select<T extends readonly [string, ...string[]]>(options: T) {
+		return z.enum(options);
+	},
+};
+
+export type Emails = z.infer<typeof Schema.Emails>;
+export type Id = z.infer<typeof Schema.Id>;
+export type PaginationSchema = z.infer<typeof Schema.PaginationSchema>;
+export type SignedId = z.infer<typeof Schema.SignedId>;
+export type Slug = z.infer<typeof Schema.Slug>;
+export type UUID = z.infer<typeof Schema.UUID>;
+export type UUIDs = z.infer<typeof Schema.UUIDs>;

package/utils/strings/format.ts

@@ -0,0 +1,51 @@
+const HTML_ESCAPES: Record<string, string> = {
+	"'": '&#39;',
+	'"': '&quot;',
+	'&': '&amp;',
+	'<': '&lt;',
+	'>': '&gt;',
+};
+
+/** Turns a raw value into a display string — a plain object of functions (a Library, same pattern
+ *  as `Crypto`/`Schema`/`Normalize`), not a service: pure output formatting, no I/O. Distinct from
+ *  `Normalize` (canonicalizing a value down to its minimal storage form) — this goes the other
+ *  way, storage/domain value → presentation string. */
+export const Format = {
+	/** Escape a string for safe interpolation into HTML text/attribute content. */
+	escapeHtml(value: string): string {
+		return value.replace(/[&<>"']/g, (c) => HTML_ESCAPES[c]!);
+	},
+
+	/** USD currency, always 2 decimal places, e.g. 1234.5 → "$1,234.50". */
+	money(amount: number): string {
+		return amount.toLocaleString(undefined, {
+			currency: 'USD',
+			maximumFractionDigits: 2,
+			minimumFractionDigits: 2,
+			style: 'currency',
+		});
+	},
+
+	/** One CSV cell, always double-quoted (embedded `"` doubled) — `null`/`undefined` → `''`. */
+	csvField(value: null | number | string | undefined): string {
+		return value == null ? '' : `"${String(value).replace(/"/g, '""')}"`;
+	},
+
+	/** Abbreviated count with a trailing "+", e.g. 1_234_567 → "1.2M+", 3_400 → "3K+". Falsy/missing → "N/A". */
+	compactCount(n: null | number | undefined): string {
+		if (!n) return 'N/A';
+		if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, '')}M+`;
+		if (n >= 1_000) return `${(n / 1_000).toFixed(0)}K+`;
+		return `${n}`;
+	},
+
+	/** Abbreviated USD amount with a T/B/M suffix, e.g. 1_500_000 → "$1.5M". `<= 0`/missing → "N/A". */
+	compactMoney(amount: null | number | undefined): string {
+		if (!amount || amount <= 0) return 'N/A';
+		if (amount >= 1_000_000_000_000) return `$${(amount / 1_000_000_000_000).toFixed(2)}T`;
+		if (amount >= 1_000_000_000)
+			return `$${(amount / 1_000_000_000).toFixed(1).replace(/\.0$/, '')}B`;
+		if (amount >= 1_000_000) return `$${(amount / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
+		return `$${amount.toLocaleString('en-US')}`;
+	},
+};

package/utils/strings/normalize.ts

@@ -0,0 +1,129 @@
+import { parse } from 'tldts';
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export function isEmail(value: string): boolean {
+	return EMAIL_RE.test(value);
+}
+
+/** Cleans a raw value down to its minimal storage form — a plain object of functions (a
+ *  Library, same pattern as `Crypto`/`Schema`), not a service: pure string transforms, no I/O. */
+export const Normalize = {
+	email(value: string): string {
+		return value.trim().toLowerCase();
+	},
+
+	/**
+	 * The registrable (root) domain for a URL or bare hostname via the Public Suffix List, or `''`
+	 * when none can be parsed. e.g. `https://www.skma.co.uk/x` → `skma.co.uk`.
+	 */
+	domain(raw: string): string {
+		const value = raw.trim().toLowerCase();
+		if (!value) return '';
+		const url = /^[a-z][a-z0-9+.-]*:\/\//.test(value) ? value : `https://${value}`;
+		return parse(url).domain ?? '';
+	},
+
+	/**
+	 * A URL cleaned to its minimal storage form: no protocol (`https` is always assumed at
+	 * display/export — see `fullUrl` in `lists/columns.ts`), `www` dropped, any other subdomain
+	 * kept, no trailing slash-only path. `''` when nothing parseable.
+	 * e.g. `https://www.domain.com/` → `domain.com`; `http://blog.domain.com` → `blog.domain.com`;
+	 * `domain.com/pricing` → `domain.com/pricing`.
+	 */
+	url(raw: string): string {
+		const value = raw.trim();
+		if (!value) return '';
+		const withProtocol = /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `https://${value}`;
+		let url: URL;
+		try {
+			url = new URL(withProtocol);
+		} catch {
+			return '';
+		}
+		const parsed = parse(url.hostname.toLowerCase());
+		if (!parsed.domain) return '';
+		const subdomain = parsed.subdomain && parsed.subdomain !== 'www' ? `${parsed.subdomain}.` : '';
+		const path = url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
+		return `${subdomain}${parsed.domain}${path}${url.search}${url.hash}`;
+	},
+
+	/**
+	 * An X/Twitter profile reduced to its bare handle: no `@`, no host, no protocol — storage is
+	 * always the minimal form, `xFullUrl` (`lists/columns.ts`) rebuilds the clickable profile URL at
+	 * display/export time. Accepts a full URL (`x.com` or the legacy `twitter.com` host), a bare
+	 * `@handle`, or an already-bare handle. `''` when nothing usable is left.
+	 * e.g. `https://x.com/elonmusk` → `elonmusk`; `twitter.com/elonmusk` → `elonmusk`;
+	 * `@elonmusk` → `elonmusk`.
+	 */
+	xHandle(raw: string): string {
+		const trimmed = raw.trim().replace(/^\/+|\/+$/g, '');
+		if (!trimmed) return '';
+		if (!/(?:^|[./])(x|twitter)\.com/i.test(trimmed)) return trimmed.replace(/^@/, ''); // already bare
+		const withProtocol = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+		try {
+			return new URL(withProtocol).pathname.replace(/^\/+|\/+$/g, '');
+		} catch {
+			return trimmed.replace(/^@/, '');
+		}
+	},
+};
+
+/** Deterministic slug: lowercase, non-alphanumeric runs collapsed to a single `-`, no leading or
+ *  trailing dash. e.g. "Q3 Growth — Final!" → "q3-growth-final". */
+export function slugify(value: string): string {
+	return value
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '');
+}
+
+/** Title-cases each word ("SHELDON" / "mark" → "Sheldon" / "Mark") — for a person's name, not
+ *  free text (would mangle brand names/acronyms). */
+export function titleCase(str: string): string {
+	return str.replace(
+		/\w\S*/g,
+		(txt) => txt.charAt(0).toUpperCase() + txt.substring(1).toLowerCase()
+	);
+}
+
+/** e.g. "John Doe" → "JD". Falls back to "?" for a blank/whitespace-only name. */
+export function initials(name: string, max = 2): string {
+	return (
+		name
+			.split(' ')
+			.filter(Boolean)
+			.slice(0, max)
+			.map((w) => w[0]?.toUpperCase())
+			.join('') || '?'
+	);
+}
+
+/** Subsequence match — every character of `needle` appears in `haystack`, in order. */
+export function fuzzySearch(needle: string, haystack: string): boolean {
+	const hlen = haystack.length;
+	const nlen = needle.length;
+
+	if (nlen > hlen) {
+		return false;
+	}
+	if (nlen === hlen) {
+		return needle.toLowerCase() === haystack.toLowerCase();
+	}
+
+	const lowerNeedle = needle.toLowerCase();
+	const lowerHaystack = haystack.toLowerCase();
+
+	outer: for (let i = 0, j = 0; i < nlen; i++) {
+		const nch = lowerNeedle.charCodeAt(i);
+		while (j < hlen) {
+			if (lowerHaystack.charCodeAt(j++) === nch) {
+				continue outer;
+			}
+		}
+		return false;
+	}
+
+	return true;
+}