@zeyolabs/kit 0.0.0-stage → 2026.11.6

package/utils/datetime.ts

@@ -0,0 +1,338 @@
+import {
+	type CalendarDate,
+	DateFormatter,
+	fromDate,
+	getDayOfWeek,
+	getLocalTimeZone,
+	now,
+	parseDate,
+	type Time,
+	toCalendarDate,
+	today,
+	toTime,
+	toZoned,
+	type ZonedDateTime,
+} from '@internationalized/date';
+
+const DEFAULT_LOCALE = 'en-GB';
+
+// Day of the week
+
+export const Days = [
+	'Monday',
+	'Tuesday',
+	'Wednesday',
+	'Thursday',
+	'Friday',
+	'Saturday',
+	'Sunday',
+] as const;
+export type Day = (typeof Days)[number];
+
+export const DayIndex: Record<Day, number> = Object.fromEntries(
+	Days.map((day, index) => [day, index])
+) as Record<Day, number>;
+
+// Date functions local to a timezone
+export class LocalDateF {
+	constructor(private readonly timezone: string) {}
+
+	/** @returns The current date and time. */
+	now(): ZonedDateTime {
+		return now(this.timezone);
+	}
+
+	/** @returns The current date. */
+	today(): CalendarDate {
+		return today(this.timezone);
+	}
+}
+
+export const SERVER_TIME_ZONE = 'Europe/London';
+export const SERVER_LOCALE = 'en-GB';
+
+// Date functions local to server time zone
+export const ServerDt = new LocalDateF(SERVER_TIME_ZONE);
+
+/** Gets the day index of the date */
+function getDayIndexOfDate(date: CalendarDate): number {
+	// Always start 0 on Monday
+	return getDayOfWeek(date, DEFAULT_LOCALE, 'mon');
+}
+
+/**
+ * Gets the day of the week for a given date.
+ * @param date - The date to get the day of the week for.
+ * @returns The day of the week
+ */
+function getDayOfDate(date: CalendarDate): Day {
+	return Days[getDayIndexOfDate(date)];
+}
+
+/* Formatting */
+
+/* Day of the week */
+
+/**
+ * Formats a day of the week.
+ * @param day - The day of the week to format.
+ * @example "Monday" -> "Mon"
+ * @returns Formatted string of the day of the week.
+ */
+function formatDayShort(day: Day): string {
+	// Use the first three letters of the day
+	return day.slice(0, 3);
+}
+
+/* Calendar Dates */
+
+const FullDateFormatter = new DateFormatter(DEFAULT_LOCALE, {
+	day: 'numeric',
+	month: 'short',
+	year: 'numeric',
+});
+
+const ShortDateFormatter = new DateFormatter(DEFAULT_LOCALE, {
+	day: 'numeric',
+	month: 'short',
+});
+
+const NumFormatter = new DateFormatter(DEFAULT_LOCALE, {
+	day: '2-digit',
+	month: '2-digit',
+	year: 'numeric',
+});
+
+/**
+ * @param date The CalendarDate object to format.
+ * @returns The formatted date string in dd/mm/yyyy format.
+ * @example "05/10/2023"
+ */
+function formatDateNum(date: CalendarDate): string {
+	return formatDate(date, NumFormatter);
+}
+
+/**
+ * Formats a full date and time.
+ * @param datetime The ZonedDateTime object to format.
+ * @returns The formatted date and time string.
+ * @example "05/10/2023 14:30:00"
+ */
+function formatAbsolute(datetime: ZonedDateTime): string {
+	const date = toCalendarDate(datetime);
+	const time = toTime(datetime);
+	return `${formatDateNum(date)} ${formatTimeFull(time)}`;
+}
+
+/**
+ * @param date The CalendarDate object to format.
+ * @returns The formatted date string.
+ * @example "5 Oct 2023"
+ */
+function formatDateFull(date: CalendarDate) {
+	return formatDate(date, FullDateFormatter);
+}
+
+/**
+ * ISO format
+ * @param date The CalendarDate object to format.
+ * @returns The formatted date string in YYYY-MM-DD format.
+ * @example "2023-10-05"
+ */
+function formatDateISO(date: CalendarDate): string {
+	return date.toString();
+}
+
+/**
+ * @param date The CalendarDate object to format.
+ * @returns string of date in shortened format
+ * @example "Oct 5"
+ */
+function formatDateShort(date: CalendarDate) {
+	return formatDate(date, ShortDateFormatter);
+}
+
+/* Times */
+
+/**
+ * Gives time in HH:MM format
+ * @param time
+ * @returns string of time in that format
+ */
+function formatTime(time: Time): string {
+	const hours = padNum(time.hour, 2);
+	const minutes = padNum(time.minute, 2);
+	return `${hours}:${minutes}`;
+}
+
+/**
+ * Gives time in HH:MM:SS format
+ * @param time
+ * @returns string of time in that format
+ */
+function formatTimeFull(time: Time): string {
+	const hours = padNum(time.hour, 2);
+	const minutes = padNum(time.minute, 2);
+	const seconds = padNum(time.second, 2);
+	return `${hours}:${minutes}:${seconds}`;
+}
+
+/* Helpers */
+
+function formatDate(date: CalendarDate, formatter: DateFormatter): string {
+	const nativeDate = date.toDate(getLocalTimeZone());
+	return formatter.format(nativeDate);
+}
+
+function padNum(num: number, len: number): string {
+	if (isNaN(num)) return '0'.repeat(len);
+
+	return num.toString().padStart(len, '0');
+}
+
+// An absolute instant re-zoned into a viewer's timezone. Without `timezone`, call from client
+// code only: `getLocalTimeZone()` reads the current runtime's zone, so server-side it resolves to
+// the server zone. The apps that display these are `ssr: false`, so that default always runs in
+// the browser. Server-rendered content with no browser to detect from (e.g. an email) must pass
+// the viewer's stored `user.timezone` explicitly.
+const inViewerZone = (zdt: ZonedDateTime, timezone?: string): ZonedDateTime =>
+	fromDate(zdt.toDate(), timezone ?? getLocalTimeZone());
+
+/** HH:MM in the viewer's timezone (stored `timezone`, else the browser's local zone). */
+const formatLocalTime = (zdt: ZonedDateTime, timezone?: string): string =>
+	formatTime(toTime(inViewerZone(zdt, timezone)));
+
+/** Full date (e.g. "5 Oct 2023") in the viewer's timezone (stored `timezone`, else the browser's local zone). */
+const formatLocalDateFull = (zdt: ZonedDateTime, timezone?: string): string =>
+	formatDateFull(toCalendarDate(inViewerZone(zdt, timezone)));
+
+/** Numeric date (dd/mm/yyyy) in the viewer's local timezone. */
+const formatLocalDateNum = (zdt: ZonedDateTime): string =>
+	formatDateNum(toCalendarDate(inViewerZone(zdt)));
+
+/** Numeric date + HH:MM:SS (e.g. "05/10/2023 14:30:00") in the viewer's timezone (stored
+ *  `timezone`, else the browser's local zone). */
+const formatLocalDateTime = (zdt: ZonedDateTime, timezone?: string): string =>
+	formatAbsolute(inViewerZone(zdt, timezone));
+
+/** Whole days from `zdt` (a past instant) to today, in the viewer's timezone (clamped ≥ 0). */
+const daysSince = (zdt: ZonedDateTime): number =>
+	Math.max(0, today(getLocalTimeZone()).compare(toCalendarDate(inViewerZone(zdt))));
+
+/** Whole days from today to `zdt` (a future instant), in the viewer's timezone (clamped ≥ 0). */
+const daysUntil = (zdt: ZonedDateTime): number =>
+	Math.max(0, toCalendarDate(inViewerZone(zdt)).compare(today(getLocalTimeZone())));
+
+/** Full local date + whole days since the instant, for a "started/created on {date} · {daysAgo}d ago" UI. */
+const formatDateWithDaysAgo = (zdt: ZonedDateTime): { date: string; daysAgo: number } => ({
+	date: formatLocalDateFull(zdt),
+	daysAgo: daysSince(zdt),
+});
+
+/** `from`, pulled forward so the inclusive `from`→`to` range spans at most `maxDays` days.
+ *  A range already within the limit comes back unchanged. */
+const clampSpanStart = (from: CalendarDate, to: CalendarDate, maxDays: number): CalendarDate =>
+	to.compare(from) > maxDays ? to.subtract({ days: maxDays }) : from;
+
+/** Short weekday label for a date, e.g. "Mon". */
+const weekdayShort = (date: CalendarDate): string => formatDayShort(getDayOfDate(date));
+
+/** A CalendarDate as a short weekday + day-of-month, e.g. "Mon 31". */
+const formatWeekdayDay = (date: CalendarDate): string => `${weekdayShort(date)} ${date.day}`;
+
+/** A ClickHouse DateTime, returned as epoch seconds (the `unix_timestamp` output format), as a ZonedDateTime. */
+const zonedFromUnixSeconds = (seconds: number): ZonedDateTime =>
+	fromDate(new Date(seconds * 1000), SERVER_TIME_ZONE);
+
+/** A raw Postgres `timestamptz` string, as returned by a raw `ctx.db.execute(sql\`...\`)` select
+ *  (bypassing the `absoluteDateTime` custom type's own driver conversion), as a ZonedDateTime. */
+const zonedFromPgTimestamp = (s: string): ZonedDateTime => fromDate(new Date(s), SERVER_TIME_ZONE);
+
+/** Domain → wire: a ZonedDateTime as epoch seconds, for CH inserts / query params only. */
+const toUnixSeconds = (zdt: ZonedDateTime): number => Math.floor(zdt.toDate().getTime() / 1000);
+
+/** Domain → wire: a CalendarDate at server-tz start-of-day, as epoch seconds (CH DateTime query param). */
+const dayStartUnix = (date: CalendarDate): number => toUnixSeconds(toZoned(date, SERVER_TIME_ZONE));
+
+/** Epoch milliseconds (e.g. Gmail `internalDate`) as a ZonedDateTime. */
+const zonedFromUnixMillis = (millis: number): ZonedDateTime =>
+	fromDate(new Date(millis), SERVER_TIME_ZONE);
+
+/** Domain → wire: a ZonedDateTime as epoch milliseconds (e.g. an HTTP JSON boundary). */
+const toUnixMillis = (zdt: ZonedDateTime): number => zdt.toDate().getTime();
+
+/**
+ * A ClickHouse `Date` column ("YYYY-MM-DD") as a CalendarDate. Null/empty and the `1970-01-01`
+ * zero-date sentinel (CH's null-Date placeholder) map to `null`.
+ */
+const calendarFromChDate = (s: null | string | undefined): CalendarDate | null =>
+	s && s !== '1970-01-01' ? parseDate(s) : null;
+
+/**
+ * Compact, human relative time for a **past** instant, rendered in the viewer's timezone:
+ * "Just now" (< 1 min), "5m" (< 1 h), "3h" (< 1 day), "Yesterday" (exactly 1 day), then "4d".
+ * Elapsed time is the absolute now→`zdt` gap, so the result is timezone-independent.
+ */
+const formatRelativeShort = (zdt: ZonedDateTime): string => {
+	const minutes = Math.floor(now(getLocalTimeZone()).compare(zdt) / 60_000);
+	if (minutes < 1) return 'Just now';
+	if (minutes < 60) return `${minutes}m`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h`;
+	const days = Math.floor(hours / 24);
+	if (days === 1) return 'Yesterday';
+	return `${days}d`;
+};
+
+/**
+ * Full-word relative time for a **past** instant: "Just now" (< 1 min), "5 minutes ago",
+ * "1 hour ago", "10 hours ago", "3 days ago"; 30 days or more falls back to the full local date.
+ * Elapsed time is the absolute gap, so the result is timezone-independent. `from` is the "now"
+ * to measure against (injectable for tests).
+ */
+const formatRelativeAgo = (
+	zdt: ZonedDateTime,
+	from: ZonedDateTime = now(getLocalTimeZone())
+): string => {
+	const minutes = Math.floor(from.compare(zdt) / 60_000);
+	if (minutes < 1) return 'Just now';
+	if (minutes < 60) return `${minutes} ${minutes === 1 ? 'minute' : 'minutes'} ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours} ${hours === 1 ? 'hour' : 'hours'} ago`;
+	const days = Math.floor(hours / 24);
+	if (days < 30) return `${days} ${days === 1 ? 'day' : 'days'} ago`;
+	return formatLocalDateFull(zdt);
+};
+
+/** Date/time formatting + wire-format conversion — a plain object of functions (a Library, same
+ *  pattern as `Crypto`/`Schema`/`Normalize`), not a service: pure functions, no I/O. `ServerDt`
+ *  (above) is a tiny library of its own already — `now()`/`today()` in the server timezone —
+ *  so it stays a standalone export rather than folding in here. */
+export const Datetime = {
+	calendarFromChDate,
+	clampSpanStart,
+	daysSince,
+	dayStartUnix,
+	daysUntil,
+	formatAbsolute,
+	formatDateFull,
+	formatDateISO,
+	formatDateShort,
+	formatDateWithDaysAgo,
+	formatDayShort,
+	formatLocalDateFull,
+	formatLocalDateNum,
+	formatLocalDateTime,
+	formatLocalTime,
+	formatRelativeAgo,
+	formatRelativeShort,
+	formatTime,
+	formatWeekdayDay,
+	getDayOfDate,
+	toUnixMillis,
+	toUnixSeconds,
+	weekdayShort,
+	zonedFromPgTimestamp,
+	zonedFromUnixMillis,
+	zonedFromUnixSeconds,
+};

package/utils/email.ts

@@ -0,0 +1,173 @@
+import { Format } from './strings/format';
+
+/**
+ * Transactional email layout, table-based with every style
+ * inlined (the only markup that renders consistently across mail clients), a hidden preheader line,
+ * an accent strip, a heading, label/value rows, one call-to-action button and a footer. The header
+ * is a styled text wordmark, not an image or inline SVG, which Outlook, Gmail and Yahoo strip.
+ *
+ * Brand-agnostic: callers pass an `EmailBrand`. Colours are hex strings because mail clients have no
+ * CSS variables. The same params also render a plain-text alternative, so the two never drift.
+ */
+
+export type EmailBrand = {
+	/** Strip, badge and links. */
+	accent: string;
+	/** Text on a white card that must stay readable: wordmark, button fill. */
+	accentDark: string;
+	/** Badge background. */
+	accentSoft: string;
+	/** Printed in the footer, e.g. a postal address. */
+	address?: string;
+	name: string;
+	supportEmail: string;
+};
+
+export type EmailRow = {
+	label: string;
+	strong?: boolean;
+	/** Smaller line under the label, e.g. "2 × £18.00". */
+	sub?: string;
+	value: string;
+};
+
+export type EmailSection =
+	{ lines: string[]; title: string } | { rows: EmailRow[]; title?: string };
+
+export type EmailParams = {
+	badge?: string;
+	brand: EmailBrand;
+	cta?: { href: string; label: string };
+	eyebrow: string;
+	footnote?: string;
+	heading: string;
+	/** Paragraphs under the heading. */
+	intro: string[];
+	/** Inbox-preview line. */
+	preheader: string;
+	sections: EmailSection[];
+};
+
+const FONT =
+	"'DM Sans',-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif";
+const INK = '#1f2937';
+const MUTED = '#6b7280';
+const RULE = '#e5e7eb';
+
+const e = Format.escapeHtml;
+
+function renderRows(rows: EmailRow[]): string {
+	return rows
+		.map(
+			(row, i) => `
+					${i > 0 ? `<tr><td colspan="2" style="border-top:1px solid ${RULE};height:1px;font-size:0;line-height:0;">&nbsp;</td></tr>` : ''}
+					<tr>
+						<td style="font-family:${FONT};font-size:14px;line-height:1.4;color:${INK};padding:12px 12px 12px 0;font-weight:${row.strong ? 700 : 400};">
+							${e(row.label)}${row.sub ? `<br /><span style="font-size:12.5px;color:${MUTED};font-weight:400;">${e(row.sub)}</span>` : ''}
+						</td>
+						<td align="right" valign="top" style="font-family:${FONT};font-size:14px;line-height:1.4;color:${INK};padding:12px 0;white-space:nowrap;font-weight:${row.strong ? 700 : 500};">${e(row.value)}</td>
+					</tr>`
+		)
+		.join('');
+}
+
+function renderSection(section: EmailSection): string {
+	const title = section.title
+		? `<p style="font-family:${FONT};font-size:11px;font-weight:600;letter-spacing:0.08em;text-transform:uppercase;color:${MUTED};margin:0 0 4px;">${e(section.title)}</p>`
+		: '';
+	const body =
+		'rows' in section
+			? `<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%">${renderRows(section.rows)}</table>`
+			: `<p style="font-family:${FONT};font-size:14px;line-height:1.6;color:${INK};margin:0;">${section.lines.map(e).join('<br />')}</p>`;
+	return `
+				<tr><td style="padding:0 36px 24px;">
+					${title}
+					${body}
+				</td></tr>`;
+}
+
+export function renderEmail(params: EmailParams): string {
+	const { brand } = params;
+	return `<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width,initial-scale=1" />
+		<meta name="color-scheme" content="light" />
+		<title>${e(params.heading)}</title>
+	</head>
+	<body style="background:#f4f5f0;margin:0;padding:0;">
+		<div style="display:none;max-height:0;overflow:hidden;">${e(params.preheader)}&#847;&zwnj;&nbsp;&#847;&zwnj;&nbsp;&#847;&zwnj;&nbsp;</div>
+		<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%" style="background:#f4f5f0;">
+			<tr><td align="center" style="padding:40px 16px 48px;">
+				<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="600" style="max-width:600px;width:100%;">
+
+					<tr><td style="padding:0 4px 20px;">
+						<span style="font-family:${FONT};font-size:22px;font-weight:700;letter-spacing:-0.02em;color:${brand.accentDark};">${e(brand.name)}</span>
+					</td></tr>
+
+					<tr><td style="background:#ffffff;border:1px solid ${RULE};border-radius:12px;">
+						<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%">
+							<tr><td style="background:${brand.accent};height:4px;border-radius:12px 12px 0 0;font-size:0;line-height:0;">&nbsp;</td></tr>
+
+							<tr><td style="padding:30px 36px 8px;">
+								<table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%">
+									<tr>
+										<td><span style="font-family:${FONT};font-size:11px;font-weight:600;color:${MUTED};text-transform:uppercase;letter-spacing:0.08em;">${e(params.eyebrow)}</span></td>
+										${params.badge ? `<td align="right"><span style="display:inline-block;background:${brand.accentSoft};color:${brand.accentDark};font-family:${FONT};font-size:11px;font-weight:600;padding:4px 10px;border-radius:99px;">${e(params.badge)}</span></td>` : ''}
+									</tr>
+								</table>
+								<h1 style="font-family:${FONT};font-size:26px;font-weight:700;color:${INK};letter-spacing:-0.03em;line-height:1.25;margin:16px 0 12px;">${e(params.heading)}</h1>
+								${params.intro.map((p) => `<p style="font-family:${FONT};font-size:14.5px;line-height:1.6;color:#4b5563;margin:0 0 12px;">${e(p)}</p>`).join('\n\t\t\t\t\t\t\t\t')}
+							</td></tr>
+
+							<tr><td style="padding:12px 36px 8px;"><table role="presentation" cellpadding="0" cellspacing="0" border="0" width="100%"><tr><td style="border-top:1px solid ${RULE};height:1px;font-size:0;line-height:0;">&nbsp;</td></tr></table></td></tr>
+							${params.sections.map(renderSection).join('')}
+
+							${
+								params.cta
+									? `<tr><td style="padding:0 36px 32px;">
+								<table role="presentation" cellpadding="0" cellspacing="0" border="0">
+									<tr><td style="background:${brand.accentDark};border-radius:8px;">
+										<a href="${e(params.cta.href)}" style="display:inline-block;font-family:${FONT};font-size:14px;font-weight:600;color:#ffffff;text-decoration:none;padding:12px 24px;">${e(params.cta.label)}</a>
+									</td></tr>
+								</table>
+							</td></tr>`
+									: ''
+							}
+						</table>
+					</td></tr>
+
+					<tr><td align="center" style="padding-top:28px;">
+						<p style="font-family:${FONT};font-size:12.5px;color:${MUTED};line-height:1.7;margin:0;text-align:center;">
+							${params.footnote ? `${e(params.footnote)}<br />` : ''}
+							Questions? Reply to this email or write to <a href="mailto:${e(brand.supportEmail)}" style="color:${MUTED};text-decoration:underline;">${e(brand.supportEmail)}</a>.${brand.address ? `<br />${e(brand.name)}, ${e(brand.address)}` : ''}
+						</p>
+					</td></tr>
+
+				</table>
+			</td></tr>
+		</table>
+	</body>
+</html>`;
+}
+
+/** The same content as plain text, for clients that don't show HTML and as the multipart fallback. */
+export function renderEmailText(params: EmailParams): string {
+	const out: string[] = [params.heading, '', ...params.intro.flatMap((p) => [p, ''])];
+	for (const section of params.sections) {
+		if (section.title) out.push(section.title.toUpperCase());
+		if ('rows' in section) {
+			for (const row of section.rows) {
+				out.push(`${row.label}${row.sub ? ` (${row.sub})` : ''}: ${row.value}`);
+			}
+		} else {
+			out.push(...section.lines);
+		}
+		out.push('');
+	}
+	if (params.cta) out.push(`${params.cta.label}: ${params.cta.href}`, '');
+	if (params.footnote) out.push(params.footnote, '');
+	out.push(`Questions? Reply to this email or write to ${params.brand.supportEmail}.`);
+	return out.join('\n') + '\n';
+}

