@beechcms/api 0.4.0 → 0.4.1

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

@@ -0,0 +1,217 @@
+import { describe, it, expect, vi } from 'vitest'
+import type { Seed } from '@beechcms/core'
+import { D1WidgetRepository } from './d1-widget.repository'
+
+function makeMockDb(allResults: unknown[] = [], firstResult: unknown = null) {
+  const allMock = vi.fn().mockResolvedValue({ results: allResults })
+  const firstMock = vi.fn().mockResolvedValue(firstResult)
+  const bindMock = vi.fn(() => ({ all: allMock, first: firstMock }))
+  const prepareMock = vi.fn(() => ({ all: allMock, first: firstMock, bind: bindMock }))
+  return { db: { prepare: prepareMock } as any, prepareMock, bindMock, allMock, firstMock }
+}
+
+const seed: Seed = {
+  slug: 'posts',
+  label: 'Post',
+  displayNameAlias: 'title',
+  branches: [
+    { id: 'br_01', alias: 'title', type: 'text', label: 'Title' },
+    { id: 'br_02', alias: 'price', type: 'number', label: 'Price' },
+  ],
+}
+
+describe('D1WidgetRepository', () => {
+  describe('aggregate', () => {
+    it('returns 0 when no rows match', async () => {
+      const { db } = makeMockDb([], null)
+      const value = await new D1WidgetRepository(db).aggregate(seed, { op: 'count' }, 'all')
+      expect(value).toBe(0)
+    })
+
+    it('builds COUNT(*) for op=count', async () => {
+      const { db, prepareMock } = makeMockDb([], { computed_value: 7 })
+      const value = await new D1WidgetRepository(db).aggregate(seed, { op: 'count' }, 'week')
+      expect(value).toBe(7)
+      const sql = prepareMock.mock.calls[0]![0] as string
+      expect(sql).toMatch(/COUNT\(\*\)/)
+      expect(sql).toMatch(/FROM content_posts/)
+      expect(sql).toMatch(/created_at > unixepoch\('now', '-7 days'\)/)
+    })
+
+    it('throws UNSAFE_COLUMN when column alias is unknown', async () => {
+      const { db } = makeMockDb()
+      await expect(
+        new D1WidgetRepository(db).aggregate(seed, { op: 'sum', column: 'unknown' }, 'all'),
+      ).rejects.toThrow('UNSAFE_COLUMN')
+    })
+
+    it('builds SUM(CAST(... AS REAL)) for valid column', async () => {
+      const { db, prepareMock } = makeMockDb([], { computed_value: 42 })
+      await new D1WidgetRepository(db).aggregate(seed, { op: 'sum', column: 'price' }, 'all')
+      expect(prepareMock.mock.calls[0]![0] as string).toMatch(/SUM\(CAST\(price AS REAL\)\)/)
+    })
+  })
+
+  describe('growth', () => {
+    it('runs two queries with current and previous filters', async () => {
+      const allMock = vi.fn().mockResolvedValue({ results: [] })
+      const firstMock = vi
+        .fn()
+        .mockResolvedValueOnce({ computed_value: 10 })
+        .mockResolvedValueOnce({ computed_value: 5 })
+      const bindMock = vi.fn(() => ({ all: allMock, first: firstMock }))
+      const prepareMock = vi.fn(() => ({ all: allMock, first: firstMock, bind: bindMock }))
+      const db = { prepare: prepareMock } as any
+
+      const result = await new D1WidgetRepository(db).growth(seed, { op: 'count' }, 'month')
+      expect(result).toEqual({ currentValue: 10, previousValue: 5 })
+      expect(prepareMock).toHaveBeenCalledTimes(2)
+      const sql0 = prepareMock.mock.calls[0]![0] as string
+      const sql1 = prepareMock.mock.calls[1]![0] as string
+      expect(sql0).toMatch(/-1 month/)
+      expect(sql1).toMatch(/-2 months/)
+    })
+
+    it('returns zeros when both queries are empty', async () => {
+      const { db } = makeMockDb([], null)
+      const result = await new D1WidgetRepository(db).growth(seed, { op: 'count' }, 'all')
+      expect(result).toEqual({ currentValue: 0, previousValue: 0 })
+    })
+  })
+
+  describe('leaderboard', () => {
+    it('uses ORDER BY DESC by default and binds only the limit', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb([
+        { id: 'a', label: 'A', score: 9 },
+      ])
+      const entries = await new D1WidgetRepository(db).leaderboard(seed, {
+        scoreColumn: 'price',
+        limit: 5,
+        orderDirection: 'DESC',
+      })
+      expect(entries).toEqual([{ id: 'a', label: 'A', score: 9 }])
+      const sql = prepareMock.mock.calls[0]![0] as string
+      expect(sql).toMatch(/ORDER BY CAST\(price AS REAL\) DESC/)
+      expect(bindMock).toHaveBeenCalledWith(5)
+    })
+
+    it('uses ORDER BY ASC when requested', async () => {
+      const { db, prepareMock } = makeMockDb([])
+      await new D1WidgetRepository(db).leaderboard(seed, {
+        scoreColumn: 'price',
+        limit: 3,
+        orderDirection: 'ASC',
+      })
+      expect(prepareMock.mock.calls[0]![0] as string).toMatch(/ORDER BY CAST\(price AS REAL\) ASC/)
+    })
+
+    it('falls back to id when label is null', async () => {
+      const { db } = makeMockDb([{ id: 'x', label: null, score: 1 }])
+      const [entry] = await new D1WidgetRepository(db).leaderboard(seed, {
+        scoreColumn: 'price',
+        limit: 1,
+        orderDirection: 'DESC',
+      })
+      expect(entry).toEqual({ id: 'x', label: 'x', score: 1 })
+    })
+  })
+
+  describe('list', () => {
+    it('returns raw rows and totalCount', async () => {
+      const allMock = vi.fn().mockResolvedValue({ results: [{ id: '1', slug: 's', status: 'published', created_at: 1, updated_at: 2, title: 'T', price: 10 }] })
+      const firstMock = vi.fn().mockResolvedValue({ total: 7 })
+      const bindMock = vi.fn(() => ({ all: allMock, first: firstMock }))
+      const prepareMock = vi.fn(() => ({ all: allMock, first: firstMock, bind: bindMock }))
+      const db = { prepare: prepareMock } as any
+
+      const result = await new D1WidgetRepository(db).list(seed, { limit: 10, offset: 0 })
+      expect(result.totalCount).toBe(7)
+      expect(result.entries[0]?.title).toBe('T')
+    })
+
+    it('appends search LIKE filter against displayNameAlias column', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb([], { total: 0 })
+      await new D1WidgetRepository(db).list(seed, { limit: 5, offset: 0, search: 'hello' })
+      const sql = (prepareMock.mock.calls[1]?.[0] ?? prepareMock.mock.calls[0]![0]) as string
+      expect(sql).toMatch(/title LIKE \?/)
+      expect(bindMock).toHaveBeenCalledWith('%hello%', 5, 0)
+    })
+
+    it('skips filters with unknown operator', async () => {
+      const { db, prepareMock } = makeMockDb([], { total: 0 })
+      await new D1WidgetRepository(db).list(seed, {
+        limit: 5,
+        offset: 0,
+        filters: [{ column: 'price', op: 'haxx', value: 1 }],
+      })
+      const dataSql = prepareMock.mock.calls[1]![0] as string
+      expect(dataSql).not.toMatch(/haxx/)
+    })
+
+    it('skips filters with unsafe column', async () => {
+      const { db, prepareMock } = makeMockDb([], { total: 0 })
+      await new D1WidgetRepository(db).list(seed, {
+        limit: 5,
+        offset: 0,
+        filters: [{ column: 'evil', op: 'eq', value: 1 }],
+      })
+      const dataSql = prepareMock.mock.calls[1]![0] as string
+      expect(dataSql).not.toMatch(/evil/)
+    })
+
+    it('uses ORDER BY DESC branch when requested', async () => {
+      const { db, prepareMock } = makeMockDb([], { total: 0 })
+      await new D1WidgetRepository(db).list(seed, {
+        limit: 5,
+        offset: 0,
+        orderByColumn: 'price',
+        orderDirection: 'DESC',
+      })
+      const dataSql = prepareMock.mock.calls[1]![0] as string
+      expect(dataSql).toMatch(/ORDER BY price DESC/)
+    })
+
+    it('falls back to created_at when orderByColumn is unsafe', async () => {
+      const { db, prepareMock } = makeMockDb([], { total: 0 })
+      await new D1WidgetRepository(db).list(seed, {
+        limit: 5,
+        offset: 0,
+        orderByColumn: 'evil',
+      })
+      const dataSql = prepareMock.mock.calls[1]![0] as string
+      expect(dataSql).toMatch(/ORDER BY created_at/)
+    })
+  })
+
+  describe('timeseries', () => {
+    it('groups by date bucket on created_at', async () => {
+      const { db, prepareMock } = makeMockDb([
+        { bucket_label: '2026-01-01', bucket_value: 3 },
+      ])
+      const points = await new D1WidgetRepository(db).timeseries(
+        seed,
+        { op: 'count' },
+        'all',
+        'created_at',
+      )
+      expect(points).toEqual([{ label: '2026-01-01', value: 3 }])
+      const sql = prepareMock.mock.calls[0]![0] as string
+      expect(sql).toMatch(/strftime\('%Y-%m-%d', created_at, 'unixepoch'\)/)
+      expect(sql).toMatch(/GROUP BY bucket_label/)
+    })
+
+    it('CASTs non-system group columns as INTEGER', async () => {
+      const { db, prepareMock } = makeMockDb([])
+      await new D1WidgetRepository(db).timeseries(seed, { op: 'count' }, 'all', 'price')
+      const sql = prepareMock.mock.calls[0]![0] as string
+      expect(sql).toMatch(/CAST\(price AS INTEGER\)/)
+    })
+
+    it('throws UNSAFE_COLUMN for invalid groupColumn', async () => {
+      const { db } = makeMockDb()
+      await expect(
+        new D1WidgetRepository(db).timeseries(seed, { op: 'count' }, 'all', 'evil'),
+      ).rejects.toThrow('UNSAFE_COLUMN')
+    })
+  })
+})

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

