@novacraft-engineering/mailbox 0.1.0

package/app/share/[id]/page.tsx

@@ -0,0 +1,166 @@
+'use client'
+
+import { CLIENT_BRAND } from '@/lib/brand.client'
+import { use, useCallback, useEffect, useState } from 'react'
+import styles from './share.module.css'
+
+type Meta = {
+  filename: string
+  size: number
+  contentType: string | null
+  needsPassword: boolean
+  expiresAt: string | null
+  downloadsLeft: number | null
+}
+
+function readableSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  const units = ['KB', 'MB', 'GB', 'TB']
+  let value = bytes / 1024
+  let unit = 0
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024
+    unit += 1
+  }
+  return `${value.toFixed(value >= 10 || unit === 0 ? 0 : 1)} ${units[unit]}`
+}
+
+/** Enough of a hint to set expectations before the file opens. */
+function kindOf(filename: string, contentType: string | null): string {
+  const extension = filename.split('.').pop()?.toLowerCase() ?? ''
+  if (/^(jpg|jpeg|png|gif|webp|avif|heic|svg)$/.test(extension)) return 'Image'
+  if (/^(mp4|mov|webm|mkv|avi)$/.test(extension)) return 'Video'
+  if (/^(mp3|wav|m4a|aac|flac|ogg)$/.test(extension)) return 'Audio'
+  if (extension === 'pdf') return 'PDF'
+  if (/^(zip|rar|7z|tar|gz)$/.test(extension)) return 'Archive'
+  if (/^(doc|docx|rtf|odt)$/.test(extension)) return 'Document'
+  if (/^(xls|xlsx|csv|ods)$/.test(extension)) return 'Spreadsheet'
+  if (/^(ppt|pptx|key|odp)$/.test(extension)) return 'Presentation'
+  return contentType?.split('/')[0] ? `${contentType.split('/')[0]} file` : 'File'
+}
+
+export default function SharePage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = use(params)
+  const [meta, setMeta] = useState<Meta | null>(null)
+  const [gone, setGone] = useState(false)
+  const [password, setPassword] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState('')
+  const [done, setDone] = useState(false)
+
+  useEffect(() => {
+    let cancelled = false
+    fetch(`/api/share/${id}`)
+      .then(async response => {
+        const data = await response.json().catch(() => null)
+        if (cancelled) return
+        if (!response.ok || !data?.ok) setGone(true)
+        else setMeta(data)
+      })
+      .catch(() => !cancelled && setGone(true))
+    return () => {
+      cancelled = true
+    }
+  }, [id])
+
+  const claim = useCallback(async () => {
+    setBusy(true)
+    setError('')
+    try {
+      const response = await fetch(`/api/share/${id}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ password }),
+      })
+      const data = await response.json().catch(() => null)
+      if (!response.ok || !data?.ok) {
+        setError(data?.error ?? 'That did not work.')
+        return
+      }
+      setDone(true)
+      // Navigating rather than opening a tab: a popup blocker would eat the tab,
+      // and the signed URL only lasts two minutes.
+      window.location.href = data.url
+    } catch {
+      setError('Could not reach the server. Try again.')
+    } finally {
+      setBusy(false)
+    }
+  }, [id, password])
+
+  if (gone) {
+    return (
+      <main className={styles.wrap}>
+        <div className={styles.card}>
+          <span className={styles.mark} aria-hidden />
+          <h1 className={styles.title}>This link is no longer available</h1>
+          <p className={styles.sub}>
+            It may have expired, been used its allowed number of times, or been withdrawn by
+            whoever sent it. Ask them for a new one.
+          </p>
+        </div>
+      </main>
+    )
+  }
+
+  if (!meta) {
+    return (
+      <main className={styles.wrap}>
+        <div className={styles.card}>
+          <span className={styles.skelMark} />
+          <span className={styles.skelLine} />
+          <span className={styles.skelLineShort} />
+        </div>
+      </main>
+    )
+  }
+
+  return (
+    <main className={styles.wrap}>
+      <div className={styles.card}>
+        <span className={styles.mark} aria-hidden />
+        <p className={styles.eyebrow}>{CLIENT_BRAND.legalName}</p>
+        <h1 className={styles.title}>{meta.filename}</h1>
+        <p className={styles.meta}>
+          {kindOf(meta.filename, meta.contentType)} · {readableSize(meta.size)}
+          {meta.downloadsLeft != null && ` · ${meta.downloadsLeft} download${meta.downloadsLeft === 1 ? '' : 's'} left`}
+        </p>
+
+        {meta.needsPassword && !done && (
+          <label className={styles.field}>
+            <span>Password</span>
+            <input
+              type="password"
+              value={password}
+              autoFocus
+              placeholder="The password you were given"
+              onChange={event => setPassword(event.target.value)}
+              onKeyDown={event => event.key === 'Enter' && password && claim()}
+            />
+          </label>
+        )}
+
+        {error && <p className={styles.error} role="alert">{error}</p>}
+
+        <button
+          type="button"
+          className={styles.go}
+          disabled={busy || done || (meta.needsPassword && !password)}
+          onClick={claim}
+        >
+          {done ? 'Starting download…' : busy ? 'Checking…' : 'Download'}
+        </button>
+
+        {meta.expiresAt && (
+          <p className={styles.foot}>
+            Available until {new Date(meta.expiresAt).toLocaleDateString('en-GB', {
+              day: 'numeric',
+              month: 'long',
+              year: 'numeric',
+            })}
+          </p>
+        )}
+      </div>
+    </main>
+  )
+}

package/app/share/[id]/share.module.css

@@ -0,0 +1,148 @@
+/* The one screen a recipient sees, and they are not a mailbox holder, so it
+   carries its own tokens rather than depending on the app's theme. */
+
+@keyframes shareIn {
+  from { opacity: 0; transform: translate3d(0, 12px, 0) scale(.98); }
+  to   { opacity: 1; transform: none; }
+}
+@keyframes sharePulse {
+  0%, 100% { opacity: .55; }
+  50%      { opacity: 1; }
+}
+
+.wrap {
+  min-height: 100dvh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 24px;
+  background: #f7f7fa;
+  font-family: Calibri, Carlito, 'Segoe UI', -apple-system, BlinkMacSystemFont, Roboto, Helvetica, Arial, sans-serif;
+}
+
+.card {
+  width: 100%;
+  max-width: 420px;
+  padding: 34px 32px 28px;
+  border: 1px solid #e4e4ec;
+  border-radius: 16px;
+  background: #fff;
+  box-shadow: 0 18px 48px rgba(8, 6, 16, .10);
+  text-align: center;
+  animation: shareIn .3s cubic-bezier(.2, .7, .3, 1) both;
+}
+
+.mark {
+  display: block;
+  width: 38px;
+  height: 28px;
+  margin: 0 auto 18px;
+  background: #6d28d9;
+  mask: url('/brand/mark.png') no-repeat center / contain;
+  -webkit-mask: url('/brand/mark.png') no-repeat center / contain;
+}
+
+.eyebrow {
+  margin: 0 0 8px;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: .14em;
+  text-transform: uppercase;
+  color: #9a96a6;
+}
+
+.title {
+  margin: 0;
+  font-size: 19px;
+  font-weight: 700;
+  line-height: 1.35;
+  color: #16121f;
+  word-break: break-word;
+  text-wrap: balance;
+}
+
+.meta {
+  margin: 8px 0 0;
+  font-size: 13px;
+  color: #6e6a7c;
+}
+
+.field {
+  display: block;
+  margin-top: 22px;
+  text-align: left;
+}
+.field span {
+  display: block;
+  margin-bottom: 6px;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: .08em;
+  text-transform: uppercase;
+  color: #6e6a7c;
+}
+.field input {
+  width: 100%;
+  padding: 11px 13px;
+  border: 1px solid #d3d3de;
+  border-radius: 10px;
+  background: #fff;
+  font: inherit;
+  font-size: 15px;
+  color: #16121f;
+  transition: border-color .16s ease, box-shadow .16s ease;
+}
+.field input:focus {
+  outline: none;
+  border-color: #6d28d9;
+  box-shadow: 0 0 0 3px rgba(169, 3, 23, .12);
+}
+
+.error {
+  margin: 12px 0 0;
+  font-size: 13px;
+  color: #c0261f;
+}
+
+.go {
+  width: 100%;
+  margin-top: 20px;
+  padding: 12px 18px;
+  border: 1px solid transparent;
+  border-radius: 10px;
+  background: #6d28d9;
+  color: #fff;
+  font: inherit;
+  font-size: 15px;
+  font-weight: 600;
+  cursor: pointer;
+  transition: background .16s ease, transform .16s ease;
+}
+.go:hover:not(:disabled) { background: #8e0213; transform: translateY(-1px); }
+.go:active:not(:disabled) { transform: translateY(0) scale(.99); }
+.go:disabled { opacity: .55; cursor: default; }
+
+.foot {
+  margin: 16px 0 0;
+  font-size: 12px;
+  color: #9a96a6;
+}
+
+/* Shown while the file's details are still being fetched. */
+.skelMark, .skelLine, .skelLineShort {
+  display: block;
+  margin: 0 auto;
+  border-radius: 8px;
+  background: #eceaf1;
+  animation: sharePulse 1.4s ease-in-out infinite;
+}
+.skelMark { width: 38px; height: 28px; margin-bottom: 20px; }
+.skelLine { width: 78%; height: 17px; margin-bottom: 10px; }
+.skelLineShort { width: 46%; height: 13px; }
+
+@media (prefers-reduced-motion: reduce) {
+  .card { animation: none; }
+  .skelMark, .skelLine, .skelLineShort { animation: none; }
+  .go, .field input { transition: none; }
+  .go:hover:not(:disabled), .go:active:not(:disabled) { transform: none; }
+}

package/eslint.config.mjs

@@ -0,0 +1,9 @@
+import { defineConfig, globalIgnores } from 'eslint/config'
+import nextVitals from 'eslint-config-next/core-web-vitals'
+import nextTs from 'eslint-config-next/typescript'
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  globalIgnores(['.next/**', 'out/**', 'build/**', 'next-env.d.ts', 'public/sw.js']),
+])

package/lib/accent-ramp.ts

@@ -0,0 +1,54 @@
+export type ThemeBase = 'dark' | 'dim' | 'light'
+
+export const ACCENT_RAMP: Record<ThemeBase, Record<string, number>> = {
+  dark: { 100: 92, 200: 84, 300: 73, 400: 62, 500: 52, 600: 44, 700: 37, 800: 25, 900: 16 },
+  dim: { 100: 90, 200: 82, 300: 71, 400: 60, 500: 51, 600: 43, 700: 36, 800: 27, 900: 20 },
+  light: { 100: 34, 200: 40, 300: 46, 400: 46, 500: 46, 600: 55, 700: 70, 800: 93, 900: 96 },
+}
+
+export function hexToHsl(hex: string): { h: number; s: number; l: number } | null {
+  const clean = hex.replace('#', '')
+  const full = clean.length === 3 ? clean.split('').map(char => char + char).join('') : clean
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) return null
+  const red = parseInt(full.slice(0, 2), 16) / 255
+  const green = parseInt(full.slice(2, 4), 16) / 255
+  const blue = parseInt(full.slice(4, 6), 16) / 255
+  const max = Math.max(red, green, blue)
+  const min = Math.min(red, green, blue)
+  const lightness = (max + min) / 2
+  if (max === min) return { h: 0, s: 0, l: lightness * 100 }
+  const delta = max - min
+  const saturation = delta / (1 - Math.abs(2 * lightness - 1))
+  let hue: number
+  if (max === red) hue = ((green - blue) / delta) % 6
+  else if (max === green) hue = (blue - red) / delta + 2
+  else hue = (red - green) / delta + 4
+  return { h: (hue * 60 + 360) % 360, s: saturation * 100, l: lightness * 100 }
+}
+
+/**
+ * The accent scale for one base. The 500 stop is the colour every primary control is
+ * painted in, so it is the configured accent exactly rather than a shade near it; the
+ * other stops slide by the same amount so the scale keeps its shape.
+ */
+export function accentScale(hex: string, base: ThemeBase = 'light'): Record<string, string> {
+  const hsl = hexToHsl(hex)
+  if (!hsl) return {}
+  const saturation = Math.max(28, Math.min(92, hsl.s))
+  const shift = hsl.l - ACCENT_RAMP[base][500]
+  const scale: Record<string, string> = {}
+  for (const [stop, lightness] of Object.entries(ACCENT_RAMP[base])) {
+    const shifted = Math.max(4, Math.min(97, lightness + shift))
+    scale[`--nc-violet-${stop}`] =
+      stop === '500'
+        ? `hsl(${hsl.h.toFixed(0)} ${hsl.s.toFixed(0)}% ${hsl.l.toFixed(0)}%)`
+        : `hsl(${hsl.h.toFixed(0)} ${saturation.toFixed(0)}% ${shifted.toFixed(0)}%)`
+  }
+  return scale
+}
+
+export function accentRampCss(hex: string, base: ThemeBase = 'light'): string {
+  return Object.entries(accentScale(hex, base))
+    .map(([name, value]) => `${name}:${value}`)
+    .join(';')
+}

package/lib/attachments.ts

@@ -0,0 +1,52 @@
+/**
+ * Which files are part of the message and which are attached to it.
+ *
+ * A signature logo and a footer badge arrive as ordinary MIME parts, so a mailbox that
+ * lists everything shows files on a message whose sender attached nothing.
+ *
+ * A Content-ID alone does not settle it. Forwarding through Outlook stamps one onto
+ * every image part, including photographs the sender genuinely attached, so treating
+ * any image that has one as decoration hides real files — accident photographs, in the
+ * case that found this. The body is the authority: a part is embedded when the message
+ * points at it, and that pointer is the whole reason it was given an id.
+ *
+ * Where the body cannot be read, everything is shown. Listing a signature logo is
+ * untidy; hiding a document somebody sent looks like the mail arrived broken.
+ */
+
+export type FileMeta = {
+  filename?: string
+  contentType?: string
+  size?: number
+  key?: string
+  contentId?: string
+  [extra: string]: unknown
+}
+
+/** Every `cid:` the body points at, lowercased and unwrapped. */
+export function referencedCids(html: string | null | undefined): Set<string> {
+  const found = new Set<string>()
+  if (!html) return found
+  for (const match of html.matchAll(/cid:([^"'\s>)\\]+)/gi)) {
+    found.add(match[1].replace(/^<|>$/g, '').trim().toLowerCase())
+  }
+  return found
+}
+
+/**
+ * Only images are ever hidden, and only when the body draws them. A Content-ID on a PDF
+ * means a sender referenced a real document, which is still something they attached.
+ */
+export function isEmbedded(file: FileMeta, referenced: Set<string>): boolean {
+  if (referenced.size === 0) return false
+  const contentId = typeof file.contentId === 'string' ? file.contentId.replace(/^<|>$/g, '').trim().toLowerCase() : ''
+  if (!contentId) return false
+  if (!String(file.contentType ?? '').toLowerCase().startsWith('image/')) return false
+  return referenced.has(contentId)
+}
+
+/** The files a reader should be offered, in their original order. */
+export function attachedFiles<T extends FileMeta>(files: T[], html?: string | null): T[] {
+  const referenced = referencedCids(html)
+  return files.filter(file => !isEmbedded(file, referenced))
+}

package/lib/brand.client.ts

@@ -0,0 +1,52 @@
+const name = process.env.NEXT_PUBLIC_BRAND_NAME?.trim() || 'Mailbox'
+const domain = process.env.NEXT_PUBLIC_MAIL_DOMAIN?.trim().toLowerCase() || 'example.com'
+const website = (process.env.NEXT_PUBLIC_BRAND_WEBSITE?.trim() || domain).replace(/^https?:\/\//, '').replace(/\/$/, '')
+const publicUrl = (process.env.NEXT_PUBLIC_MAIL_PUBLIC_URL?.trim() || `https://mail.${domain}`).replace(/\/$/, '')
+
+const legalName = process.env.NEXT_PUBLIC_BRAND_LEGAL_NAME?.trim() || name
+
+export const CLIENT_BRAND = {
+  name,
+  legalName,
+  address: process.env.NEXT_PUBLIC_BRAND_ADDRESS?.trim() || '',
+  tel: process.env.NEXT_PUBLIC_BRAND_TEL?.trim() || '',
+  regulatory: process.env.NEXT_PUBLIC_BRAND_REGULATORY?.trim() || '',
+  disclaimer:
+    process.env.NEXT_PUBLIC_BRAND_DISCLAIMER?.trim() ||
+    `DISCLAIMER: The information contained in this e-mail is proprietary to ${legalName} and is intended only for the individual or entity to which it is addressed. It may contain information that is privileged, confidential or exempt from disclosure under applicable law. If you are not the intended recipient, any use, distribution, transmission, printing, copying or dissemination of this information is strictly prohibited. If you have received this communication in error, please delete it and notify us.`,
+  colors: {
+    accent: process.env.NEXT_PUBLIC_BRAND_COLOR_ACCENT?.trim() || 'rgb(109, 40, 217)',
+    link: process.env.NEXT_PUBLIC_BRAND_COLOR_LINK?.trim() || 'rgb(17, 85, 204)',
+    muted: process.env.NEXT_PUBLIC_BRAND_COLOR_MUTED?.trim() || 'rgb(107, 114, 128)',
+  },
+  slug: name.toLowerCase().replace(/[^a-z0-9]+/g, '') || 'mailbox',
+  domain,
+  website,
+  websiteUrl: `https://${website}`,
+  publicUrl,
+  markUrl: process.env.NEXT_PUBLIC_BRAND_MARK_URL?.trim() || `${publicUrl}/icon-192.png`,
+  accent: process.env.NEXT_PUBLIC_BRAND_ACCENT?.trim() || '#6d28d9',
+  chromeMarkUrl: process.env.NEXT_PUBLIC_BRAND_CHROME_MARK_URL?.trim() || '/brand/mark.png',
+  signatureMark: {
+    border: process.env.NEXT_PUBLIC_BRAND_SIGNATURE_MARK_BORDER?.trim() || 'none',
+    radius: process.env.NEXT_PUBLIC_BRAND_SIGNATURE_MARK_RADIUS?.trim() || '0',
+  },
+  addressDomains: (process.env.NEXT_PUBLIC_MAIL_ADDRESS_DOMAINS ?? '')
+    .split(',')
+    .map(value => value.trim().toLowerCase())
+    .filter(Boolean),
+  addresses: (process.env.NEXT_PUBLIC_MAIL_ADDRESSES ?? '')
+    .split(',')
+    .map(value => value.trim().toLowerCase())
+    .filter(Boolean),
+} as const
+
+export const LS = (key: string) => `${CLIENT_BRAND.slug}_mail_${key}`
+
+/** Browser twin of signatureMarkStyle in lib/brand.ts; the two must agree or the preview lies about the sent mail. */
+export function clientSignatureMarkStyle(width: number): string {
+  const { border, radius } = CLIENT_BRAND.signatureMark
+  const colour = border === 'accent' ? CLIENT_BRAND.accent : border
+  const frame = !colour || colour === 'none' ? 'border:0;' : `padding:8px;border:1px solid ${colour};border-radius:${radius}px;`
+  return `display:block;width:${width}px;height:auto;${frame}`
+}

package/lib/brand.ts

@@ -0,0 +1,87 @@
+export type MailRole = 'admin' | 'member'
+export type MailSeat = { email: string; address: string; name: string; role: MailRole }
+
+const env = (key: string, fallback = '') => (process.env[key] ?? fallback).trim()
+
+function json<T>(key: string, fallback: T): T {
+  const raw = process.env[key]
+  if (!raw || !raw.trim()) return fallback
+  try {
+    return JSON.parse(raw) as T
+  } catch {
+    return fallback
+  }
+}
+
+const domain = env('MAIL_ADDRESS_DOMAIN', 'example.com').toLowerCase()
+const name = env('BRAND_NAME', 'Mailbox')
+const website = env('BRAND_WEBSITE', domain).replace(/^https?:\/\//, '').replace(/\/$/, '')
+const publicUrl = env('MAIL_PUBLIC_URL', `https://mail.${domain}`).replace(/\/$/, '')
+
+export const BRAND = {
+  name,
+  legalName: env('BRAND_LEGAL_NAME', name),
+  domain,
+  website,
+  websiteUrl: `https://${website}`,
+  publicUrl,
+  logoUrl: env('BRAND_LOGO_URL', `${publicUrl}/brand/mark-email.png`),
+  markUrl: env('BRAND_MARK_URL', `${publicUrl}/icon-192.png`),
+  address: env('BRAND_ADDRESS'),
+  tel: env('BRAND_TEL'),
+  regulatory: env('BRAND_REGULATORY'),
+  disclaimer: env(
+    'BRAND_DISCLAIMER',
+    `DISCLAIMER: The information contained in this e-mail is proprietary to ${env('BRAND_LEGAL_NAME', name)} and is intended only for the individual or entity to which it is addressed. It may contain information that is privileged, confidential or exempt from disclosure under applicable law. If you are not the intended recipient, any use, distribution, transmission, printing, copying or dissemination of this information is strictly prohibited. If you have received this communication in error, please delete it and notify us.`,
+  ),
+  colors: {
+    accent: env('BRAND_COLOR_ACCENT', 'rgb(109, 40, 217)'),
+    link: env('BRAND_COLOR_LINK', 'rgb(17, 85, 204)'),
+    muted: env('BRAND_COLOR_MUTED', 'rgb(107, 114, 128)'),
+  },
+  chromeMarkUrl: env('BRAND_CHROME_MARK_URL', '/brand/mark.png'),
+  signatureMark: {
+    border: env('BRAND_SIGNATURE_MARK_BORDER', 'none'),
+    radius: env('BRAND_SIGNATURE_MARK_RADIUS', '0'),
+  },
+  iconUrl: env('BRAND_ICON_URL'),
+  appleIconUrl: env('BRAND_APPLE_ICON_URL', env('BRAND_ICON_URL')),
+  accentHex: env('BRAND_ACCENT_HEX', env('NEXT_PUBLIC_BRAND_ACCENT', '#6d28d9')),
+  supportEmail: env('MAIL_SUPPORT_EMAIL', `info@${domain}`),
+  vapidSubject: env('VAPID_SUBJECT', `mailto:info@${domain}`),
+} as const
+
+const addressDomains: string[] = (() => {
+  const extra = env('MAIL_ADDRESS_DOMAINS')
+    .split(',')
+    .map(entry => entry.trim().toLowerCase())
+    .filter(Boolean)
+  const preferred = env('MAIL_DEFAULT_ADDRESS_DOMAIN').toLowerCase() || domain
+  return [...new Set([preferred, domain, ...extra])]
+})()
+
+export const ADDRESS_DOMAINS = addressDomains
+
+/**
+ * A mailbox a fresh checkout can sign into, so the package can be run and tried with no
+ * configuration at all. Its password is its own address, so it is never seeded into a
+ * production deployment.
+ */
+const DEV_SEAT: MailSeat = { email: `test@${domain}`, address: `test@${domain}`, name: 'Test Account', role: 'admin' }
+
+export const MAIL_SEATS: MailSeat[] = (() => {
+  const configured = json<MailSeat[]>('MAIL_SEATS', [])
+  if (process.env.NODE_ENV === 'production') return configured
+  return configured.some(seat => seat.email.toLowerCase() === DEV_SEAT.email) ? configured : [...configured, DEV_SEAT]
+})()
+export const ADDRESS_ALIASES: Record<string, string> = json<Record<string, string>>('MAIL_ADDRESS_ALIASES', {})
+
+export const brandSlug = BRAND.name.toLowerCase().replace(/[^a-z0-9]+/g, '')
+
+/** Inline style for the mark in a signature: a frame in the accent when the tenant asks for one, nothing otherwise. */
+export function signatureMarkStyle(width: number): string {
+  const { border, radius } = BRAND.signatureMark
+  const colour = border === 'accent' ? BRAND.colors.accent : border
+  const frame = !colour || colour === 'none' ? 'border:0;' : `padding:8px;border:1px solid ${colour};border-radius:${radius}px;`
+  return `display:block;width:${width}px;height:auto;${frame}`
+}

package/lib/d1.ts

@@ -0,0 +1,64 @@
+/**
+ * Cloudflare D1 over the REST API, shaped like the `neon()` tagged-template client so
+ * query call sites read the same. The app runs on Vercel, so there is no Worker binding
+ * available — every statement is an HTTPS round-trip to Cloudflare.
+ */
+
+type Param = string | number | null
+export type D1Sql = (strings: TemplateStringsArray, ...values: unknown[]) => Promise<Record<string, unknown>[]>
+
+const API = 'https://api.cloudflare.com/client/v4'
+
+function config() {
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID
+  const databaseId = process.env.D1_DATABASE_ID
+  const token = process.env.CLOUDFLARE_D1_TOKEN
+  if (!accountId || !databaseId || !token) {
+    throw new Error('CLOUDFLARE_ACCOUNT_ID, D1_DATABASE_ID and CLOUDFLARE_D1_TOKEN must be configured')
+  }
+  return { accountId, databaseId, token }
+}
+
+/** SQLite has no boolean or object types — normalise before binding. */
+function toParam(value: unknown): Param {
+  if (value === undefined || value === null) return null
+  if (typeof value === 'boolean') return value ? 1 : 0
+  if (typeof value === 'number') return value
+  if (value instanceof Date) return value.toISOString()
+  if (typeof value === 'object') return JSON.stringify(value)
+  return String(value)
+}
+
+export async function d1Query(sql: string, params: unknown[] = []): Promise<Record<string, unknown>[]> {
+  const { accountId, databaseId, token } = config()
+  const response = await fetch(`${API}/accounts/${accountId}/d1/database/${databaseId}/query`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ sql, params: params.map(toParam) }),
+  })
+  const payload = (await response.json()) as {
+    success?: boolean
+    errors?: Array<{ message?: string }>
+    result?: Array<{ results?: Record<string, unknown>[]; success?: boolean; error?: string }>
+  }
+  if (!response.ok || !payload.success) {
+    const detail = payload.errors?.map(entry => entry.message).filter(Boolean).join('; ') || `HTTP ${response.status}`
+    throw new Error(`D1 query failed: ${detail}`)
+  }
+  const first = payload.result?.[0]
+  if (first?.error) throw new Error(`D1 query failed: ${first.error}`)
+  return first?.results ?? []
+}
+
+/** Tagged-template entry point: interpolations become bound `?` parameters. */
+export function d1(): D1Sql {
+  return (strings, ...values) => d1Query(strings.raw.join('?'), values)
+}
+
+/** Run several statements in order — used for schema setup. */
+export async function d1Batch(statements: string[]): Promise<void> {
+  for (const statement of statements) {
+    const trimmed = statement.trim()
+    if (trimmed) await d1Query(trimmed)
+  }
+}