@beechcms/api 0.4.0 → 0.4.1

package/src/shared/d1-activity-logger.ts

@@ -0,0 +1,63 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { IActivityLogger, ActivityLogEntry, IClock, IIdGenerator } from '@beechcms/core'
+
+const ACTIVITY_LOG_INSERT_SQL =
+  `INSERT INTO activity_logs
+     (id, user_id, user_email, user_name, action, entity_type, entity_id, entity_slug, details)
+   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+
+const FALLBACK_USER_EMAIL = 'unknown'
+
+type ScheduleBackgroundTask = (task: Promise<unknown>) => void
+
+/**
+ * D1-backed implementation of {@link IActivityLogger}.
+ *
+ * When `scheduleBackgroundTask` is provided (production path, wired to
+ * `c.executionCtx.waitUntil`), the INSERT runs after the response is sent so
+ * audit logging never adds latency to the user-facing request. When absent
+ * (tests, scripts), the INSERT runs inline and any errors are logged.
+ */
+export class D1ActivityLogger implements IActivityLogger {
+  constructor(
+    private readonly database: D1Database,
+    private readonly clock: IClock,
+    private readonly idGenerator: IIdGenerator,
+    private readonly scheduleBackgroundTask?: ScheduleBackgroundTask
+  ) {}
+
+  log(entry: ActivityLogEntry): Promise<void> | void {
+    const insertPromise = this.runInsert(entry)
+
+    if (this.scheduleBackgroundTask) {
+      this.scheduleBackgroundTask(insertPromise)
+      return
+    }
+
+    return insertPromise
+  }
+
+  private async runInsert(entry: ActivityLogEntry): Promise<void> {
+    try {
+      const recordId = this.idGenerator.uuid()
+      const serializedDetails = entry.details ? JSON.stringify(entry.details) : null
+
+      await this.database
+        .prepare(ACTIVITY_LOG_INSERT_SQL)
+        .bind(
+          recordId,
+          entry.actor.id,
+          entry.actor.email || FALLBACK_USER_EMAIL,
+          entry.actor.name ?? null,
+          entry.action,
+          entry.entityType,
+          entry.entityId,
+          entry.entitySlug ?? null,
+          serializedDetails
+        )
+        .run()
+    } catch (error) {
+      console.error('D1ActivityLogger: failed to persist activity entry', error)
+    }
+  }
+}

package/src/shared/d1-analytics.repository.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi } from 'vitest'
+import { D1AnalyticsRepository } from './d1-analytics.repository'
+import { FixedClock } from './fixed-clock'
+
+const FIXED_NOW_MS = 1700000000_000
+const EXPECTED_DAY_BUCKET = Math.floor(FIXED_NOW_MS / 1000 / 86400) * 86400
+
+function makeMockDb(allResults: unknown[] = [], firstResult: unknown = null) {
+  const allMock = vi.fn().mockResolvedValue({ results: allResults })
+  const firstMock = vi.fn().mockResolvedValue(firstResult)
+  const runMock = vi.fn().mockResolvedValue({ success: true })
+  const bindMock = vi.fn(() => ({ all: allMock, first: firstMock, run: runMock }))
+  const prepareMock = vi.fn(() => ({ bind: bindMock }))
+  return { db: { prepare: prepareMock } as any, prepareMock, bindMock, allMock, firstMock, runMock }
+}
+
+describe('D1AnalyticsRepository', () => {
+  describe('recordRequest', () => {
+    it('issues an INSERT ... ON CONFLICT upsert with seed and computed day bucket', async () => {
+      const { db, prepareMock, bindMock, runMock } = makeMockDb()
+      await new D1AnalyticsRepository(db, new FixedClock(FIXED_NOW_MS)).recordRequest('posts')
+      const sql = prepareMock.mock.calls[0]![0] as string
+      expect(sql).toMatch(/INSERT INTO analytics/)
+      expect(sql).toMatch(/ON CONFLICT\(day_ts, metric, seed\) DO UPDATE SET value = value \+ 1/)
+      expect(bindMock).toHaveBeenCalledWith(EXPECTED_DAY_BUCKET, 'posts')
+      expect(runMock).toHaveBeenCalled()
+    })
+  })
+
+  describe('sumByMetric', () => {
+    it('binds requests metric, seed and since', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb([], { total: 99 })
+      const total = await new D1AnalyticsRepository(db, new FixedClock(FIXED_NOW_MS)).sumByMetric('requests', 'posts', 1)
+      expect(total).toBe(99)
+      const sql = prepareMock.mock.calls[0]![0] as string
+      expect(sql).toMatch(/SELECT SUM\(value\) as total/)
+      expect(sql).toMatch(/WHERE metric = \? AND seed = \? AND day_ts >= \?/)
+      expect(bindMock).toHaveBeenCalledWith('requests', 'posts', 1)
+    })
+
+    it('returns 0 when SUM is null', async () => {
+      const { db } = makeMockDb([], { total: null })
+      const total = await new D1AnalyticsRepository(db, new FixedClock(FIXED_NOW_MS)).sumByMetric('visitors', '', 0)
+      expect(total).toBe(0)
+    })
+
+    it('returns 0 when no row matches', async () => {
+      const { db } = makeMockDb([], null)
+      const total = await new D1AnalyticsRepository(db, new FixedClock(FIXED_NOW_MS)).sumByMetric('requests', '', 0)
+      expect(total).toBe(0)
+    })
+  })
+
+  describe('groupByMetric', () => {
+    it('returns a date_label → count map filtered to metric=requests', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb([
+        { date_label: '2026-01-01', daily_count: 10 },
+        { date_label: '2026-01-02', daily_count: 20 },
+      ])
+      const result = await new D1AnalyticsRepository(db, new FixedClock(FIXED_NOW_MS)).groupByMetric('posts', 1)
+      expect(result).toEqual({ '2026-01-01': 10, '2026-01-02': 20 })
+      const sql = prepareMock.mock.calls[0]![0] as string
+      expect(sql).toMatch(/strftime\('%Y-%m-%d', day_ts, 'unixepoch'\)/)
+      expect(sql).toMatch(/metric = 'requests'/)
+      expect(bindMock).toHaveBeenCalledWith('posts', 1)
+    })
+
+    it('skips rows with null date_label', async () => {
+      const { db } = makeMockDb([{ date_label: null, daily_count: 5 }])
+      const result = await new D1AnalyticsRepository(db, new FixedClock(FIXED_NOW_MS)).groupByMetric('', 0)
+      expect(result).toEqual({})
+    })
+  })
+})

package/src/shared/d1-analytics.repository.ts

@@ -0,0 +1,81 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { IAnalyticsRepository, AnalyticsMetric, IClock } from '@beechcms/core'
+
+const SECONDS_PER_DAY = 86400
+
+/**
+ * D1-backed implementation of {@link IAnalyticsRepository}.
+ *
+ * The underlying schema is long-format:
+ * `analytics(day_ts, metric, seed, value)` with UNIQUE(day_ts, metric, seed).
+ * Each row stores the counter for one (day, metric, seed) tuple. The
+ * IAnalyticsRepository contract is metric-aware (the metric is selected via
+ * a switch on the validated enum), and never interpolates user values into
+ * SQL — the actual metric name is bound through a parameter.
+ */
+export class D1AnalyticsRepository implements IAnalyticsRepository {
+  constructor(
+    private readonly database: D1Database,
+    private readonly clock: IClock,
+  ) {}
+
+  async recordRequest(seedSlug: string): Promise<void> {
+    const dayTimestamp = Math.floor(this.clock.nowSeconds() / SECONDS_PER_DAY) * SECONDS_PER_DAY
+    await this.database
+      .prepare(
+        `INSERT INTO analytics (day_ts, metric, seed, value)
+              VALUES (?, 'requests', ?, 1)
+         ON CONFLICT(day_ts, metric, seed) DO UPDATE SET value = value + 1`,
+      )
+      .bind(dayTimestamp, seedSlug)
+      .run()
+  }
+
+  async sumByMetric(
+    metric: AnalyticsMetric,
+    seedSlug: string,
+    sinceTimestamp: number,
+  ): Promise<number> {
+    const metricName = this.resolveMetricName(metric)
+    const row = await this.database
+      .prepare(
+        `SELECT SUM(value) as total
+           FROM analytics
+          WHERE metric = ? AND seed = ? AND day_ts >= ?`,
+      )
+      .bind(metricName, seedSlug, sinceTimestamp)
+      .first<{ total: number | null }>()
+    return row?.total ?? 0
+  }
+
+  async groupByMetric(
+    seedSlug: string,
+    sinceTimestamp: number,
+  ): Promise<Record<string, number>> {
+    const result = await this.database
+      .prepare(
+        `SELECT strftime('%Y-%m-%d', day_ts, 'unixepoch') as date_label,
+                SUM(value) as daily_count
+           FROM analytics
+          WHERE metric = 'requests' AND seed = ? AND day_ts >= ?
+          GROUP BY date_label
+          ORDER BY date_label ASC`,
+      )
+      .bind(seedSlug, sinceTimestamp)
+      .all<{ date_label: string | null; daily_count: number | null }>()
+
+    const grouped: Record<string, number> = {}
+    for (const row of result.results ?? []) {
+      if (row.date_label === null) continue
+      grouped[row.date_label] = row.daily_count ?? 0
+    }
+    return grouped
+  }
+
+  private resolveMetricName(metric: AnalyticsMetric): string {
+    switch (metric) {
+      case 'requests': return 'requests'
+      case 'visitors': return 'visitors'
+    }
+  }
+}

package/src/shared/d1-content-scan.repository.ts

@@ -0,0 +1,29 @@
+import type { D1Database } from '@cloudflare/workers-types'
+import type { IContentScanRepository, Seed } from '@beechcms/core'
+
+export class D1ContentScanRepository implements IContentScanRepository {
+  constructor(private readonly db: D1Database) {}
+
+  async getReferencedMediaKeys(seeds: Seed[]): Promise<Set<string>> {
+    const referencedMediaKeys = new Set<string>()
+
+    for (const seed of seeds) {
+      const mediaFields = seed.branches.filter(branch => branch.type === 'file')
+      if (mediaFields.length === 0) continue
+
+      const mediaColumns = mediaFields.map(field => field.alias).join(', ')
+      const contentData = await this.db.prepare(
+        `SELECT ${mediaColumns} FROM content_${seed.slug}`
+      ).all<Record<string, string | null>>()
+
+      for (const contentRow of contentData.results ?? []) {
+        const rowContentString = Object.values(contentRow).filter(Boolean).join(' ')
+        for (const keyMatch of rowContentString.matchAll(/\/api\/media\/([^"'\s\\,}\]]+)/g)) {
+          referencedMediaKeys.add(decodeURIComponent(keyMatch[1]))
+        }
+      }
+    }
+
+    return referencedMediaKeys
+  }
+}

package/src/shared/d1-notification.repository.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi } from 'vitest'
+import { D1NotificationRepository } from './d1-notification.repository'
+import { FixedClock } from './fixed-clock'
+import { SequentialIdGenerator } from './sequential-id-generator'
+
+const clock = new FixedClock(1700000000_000)
+const makeIdGen = () => new SequentialIdGenerator()
+
+function makeMockDb(opts: { firstResult?: unknown; allResults?: unknown[] } = {}) {
+  const { firstResult = null, allResults = [] } = opts
+  const runMock = vi.fn().mockResolvedValue({ success: true })
+  const firstMock = vi.fn().mockResolvedValue(firstResult)
+  const allMock = vi.fn().mockResolvedValue({ results: allResults })
+  const bindMock = vi.fn(() => ({ first: firstMock, all: allMock, run: runMock }))
+  const prepareMock = vi.fn(() => ({
+    bind: bindMock,
+    first: firstMock,
+    all: allMock,
+    run: runMock,
+  }))
+  return { db: { prepare: prepareMock } as any, prepareMock, bindMock, runMock, firstMock, allMock }
+}
+
+describe('D1NotificationRepository', () => {
+  describe('list', () => {
+    it('maps rows to NotificationRecord with isRead boolean', async () => {
+      const { db } = makeMockDb({
+        allResults: [
+          {
+            id: 'n-1',
+            title: 'T',
+            message: 'M',
+            type: 'success',
+            is_read: 0,
+            created_at: 100,
+          },
+          {
+            id: 'n-2',
+            title: 'T2',
+            message: 'M2',
+            type: 'info',
+            is_read: 1,
+            created_at: 99,
+          },
+        ],
+      })
+      const records = await new D1NotificationRepository(db, clock, makeIdGen()).list(10)
+      expect(records).toEqual([
+        { id: 'n-1', title: 'T', message: 'M', type: 'success', isRead: false, createdAt: 100 },
+        { id: 'n-2', title: 'T2', message: 'M2', type: 'info', isRead: true, createdAt: 99 },
+      ])
+    })
+
+    it('orders by created_at DESC with LIMIT bound', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      await new D1NotificationRepository(db, clock, makeIdGen()).list(25)
+      expect(prepareMock.mock.calls[0][0]).toMatch(/ORDER BY created_at DESC/)
+      expect(bindMock).toHaveBeenCalledWith(25)
+    })
+  })
+
+  describe('stats', () => {
+    it('returns aggregate counters mapped to camelCase', async () => {
+      const { db } = makeMockDb({
+        firstResult: { total_count: 7, latest_created_at: 1234, read_count: 3 },
+      })
+      const stats = await new D1NotificationRepository(db, clock, makeIdGen()).stats()
+      expect(stats).toEqual({ totalCount: 7, latestCreatedAt: 1234, readCount: 3 })
+    })
+
+    it('returns zeros when the table is empty', async () => {
+      const { db } = makeMockDb({
+        firstResult: { total_count: 0, latest_created_at: null, read_count: null },
+      })
+      const stats = await new D1NotificationRepository(db, clock, makeIdGen()).stats()
+      expect(stats).toEqual({ totalCount: 0, latestCreatedAt: 0, readCount: 0 })
+    })
+  })
+
+  describe('create', () => {
+    it('inserts a new notification and returns the generated id', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      const id = await new D1NotificationRepository(db, clock, makeIdGen()).create({
+        title: 'Hello',
+        message: 'World',
+        type: 'info',
+      })
+      expect(typeof id).toBe('string')
+      expect(id.length).toBeGreaterThan(0)
+      expect(prepareMock.mock.calls[0][0]).toMatch(/INSERT INTO notifications/)
+      expect(bindMock).toHaveBeenCalledWith(id, 'Hello', 'World', 'info')
+    })
+  })
+
+  describe('markRead / markUnread / delete / markAllRead', () => {
+    it('markRead binds the given id', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      await new D1NotificationRepository(db, clock, makeIdGen()).markRead('n-1')
+      expect(prepareMock.mock.calls[0][0]).toMatch(/UPDATE notifications SET is_read = 1 WHERE id = \?/)
+      expect(bindMock).toHaveBeenCalledWith('n-1')
+    })
+
+    it('markUnread binds the given id', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      await new D1NotificationRepository(db, clock, makeIdGen()).markUnread('n-2')
+      expect(prepareMock.mock.calls[0][0]).toMatch(/UPDATE notifications SET is_read = 0 WHERE id = \?/)
+      expect(bindMock).toHaveBeenCalledWith('n-2')
+    })
+
+    it('delete binds the given id', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      await new D1NotificationRepository(db, clock, makeIdGen()).delete('n-3')
+      expect(prepareMock.mock.calls[0][0]).toMatch(/DELETE FROM notifications WHERE id = \?/)
+      expect(bindMock).toHaveBeenCalledWith('n-3')
+    })
+
+    it('markAllRead runs without bindings', async () => {
+      const { db, prepareMock, runMock } = makeMockDb()
+      await new D1NotificationRepository(db, clock, makeIdGen()).markAllRead()
+      expect(prepareMock.mock.calls[0][0]).toMatch(/^UPDATE notifications SET is_read = 1$/)
+      expect(runMock).toHaveBeenCalled()
+    })
+  })
+})

package/src/shared/d1-notification.repository.ts

@@ -0,0 +1,114 @@
+/// <reference types="@cloudflare/workers-types" />
+import type {
+  INotificationRepository,
+  NotificationRecord,
+  NotificationStats,
+  NotificationType,
+  IClock,
+  IIdGenerator,
+} from '@beechcms/core'
+
+interface NotificationRow {
+  id: string
+  title: string
+  message: string
+  type: string
+  is_read: number
+  created_at: number
+}
+
+interface NotificationStatsRow {
+  total_count: number | null
+  latest_created_at: number | null
+  read_count: number | null
+}
+
+/**
+ * D1-backed implementation of {@link INotificationRepository}.
+ */
+export class D1NotificationRepository implements INotificationRepository {
+  constructor(
+    private readonly database: D1Database,
+    private readonly clock: IClock,
+    private readonly idGenerator: IIdGenerator,
+  ) {}
+
+  async list(limit: number): Promise<NotificationRecord[]> {
+    const queryResult = await this.database
+      .prepare(
+        `SELECT id, title, message, type, is_read, created_at
+           FROM notifications
+           ORDER BY created_at DESC
+           LIMIT ?`
+      )
+      .bind(limit)
+      .all<NotificationRow>()
+
+    return (queryResult.results ?? []).map(mapRowToRecord)
+  }
+
+  async stats(): Promise<NotificationStats> {
+    const statsRow = await this.database
+      .prepare(
+        `SELECT COUNT(*) as total_count,
+                MAX(created_at) as latest_created_at,
+                SUM(is_read) as read_count
+           FROM notifications`
+      )
+      .first<NotificationStatsRow>()
+
+    return {
+      totalCount: statsRow?.total_count ?? 0,
+      latestCreatedAt: statsRow?.latest_created_at ?? 0,
+      readCount: statsRow?.read_count ?? 0,
+    }
+  }
+
+  async create(record: Omit<NotificationRecord, 'id' | 'createdAt' | 'isRead'>): Promise<string> {
+    const generatedId = this.idGenerator.uuid()
+    await this.database
+      .prepare(
+        `INSERT INTO notifications (id, title, message, type)
+         VALUES (?, ?, ?, ?)`
+      )
+      .bind(generatedId, record.title, record.message, record.type)
+      .run()
+    return generatedId
+  }
+
+  async markRead(notificationId: string): Promise<void> {
+    await this.database
+      .prepare('UPDATE notifications SET is_read = 1 WHERE id = ?')
+      .bind(notificationId)
+      .run()
+  }
+
+  async markUnread(notificationId: string): Promise<void> {
+    await this.database
+      .prepare('UPDATE notifications SET is_read = 0 WHERE id = ?')
+      .bind(notificationId)
+      .run()
+  }
+
+  async markAllRead(): Promise<void> {
+    await this.database.prepare('UPDATE notifications SET is_read = 1').run()
+  }
+
+  async delete(notificationId: string): Promise<void> {
+    await this.database
+      .prepare('DELETE FROM notifications WHERE id = ?')
+      .bind(notificationId)
+      .run()
+  }
+}
+
+function mapRowToRecord(row: NotificationRow): NotificationRecord {
+  return {
+    id: row.id,
+    title: row.title,
+    message: row.message,
+    type: row.type as NotificationType,
+    isRead: row.is_read === 1,
+    createdAt: row.created_at,
+  }
+}

package/src/shared/d1-password-reset-token.repository.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi } from 'vitest'
+import { D1PasswordResetTokenRepository } from './d1-password-reset-token.repository'
+
+const NOW = Math.floor(Date.now() / 1000)
+const fixedIdGen = { uuid: () => 'prt-1' }
+
+function makeMockDb(opts: { firstResult?: unknown; runChanges?: number } = {}) {
+  const { firstResult = null, runChanges = 1 } = opts
+  const runMock = vi.fn().mockResolvedValue({ success: true, meta: { changes: runChanges } })
+  const firstMock = vi.fn().mockResolvedValue(firstResult)
+  const bindMock = vi.fn(() => ({ first: firstMock, run: runMock }))
+  const prepareMock = vi.fn(() => ({ bind: bindMock }))
+  return { db: { prepare: prepareMock } as any, prepareMock, bindMock, runMock }
+}
+
+describe('D1PasswordResetTokenRepository', () => {
+  describe('create', () => {
+    it('calls INSERT INTO password_reset_tokens', async () => {
+      const { db, prepareMock } = makeMockDb()
+      await new D1PasswordResetTokenRepository(db, fixedIdGen).create({
+        userId: 'u1', tokenHash: 'h', expiresAt: NOW + 1800,
+      })
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('INSERT INTO password_reset_tokens'))
+    })
+
+    it('binds id, userId, tokenHash, and expiresAt in the correct order', async () => {
+      const { db, bindMock } = makeMockDb()
+      await new D1PasswordResetTokenRepository(db, fixedIdGen).create({
+        userId: 'u1', tokenHash: 'h', expiresAt: NOW + 1800,
+      })
+      expect(bindMock).toHaveBeenCalledWith('prt-1', 'u1', 'h', NOW + 1800)
+    })
+  })
+
+  describe('findValidByHashWithEmail', () => {
+    it('returns a ValidatedResetToken with the userId and email from the JOIN', async () => {
+      const row = { id: 'prt-1', user_id: 'u1', email: 'user@test.com' }
+      const { db } = makeMockDb({ firstResult: row })
+      const result = await new D1PasswordResetTokenRepository(db, fixedIdGen).findValidByHashWithEmail('h', NOW)
+      expect(result).toEqual({ id: 'prt-1', userId: 'u1', email: 'user@test.com' })
+    })
+
+    it('returns null when the token is not found, expired, or already used', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      expect(await new D1PasswordResetTokenRepository(db, fixedIdGen).findValidByHashWithEmail('bad-hash', NOW)).toBeNull()
+    })
+
+    it('passes tokenHash and nowTimestamp as bound values', async () => {
+      const { db, bindMock } = makeMockDb()
+      await new D1PasswordResetTokenRepository(db, fixedIdGen).findValidByHashWithEmail('my-hash', NOW)
+      expect(bindMock).toHaveBeenCalledWith('my-hash', NOW)
+    })
+  })
+
+  describe('markUsed', () => {
+    it('calls UPDATE password_reset_tokens SET used_at', async () => {
+      const { db, prepareMock } = makeMockDb()
+      await new D1PasswordResetTokenRepository(db, fixedIdGen).markUsed('prt-1', NOW)
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('used_at'))
+    })
+
+    it('binds nowTimestamp and tokenId in the correct order', async () => {
+      const { db, bindMock } = makeMockDb()
+      await new D1PasswordResetTokenRepository(db, fixedIdGen).markUsed('prt-1', NOW)
+      expect(bindMock).toHaveBeenCalledWith(NOW, 'prt-1')
+    })
+  })
+
+  describe('invalidatePending', () => {
+    it('calls UPDATE password_reset_tokens and includes the userId in the bound values', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      await new D1PasswordResetTokenRepository(db, fixedIdGen).invalidatePending('u1', NOW)
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('UPDATE password_reset_tokens'))
+      expect((bindMock.mock.calls[0] as unknown[]).includes('u1')).toBe(true)
+    })
+  })
+})

package/src/shared/d1-password-reset-token.repository.ts

@@ -0,0 +1,52 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { IPasswordResetTokenRepository, NewPasswordResetToken, ValidatedResetToken, IIdGenerator } from '@beechcms/core'
+
+type ValidatedResetTokenRow = {
+  id: string
+  user_id: string
+  email: string
+}
+
+export class D1PasswordResetTokenRepository implements IPasswordResetTokenRepository {
+  constructor(
+    private readonly db: D1Database,
+    private readonly idGenerator: IIdGenerator,
+  ) {}
+
+  async invalidatePending(userId: string, nowTimestamp: number): Promise<void> {
+    await this.db
+      .prepare('UPDATE password_reset_tokens SET used_at = ? WHERE user_id = ? AND used_at IS NULL')
+      .bind(nowTimestamp, userId)
+      .run()
+  }
+
+  async create(record: NewPasswordResetToken): Promise<void> {
+    const generatedId = this.idGenerator.uuid()
+    await this.db
+      .prepare('INSERT INTO password_reset_tokens (id, user_id, token_hash, expires_at) VALUES (?, ?, ?, ?)')
+      .bind(generatedId, record.userId, record.tokenHash, record.expiresAt)
+      .run()
+  }
+
+  async findValidByHashWithEmail(tokenHash: string, nowTimestamp: number): Promise<ValidatedResetToken | null> {
+    const row = await this.db
+      .prepare(
+        `SELECT prt.id, prt.user_id, u.email
+         FROM password_reset_tokens prt
+         JOIN users u ON u.id = prt.user_id
+         WHERE prt.token_hash = ? AND prt.expires_at > ? AND prt.used_at IS NULL`
+      )
+      .bind(tokenHash, nowTimestamp)
+      .first<ValidatedResetTokenRow>()
+
+    if (!row) return null
+    return { id: row.id, userId: row.user_id, email: row.email }
+  }
+
+  async markUsed(tokenId: string, nowTimestamp: number): Promise<void> {
+    await this.db
+      .prepare('UPDATE password_reset_tokens SET used_at = ? WHERE id = ?')
+      .bind(nowTimestamp, tokenId)
+      .run()
+  }
+}