@@ -0,0 +1,337 @@
+/// <reference types="@cloudflare/workers-types" />
+import type {
+  Seed,
+  IWidgetRepository,
+  AggregateFormula,
+  TimeWindow,
+  LeaderboardEntry,
+  LeaderboardOptions,
+  TimeseriesPoint,
+  WidgetListOptions,
+  WidgetListResult,
+  GrowthResult,
+} from '@beechcms/core'
+
+const SYSTEM_COLUMNS: ReadonlySet<string> = new Set([
+  'id',
+  'slug',
+  'status',
+  'created_at',
+  'updated_at',
+])
+
+const ALLOWED_FILTER_OPERATORS: ReadonlySet<string> = new Set([
+  'eq',
+  '=',
+  'neq',
+  '!=',
+  'like',
+  'gt',
+  '>',
+  'lt',
+  '<',
+])
+
+const UNSAFE_COLUMN_ERROR = 'UNSAFE_COLUMN'
+
+/**
+ * D1-backed implementation of {@link IWidgetRepository}.
+ *
+ * All user-supplied values are bound via parameterised statements. Column
+ * aliases originating from query strings are validated against the seed
+ * before being composed into the SQL string, preventing column-name
+ * injection. SQL keywords (aggregate function names, ORDER direction) are
+ * selected via hardcoded branches.
+ */
+export class D1WidgetRepository implements IWidgetRepository {
+  constructor(private readonly database: D1Database) {}
+
+  async aggregate(seed: Seed, formula: AggregateFormula, window: TimeWindow): Promise<number> {
+    const aggregateExpression = this.buildAggregateExpression(seed, formula)
+    const timeWindowFilter = this.buildTimeWindowFilter(window)
+    const tableName = `content_${seed.slug}`
+
+    const sql =
+      `SELECT ${aggregateExpression} as computed_value
+         FROM ${tableName}
+        WHERE ${timeWindowFilter}`
+
+    const row = await this.database.prepare(sql).first<{ computed_value: number | null }>()
+    return row?.computed_value ?? 0
+  }
+
+  async growth(
+    seed: Seed,
+    formula: AggregateFormula,
+    window: TimeWindow,
+  ): Promise<GrowthResult> {
+    const aggregateExpression = this.buildAggregateExpression(seed, formula)
+    const { currentFilter, previousFilter } = this.buildPreviousWindowFilter(window)
+    const tableName = `content_${seed.slug}`
+
+    const [currentRow, previousRow] = await Promise.all([
+      this.database
+        .prepare(`SELECT ${aggregateExpression} as computed_value FROM ${tableName} WHERE ${currentFilter}`)
+        .first<{ computed_value: number | null }>(),
+      this.database
+        .prepare(`SELECT ${aggregateExpression} as computed_value FROM ${tableName} WHERE ${previousFilter}`)
+        .first<{ computed_value: number | null }>(),
+    ])
+
+    return {
+      currentValue: currentRow?.computed_value ?? 0,
+      previousValue: previousRow?.computed_value ?? 0,
+    }
+  }
+
+  async leaderboard(seed: Seed, options: LeaderboardOptions): Promise<LeaderboardEntry[]> {
+    const scoreColumn = this.resolveColumnExpression(seed, options.scoreColumn)
+    const labelColumn = this.resolveColumnExpression(seed, seed.displayNameAlias)
+    const tableName = `content_${seed.slug}`
+    const orderClause = options.orderDirection === 'ASC'
+      ? `ORDER BY CAST(${scoreColumn} AS REAL) ASC`
+      : `ORDER BY CAST(${scoreColumn} AS REAL) DESC`
+
+    const sql =
+      `SELECT id, ${labelColumn} as label, ${scoreColumn} as score
+         FROM ${tableName}
+        WHERE ${scoreColumn} IS NOT NULL
+        ${orderClause}
+        LIMIT ?`
+
+    const rows = await this.database
+      .prepare(sql)
+      .bind(options.limit)
+      .all<{ id: string; label: string | null; score: number | string | null }>()
+
+    return (rows.results ?? []).map(row => ({
+      id: row.id,
+      label: row.label ?? row.id,
+      score: row.score ?? 0,
+    }))
+  }
+
+  async list(seed: Seed, options: WidgetListOptions): Promise<WidgetListResult> {
+    const tableName = `content_${seed.slug}`
+    const conditions: string[] = []
+    const bindings: unknown[] = []
+
+    const trimmedSearch = options.search?.trim() ?? ''
+    if (trimmedSearch.length > 0) {
+      const displayColumn = this.resolveColumnExpression(seed, seed.displayNameAlias)
+      conditions.push(`${displayColumn} LIKE ?`)
+      bindings.push(`%${trimmedSearch}%`)
+    }
+
+    for (const filter of options.filters ?? []) {
+      this.appendFilterCondition(seed, filter, conditions, bindings)
+    }
+
+    const whereSql = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+    const orderClause = this.buildListOrderClause(seed, options)
+    const branchColumns = seed.branches.map(branch => branch.alias).join(', ')
+    const selectColumns = branchColumns.length > 0
+      ? `id, slug, status, created_at, updated_at, ${branchColumns}`
+      : `id, slug, status, created_at, updated_at`
+
+    const dataSql =
+      `SELECT ${selectColumns}
+         FROM ${tableName}
+         ${whereSql}
+         ${orderClause}
+         LIMIT ? OFFSET ?`
+
+    const countSql = `SELECT COUNT(*) as total FROM ${tableName} ${whereSql}`
+
+    const [countRow, listRows] = await Promise.all([
+      this.database.prepare(countSql).bind(...bindings).first<{ total: number }>(),
+      this.database
+        .prepare(dataSql)
+        .bind(...bindings, options.limit, options.offset)
+        .all<Record<string, unknown>>(),
+    ])
+
+    return {
+      entries: listRows.results ?? [],
+      totalCount: countRow?.total ?? 0,
+    }
+  }
+
+  async timeseries(
+    seed: Seed,
+    formula: AggregateFormula,
+    window: TimeWindow,
+    groupColumn: string,
+  ): Promise<TimeseriesPoint[]> {
+    const groupColumnExpression = this.resolveColumnExpression(seed, groupColumn)
+    const aggregateExpression = this.buildAggregateExpression(seed, formula)
+    const timeWindowFilter = this.buildTimeWindowFilter(window)
+    const tableName = `content_${seed.slug}`
+
+    const dateBucketExpression = groupColumnExpression === 'created_at'
+      ? `strftime('%Y-%m-%d', created_at, 'unixepoch')`
+      : `strftime('%Y-%m-%d', CAST(${groupColumnExpression} AS INTEGER), 'unixepoch')`
+
+    const sql =
+      `SELECT ${dateBucketExpression} as bucket_label,
+              ${aggregateExpression} as bucket_value
+         FROM ${tableName}
+        WHERE ${timeWindowFilter}
+        GROUP BY bucket_label
+        ORDER BY bucket_label ASC`
+
+    const rows = await this.database
+      .prepare(sql)
+      .all<{ bucket_label: string | null; bucket_value: number | null }>()
+
+    return (rows.results ?? []).map(row => ({
+      label: row.bucket_label ?? '',
+      value: row.bucket_value ?? 0,
+    }))
+  }
+
+  /**
+   * Throws UNSAFE_COLUMN if the alias is neither a system column nor a
+   * declared seed branch, preventing SQL injection via column names.
+   */
+  private resolveColumnExpression(seed: Seed, alias: string): string {
+    if (SYSTEM_COLUMNS.has(alias)) return alias
+    const branch = seed.branches.find(candidate => candidate.alias === alias)
+    if (!branch) throw new Error(UNSAFE_COLUMN_ERROR)
+    return branch.alias
+  }
+
+  private buildAggregateExpression(seed: Seed, formula: AggregateFormula): string {
+    switch (formula.op) {
+      case 'count':
+        return 'COUNT(*)'
+      case 'sum': {
+        const column = this.resolveColumnExpression(seed, formula.column)
+        return `SUM(CAST(${column} AS REAL))`
+      }
+      case 'avg': {
+        const column = this.resolveColumnExpression(seed, formula.column)
+        return `AVG(CAST(${column} AS REAL))`
+      }
+      case 'min': {
+        const column = this.resolveColumnExpression(seed, formula.column)
+        return `MIN(CAST(${column} AS REAL))`
+      }
+      case 'max': {
+        const column = this.resolveColumnExpression(seed, formula.column)
+        return `MAX(CAST(${column} AS REAL))`
+      }
+      case 'countWhere':
+        return this.buildCountWhereExpression(seed, formula.column, formula.value)
+      case 'percentageOf': {
+        const numerator = this.resolveColumnExpression(seed, formula.numeratorColumn)
+        const denominator = this.resolveColumnExpression(seed, formula.denominatorColumn)
+        return `CASE WHEN SUM(CAST(${denominator} AS REAL)) = 0 THEN 0 ELSE (SUM(CAST(${numerator} AS REAL)) * 100.0 / SUM(CAST(${denominator} AS REAL))) END`
+      }
+    }
+  }
+
+  private buildCountWhereExpression(seed: Seed, alias: string, value: unknown): string {
+    const column = this.resolveColumnExpression(seed, alias)
+    if (value === null) return `COUNT(CASE WHEN ${column} IS NULL THEN 1 END)`
+    if (typeof value === 'boolean') {
+      const numericValue = value ? 1 : 0
+      return `COUNT(CASE WHEN ${column} = ${numericValue} THEN 1 END)`
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return `COUNT(CASE WHEN CAST(${column} AS REAL) = ${value} THEN 1 END)`
+    }
+    const escaped = String(value).replace(/'/g, "''")
+    return `COUNT(CASE WHEN ${column} = '${escaped}' THEN 1 END)`
+  }
+
+  private buildTimeWindowFilter(window: TimeWindow): string {
+    switch (window) {
+      case 'week':  return "created_at > unixepoch('now', '-7 days')"
+      case 'month': return "created_at > unixepoch('now', '-1 month')"
+      case 'year':  return "created_at > unixepoch('now', '-1 year')"
+      case 'all':   return '1=1'
+    }
+  }
+
+  private buildPreviousWindowFilter(
+    window: TimeWindow,
+  ): { currentFilter: string; previousFilter: string } {
+    switch (window) {
+      case 'week':
+        return {
+          currentFilter:  "created_at > unixepoch('now', '-7 days')",
+          previousFilter: "created_at > unixepoch('now', '-14 days') AND created_at <= unixepoch('now', '-7 days')",
+        }
+      case 'month':
+        return {
+          currentFilter:  "created_at > unixepoch('now', '-1 month')",
+          previousFilter: "created_at > unixepoch('now', '-2 months') AND created_at <= unixepoch('now', '-1 month')",
+        }
+      case 'year':
+        return {
+          currentFilter:  "created_at > unixepoch('now', '-1 year')",
+          previousFilter: "created_at > unixepoch('now', '-2 years') AND created_at <= unixepoch('now', '-1 year')",
+        }
+      case 'all':
+        return { currentFilter: '1=1', previousFilter: '1=0' }
+    }
+  }
+
+  private appendFilterCondition(
+    seed: Seed,
+    filter: { column: string; op: string; value: unknown },
+    conditions: string[],
+    bindings: unknown[],
+  ): void {
+    if (!ALLOWED_FILTER_OPERATORS.has(filter.op)) return
+
+    let column: string
+    try {
+      column = this.resolveColumnExpression(seed, filter.column)
+    } catch {
+      return
+    }
+
+    switch (filter.op) {
+      case 'eq':
+      case '=':
+        conditions.push(`${column} = ?`)
+        bindings.push(filter.value)
+        return
+      case 'neq':
+      case '!=':
+        conditions.push(`${column} != ?`)
+        bindings.push(filter.value)
+        return
+      case 'like':
+        conditions.push(`${column} LIKE ?`)
+        bindings.push(filter.value)
+        return
+      case 'gt':
+      case '>':
+        conditions.push(`CAST(${column} AS REAL) > ?`)
+        bindings.push(filter.value)
+        return
+      case 'lt':
+      case '<':
+        conditions.push(`CAST(${column} AS REAL) < ?`)
+        bindings.push(filter.value)
+        return
+    }
+  }
+
+  private buildListOrderClause(seed: Seed, options: WidgetListOptions): string {
+    let orderColumn = 'created_at'
+    if (options.orderByColumn) {
+      try {
+        orderColumn = this.resolveColumnExpression(seed, options.orderByColumn)
+      } catch {
+        orderColumn = 'created_at'
+      }
+    }
+    return options.orderDirection === 'DESC'
+      ? `ORDER BY ${orderColumn} DESC`
+      : `ORDER BY ${orderColumn} ASC`
+  }
+}

package/src/shared/fixed-clock.ts

@@ -0,0 +1,21 @@
+import type { IClock } from '@beechcms/core'
+
+const MILLISECONDS_PER_SECOND = 1000
+
+/**
+ * Test-only IClock implementation that returns a frozen timestamp on every
+ * call. Lets specs assert exact values for `createdAt`, `iat`, and
+ * day-bucket computations without resorting to vi.useFakeTimers or
+ * patching the global Date constructor.
+ */
+export class FixedClock implements IClock {
+  constructor(private readonly fixedNowMs: number) {}
+
+  now(): number {
+    return this.fixedNowMs
+  }
+
+  nowSeconds(): number {
+    return Math.floor(this.fixedNowMs / MILLISECONDS_PER_SECOND)
+  }
+}

package/src/shared/idempotency.repository.d1.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi } from 'vitest'
+import { D1IdempotencyRepository } from './idempotency.repository.d1'
+
+function makeMockDb(opts: { firstResult?: unknown } = {}) {
+  const { firstResult = null } = opts
+  const runMock = vi.fn().mockResolvedValue({ success: true })
+  const firstMock = vi.fn().mockResolvedValue(firstResult)
+  const bindMock = vi.fn(() => ({ run: runMock, first: firstMock }))
+  const prepareMock = vi.fn(() => ({ bind: bindMock }))
+  return { db: { prepare: prepareMock } as any, prepareMock, bindMock, runMock }
+}
+
+describe('D1IdempotencyRepository', () => {
+  describe('lookup', () => {
+    it('returns a mapped IdempotencyRecord when the key is found', async () => {
+      const row = {
+        idempotency_key: 'idem-1',
+        request_fingerprint: 'fp-abc',
+        response_status: 200,
+        response_body: '{"ok":true}',
+        expires_at: 9999,
+      }
+      const { db } = makeMockDb({ firstResult: row })
+      const result = await new D1IdempotencyRepository(db).lookup('idem-1')
+      expect(result).toEqual({
+        key: 'idem-1',
+        fingerprint: 'fp-abc',
+        responseStatus: 200,
+        responseBody: '{"ok":true}',
+        expiresAt: 9999,
+      })
+    })
+
+    it('returns null when the key is not found', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      expect(await new D1IdempotencyRepository(db).lookup('missing')).toBeNull()
+    })
+
+    it('queries the correct table', async () => {
+      const { db, prepareMock } = makeMockDb()
+      await new D1IdempotencyRepository(db).lookup('k')
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('public_idempotency_keys'))
+    })
+  })
+
+  describe('store', () => {
+    it('calls INSERT INTO public_idempotency_keys with upsert on conflict', async () => {
+      const { db, prepareMock } = makeMockDb()
+      await new D1IdempotencyRepository(db).store({
+        key: 'idem-1', fingerprint: 'fp', responseStatus: 201, responseBody: '{}', expiresAt: 9999,
+      })
+      const sql = prepareMock.mock.calls[0][0] as string
+      expect(sql).toContain('INSERT INTO public_idempotency_keys')
+      expect(sql).toContain('ON CONFLICT')
+    })
+
+    it('binds key, fingerprint, status, body, and expiresAt', async () => {
+      const { db, bindMock } = makeMockDb()
+      await new D1IdempotencyRepository(db).store({
+        key: 'idem-1', fingerprint: 'fp-x', responseStatus: 200, responseBody: '{"ok":1}', expiresAt: 8888,
+      })
+      const args = bindMock.mock.calls[0] as unknown[]
+      expect(args).toContain('idem-1')
+      expect(args).toContain('fp-x')
+      expect(args).toContain(200)
+      expect(args).toContain('{"ok":1}')
+      expect(args).toContain(8888)
+    })
+  })
+
+  describe('cleanup', () => {
+    it('calls DELETE with the expiration timestamp', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      await new D1IdempotencyRepository(db).cleanup(12345)
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('DELETE FROM public_idempotency_keys'))
+      expect(bindMock).toHaveBeenCalledWith(12345)
+    })
+  })
+})

package/src/shared/in-memory-activity-logger.ts

@@ -0,0 +1,15 @@
+import type { IActivityLogger, ActivityLogEntry } from '@beechcms/core'
+
+/**
+ * Test double for {@link IActivityLogger}.
+ *
+ * Captures every call into a public array so test assertions can verify
+ * audit-trail side effects without touching D1. Preserves insertion order.
+ */
+export class InMemoryActivityLogger implements IActivityLogger {
+  public readonly entries: ActivityLogEntry[] = []
+
+  log(entry: ActivityLogEntry): void {
+    this.entries.push(entry)
+  }
+}

package/src/shared/in-memory-notification-service.ts

@@ -0,0 +1,15 @@
+import type { INotificationService, CreateNotificationInput } from '@beechcms/core'
+
+/**
+ * Test double for {@link INotificationService}.
+ *
+ * Captures every call into a public array so tests can assert what would have
+ * been delivered without touching D1.
+ */
+export class InMemoryNotificationService implements INotificationService {
+  public readonly receivedNotifications: CreateNotificationInput[] = []
+
+  notify(input: CreateNotificationInput): void {
+    this.receivedNotifications.push(input)
+  }
+}