package/utils/env.ts

@@ -0,0 +1,171 @@
+/** Config vars (`vars` in wrangler.jsonc) AND secrets (Secrets Store bindings in prod, plain
+ *  strings in local `.dev.vars`/`.env`) — one store for both. Construct directly in tests
+ *  (`new EnvStore({ AUTH_URL: '...' })`) — real validation logic, no fake method stubs to keep in
+ *  sync. Production gets the one real instance via `resolve()`/`envStore()` below. */
+export class EnvStore {
+	private static instance: EnvStore | null = null;
+
+	private readonly secrets: Record<string, string> = {};
+
+	constructor(private readonly env: Record<string, unknown>) {}
+
+	static current(): EnvStore {
+		if (!EnvStore.instance) throw new Error('EnvStore.resolve() has not run yet');
+		return EnvStore.instance;
+	}
+
+	/** Test-only: clears the cached instance so the next `resolve()` call rebuilds against
+	 *  whatever env is current. A real isolate never needs this — the binding is isolate-stable
+	 *  for its whole lifetime; only a test process resolving many different envs does. */
+	static resetForTests(): void {
+		EnvStore.instance = null;
+	}
+
+	/** Builds the one real instance for this isolate — idempotent. Called from `runWithContext`,
+	 *  or directly (a Durable Object, say) if that never runs. Takes `unknown` so callers never
+	 *  need their own cast.
+	 *
+	 *  Eagerly resolves every binding named in `secretNames` so `secret()` can stay sync afterward.
+	 *  Gated on the name, not the binding's shape: Secrets Store, Service Bindings, and VPC services
+	 *  are all backed by the identical `Fetcher` RPC stub (same `constructor.name`, same prototype,
+	 *  zero own keys — verified live), so a prior attempt at excluding fetch-shaped bindings from
+	 *  this scan (#1262) instead excluded every real secret too and broke them all in prod (reverted
+	 *  in #1263). Filtering by name is the only signal that's actually reliable, and as a side
+	 *  effect it also means `.get()` is never called on a Service/VPC binding, so it stops causing a
+	 *  spurious cross-worker RPC exception log too. `secretNames` itself is app config
+	 *  (the names of the Secrets Store bindings), not here — this package stays account-agnostic, the actual
+	 *  list of real secret names is per-app config.
+	 *
+	 *  Local resolution is unreliable in two distinct ways (see the wiki): `.get()` can throw (an
+	 *  unseeded binding), or it can resolve cleanly to something that isn't a real secret at all —
+	 *  `null`, or even a non-string value. Either case falls back to a same-named `process.env`
+	 *  value (populated from `.env` by the SvelteKit/Vite dev server) so `secret()` works the same
+	 *  locally as in prod without every app re-implementing this fallback itself; if that's unset
+	 *  too, the secret is left unresolved, surfaced only if something actually reads it via
+	 *  `secret()`. `process` is absent in the real Workers runtime (no `nodejs_compat` polyfill
+	 *  covers it here), so this fallback only ever fires under local dev. */
+	static async resolve(env: unknown, secretNames: ReadonlySet<string>): Promise<void> {
+		if (EnvStore.instance) return;
+		const raw = env as Record<string, unknown>;
+		const instance = new EnvStore(raw);
+		const nodeEnv = typeof process === 'undefined' ? undefined : process.env;
+		await Promise.all(
+			Object.entries(raw).map(async ([name, value]) => {
+				if (
+					secretNames.has(name) &&
+					value != null &&
+					typeof value === 'object' &&
+					typeof (value as { get?: unknown }).get === 'function'
+				) {
+					let resolved: string | undefined;
+					try {
+						const got = await (value as { get(): Promise<unknown> }).get();
+						resolved = typeof got === 'string' && got.length > 0 ? got : undefined;
+					} catch {
+						resolved = undefined;
+					}
+					const fallback = resolved ?? nodeEnv?.[name];
+					if (fallback) instance.secrets[name] = fallback;
+				}
+			})
+		);
+		EnvStore.instance = instance;
+	}
+
+	/** Any other raw binding (Workers AI, R2, a Durable Object namespace, …) that isn't a plain
+	 *  var/VPC-fetch-shaped/secret — just existence-checked, then handed back as `T`. */
+	binding<T>(name: string): T {
+		const value = this.env[name];
+		if (!value) throw new Error(`EnvStore: "${name}" binding is not configured`);
+		return value as T;
+	}
+
+	/** A Cloudflare Hyperdrive binding. */
+	hyperdrive(name: string): Hyperdrive {
+		return this.binding<Hyperdrive>(name);
+	}
+
+	/** A numeric `vars` entry (e.g. `SENDER_BATCH_LIMIT: "500"`) — still a string in
+	 *  wrangler.jsonc, parsed and validated here instead of a bare `Number(...)` at the call site,
+	 *  which silently produces `NaN` on a bad value rather than failing. */
+	int(name: string): number {
+		const value = this.string(name);
+		const parsed = Number(value);
+		if (!Number.isInteger(parsed))
+			throw new Error(`EnvStore: "${name}" ("${value}") is not an integer`);
+		return parsed;
+	}
+
+	/** A secret — a Secrets Store binding in prod (resolved once in `resolve()` for names in
+	 *  `SECRET_STORE_BINDING_NAMES`), or a plain string in local `.dev.vars`/`.env`. A name missing
+	 *  from that set just fails loudly here at first call instead of at compile time, same tradeoff
+	 *  `string()` already makes. */
+	secret(name: string): string {
+		const resolved = this.secrets[name];
+		if (resolved != null) return resolved;
+		const value = this.env[name];
+		if (typeof value === 'string') return value;
+		throw new Error(`EnvStore: "${name}" secret is not configured in this env`);
+	}
+
+	/** Same as `secret()` but for a secret that's genuinely optional — `null` instead of throwing
+	 *  when unresolved (unset in this env, or an unseeded local Secrets Store binding with no
+	 *  `.env` fallback either). */
+	secretNull(name: string): null | string {
+		const resolved = this.secrets[name];
+		if (resolved != null) return resolved;
+		const value = this.env[name];
+		return typeof value === 'string' && value !== '' ? value : null;
+	}
+
+	/** No enumerated key list: this env's own vars vary too widely per app/worker to maintain one,
+	 *  and a typo'd name still fails loudly, just at first call instead of at compile time. */
+	string(name: string): string {
+		const value = this.lookup(name);
+		if (typeof value !== 'string') throw new Error(`EnvStore: "${name}" is not a string`);
+		return value;
+	}
+
+	/** Same as `string()` but for a var that's genuinely optional (some apps/workers set it,
+	 *  others don't) — `null` instead of throwing when unset. */
+	stringNull(name: string): null | string {
+		const value = this.env[name];
+		if (value == null || value === '') return null;
+		if (typeof value !== 'string') throw new Error(`EnvStore: "${name}" is not a string`);
+		return value;
+	}
+
+	/** A Workers VPC Service binding (`fetch`/`connect`, real Cloudflare shape — no cast needed at
+	 *  the call site). */
+	vpc(name: string): Fetcher {
+		const value = this.env[name];
+		if (!value) throw new Error(`EnvStore: "${name}" VPC binding is not configured`);
+		return value as Fetcher;
+	}
+
+	/** Same as `vpc()` but for a VPC binding that's genuinely optional (e.g. local dev has no VPC
+	 *  services at all) — `null` instead of throwing when unset. */
+	vpcNull(name: string): Fetcher | null {
+		const value = this.env[name];
+		return value ? (value as Fetcher) : null;
+	}
+
+	private lookup(name: string): unknown {
+		const value = this.env[name];
+		if (
+			value != null &&
+			typeof value === 'object' &&
+			typeof (value as { get?: unknown }).get === 'function'
+		) {
+			throw new Error(`EnvStore: "${name}" is a Secrets Store binding — use secret() instead`);
+		}
+		if (value == null || value === '') {
+			throw new Error(`EnvStore: "${name}" is not configured in this env`);
+		}
+		return value;
+	}
+}
+
+export function envStore(): EnvStore {
+	return EnvStore.current();
+}