@beechcms/api 0.4.0 → 0.4.1

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

@@ -0,0 +1,312 @@
+import { describe, it, expect, vi } from 'vitest'
+import { D1ContentRepository } from './content.repository.d1'
+import { EntryNotFoundError, SlugConflictError } from '@beechcms/core'
+import type { Seed } from '@beechcms/core'
+
+const SEED = {
+  slug: 'posts',
+  displayNameAlias: 'title',
+  allowDrafts: true,
+  branches: [
+    { id: 'br_01', alias: 'title', type: 'text' },
+    { id: 'br_02', alias: 'body', type: 'text' },
+  ],
+} as unknown as Seed
+
+const NO_DRAFT_SEED = {
+  slug: 'produtos',
+  displayNameAlias: 'name',
+  allowDrafts: false,
+  branches: [{ id: 'br_01', alias: 'name', type: 'text' }],
+} as unknown as Seed
+
+function makeMockDb(opts: {
+  firstResult?: unknown
+  allResults?: unknown[]
+  runChanges?: number
+  batchResults?: unknown[]
+} = {}) {
+  const { firstResult = null, allResults = [], runChanges = 1, batchResults = [] } = opts
+  const runMock = vi.fn().mockResolvedValue({ success: true, meta: { changes: runChanges } })
+  const firstMock = vi.fn().mockResolvedValue(firstResult)
+  const allMock = vi.fn().mockResolvedValue({ results: allResults })
+  const bindMock = vi.fn(() => ({ run: runMock, first: firstMock, all: allMock }))
+  const stmt = { bind: bindMock, run: runMock, first: firstMock, all: allMock }
+  const prepareMock = vi.fn(() => stmt)
+  const batchMock = vi.fn().mockResolvedValue(batchResults)
+  return { db: { prepare: prepareMock, batch: batchMock } as any, prepareMock, bindMock, runMock, firstMock, allMock, batchMock }
+}
+
+// ─── findMany ─────────────────────────────────────────────────────────────────
+
+describe('D1ContentRepository', () => {
+  describe('findMany', () => {
+    it('returns mapped items and total from batch results', async () => {
+      const row = { id: 'e1', slug: 'post-1', status: 'published', title: 'Hello', body: null, created_at: 1000, updated_at: 1000 }
+      const { db } = makeMockDb({
+        batchResults: [
+          { results: [row] },
+          { results: [{ total: 1 }] },
+        ],
+      })
+      const result = await new D1ContentRepository(db).findMany(SEED, { pagination: { limit: 10, offset: 0 } })
+      expect(result.items).toHaveLength(1)
+      expect(result.items[0].id).toBe('e1')
+      expect(result.total).toBe(1)
+    })
+
+    it('returns empty items and zero total when table is empty', async () => {
+      const { db } = makeMockDb({
+        batchResults: [{ results: [] }, { results: [{ total: 0 }] }],
+      })
+      const result = await new D1ContentRepository(db).findMany(SEED, {})
+      expect(result.items).toHaveLength(0)
+      expect(result.total).toBe(0)
+    })
+
+    it('wraps D1 errors in RepositoryError', async () => {
+      const { db } = makeMockDb()
+      db.batch = vi.fn().mockRejectedValue(new Error('D1 error'))
+      await expect(new D1ContentRepository(db).findMany(SEED, {})).rejects.toThrow('findMany')
+    })
+  })
+
+  // ─── findById ───────────────────────────────────────────────────────────────
+
+  describe('findById', () => {
+    it('returns the entry when found', async () => {
+      const row = { id: 'e1', slug: 'p', status: 'draft', title: 'T', body: null, created_at: 0, updated_at: 0 }
+      const { db } = makeMockDb({ firstResult: row })
+      const result = await new D1ContentRepository(db).findById(SEED, 'e1')
+      expect(result.id).toBe('e1')
+      expect(result.title).toBe('T')
+    })
+
+    it('throws EntryNotFoundError when the row does not exist', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      await expect(new D1ContentRepository(db).findById(SEED, 'missing')).rejects.toBeInstanceOf(EntryNotFoundError)
+    })
+
+    it('queries the correct content table', async () => {
+      const { db, prepareMock } = makeMockDb({ firstResult: { id: 'e1', slug: null, status: 'draft', title: null, body: null } })
+      await new D1ContentRepository(db).findById(SEED, 'e1')
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('content_posts'))
+    })
+  })
+
+  // ─── findBySlug ─────────────────────────────────────────────────────────────
+
+  describe('findBySlug', () => {
+    it('returns the entry when the slug is found', async () => {
+      const row = { id: 'e1', slug: 'my-post', status: 'published', title: 'T', body: null }
+      const { db } = makeMockDb({ firstResult: row })
+      const result = await new D1ContentRepository(db).findBySlug(SEED, 'my-post')
+      expect(result.slug).toBe('my-post')
+    })
+
+    it('throws EntryNotFoundError when slug does not exist', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      await expect(new D1ContentRepository(db).findBySlug(SEED, 'ghost')).rejects.toBeInstanceOf(EntryNotFoundError)
+    })
+  })
+
+  // ─── getFacets ───────────────────────────────────────────────────────────────
+
+  describe('getFacets', () => {
+    it('returns status counts mapped from status GROUP BY results', async () => {
+      const { db, allMock } = makeMockDb()
+      allMock.mockResolvedValueOnce({ results: [{ status: 'published', count: 3 }, { status: 'draft', count: 1 }] })
+      const result = await new D1ContentRepository(db).getFacets(SEED)
+      expect(result.statuses).toEqual({ published: 3, draft: 1 })
+    })
+
+    it('returns empty tagsByColumn when seed has no tag branches', async () => {
+      const { db, allMock } = makeMockDb()
+      allMock.mockResolvedValueOnce({ results: [] })
+      const result = await new D1ContentRepository(db).getFacets(SEED)
+      expect(result.tagsByColumn).toEqual({})
+    })
+  })
+
+  // ─── existsSlug ─────────────────────────────────────────────────────────────
+
+  describe('existsSlug', () => {
+    it('returns true when the slug row is found', async () => {
+      const { db } = makeMockDb({ firstResult: { 1: 1 } })
+      expect(await new D1ContentRepository(db).existsSlug(SEED, 'existing-slug')).toBe(true)
+    })
+
+    it('returns false when the slug row is not found', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      expect(await new D1ContentRepository(db).existsSlug(SEED, 'new-slug')).toBe(false)
+    })
+
+    it('appends AND id != ? clause when excludeId is provided', async () => {
+      const { db, bindMock } = makeMockDb({ firstResult: null })
+      await new D1ContentRepository(db).existsSlug(SEED, 'slug', 'exclude-me')
+      expect(bindMock).toHaveBeenCalledWith('slug', 'exclude-me')
+    })
+  })
+
+  // ─── create ─────────────────────────────────────────────────────────────────
+
+  describe('create', () => {
+    it('calls INSERT INTO the content table', async () => {
+      const { db, prepareMock } = makeMockDb({ firstResult: null }) // existsSlug → null
+      await new D1ContentRepository(db).create(SEED, 'new-id', 'my-slug', 'draft', { title: 'Hello' })
+      const calls = prepareMock.mock.calls.map(c => c[0] as string)
+      expect(calls.some(sql => sql.includes('INSERT INTO content_posts'))).toBe(true)
+    })
+
+    it('throws SlugConflictError when the slug already exists', async () => {
+      const { db } = makeMockDb({ firstResult: { 1: 1 } }) // existsSlug → found
+      await expect(
+        new D1ContentRepository(db).create(SEED, 'id', 'taken-slug', 'draft', {}),
+      ).rejects.toBeInstanceOf(SlugConflictError)
+    })
+  })
+
+  // ─── update ─────────────────────────────────────────────────────────────────
+
+  describe('update', () => {
+    it('calls UPDATE with provided status and branch data', async () => {
+      const { db, prepareMock, runMock } = makeMockDb({ runChanges: 1 })
+      runMock.mockResolvedValue({ success: true, meta: { changes: 1 } })
+      await new D1ContentRepository(db).update(SEED, 'e1', { title: 'New' }, 'published')
+      const calls = prepareMock.mock.calls.map(c => c[0] as string)
+      expect(calls.some(sql => sql.includes('UPDATE content_posts'))).toBe(true)
+    })
+
+    it('throws EntryNotFoundError when no rows are updated', async () => {
+      const { db } = makeMockDb({ runChanges: 0 })
+      await expect(new D1ContentRepository(db).update(SEED, 'ghost', { title: 'X' })).rejects.toBeInstanceOf(EntryNotFoundError)
+    })
+
+    it('returns early without a DB call when there is nothing to update', async () => {
+      const { db, prepareMock } = makeMockDb()
+      await new D1ContentRepository(db).update(SEED, 'e1', {}) // no data, no status
+      // existsSlug is not called; only prepare calls would be for UPDATE which shouldn't happen
+      const updateCalls = prepareMock.mock.calls.filter(c => (c[0] as string).includes('UPDATE content_posts'))
+      expect(updateCalls).toHaveLength(0)
+    })
+  })
+
+  // ─── delete ─────────────────────────────────────────────────────────────────
+
+  describe('delete', () => {
+    it('returns the row data and calls DELETE', async () => {
+      const row = { id: 'e1', slug: 'p', status: 'published', title: 'T', body: null }
+      const { db, prepareMock } = makeMockDb({ firstResult: row })
+      const result = await new D1ContentRepository(db).delete(SEED, 'e1')
+      expect(result.row.id).toBe('e1')
+      const sqls = prepareMock.mock.calls.map(c => c[0] as string)
+      expect(sqls.some(s => s.includes('DELETE FROM content_posts'))).toBe(true)
+    })
+
+    it('throws EntryNotFoundError when the entry does not exist', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      await expect(new D1ContentRepository(db).delete(SEED, 'missing')).rejects.toBeInstanceOf(EntryNotFoundError)
+    })
+  })
+
+  // ─── saveDraft ───────────────────────────────────────────────────────────────
+
+  describe('saveDraft', () => {
+    it('calls INSERT OR REPLACE into the draft table', async () => {
+      const { db, prepareMock } = makeMockDb()
+      await new D1ContentRepository(db).saveDraft(SEED, 'e1', { title: 'Draft title' })
+      const sqls = prepareMock.mock.calls.map(c => c[0] as string)
+      expect(sqls.some(s => s.includes('content_posts_drafts'))).toBe(true)
+    })
+
+    it('throws RepositoryError when seed does not allow drafts', async () => {
+      const { db } = makeMockDb()
+      await expect(new D1ContentRepository(db).saveDraft(NO_DRAFT_SEED, 'e1', {})).rejects.toThrow('Drafts not allowed')
+    })
+  })
+
+  // ─── getDraft ────────────────────────────────────────────────────────────────
+
+  describe('getDraft', () => {
+    it('returns null when seed does not allow drafts', async () => {
+      const { db } = makeMockDb()
+      expect(await new D1ContentRepository(db).getDraft(NO_DRAFT_SEED, 'e1')).toBeNull()
+    })
+
+    it('returns null when no draft row exists', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      expect(await new D1ContentRepository(db).getDraft(SEED, 'e1')).toBeNull()
+    })
+
+    it('returns deserialized draft data for non-null branch values', async () => {
+      const draftRow = { entry_id: 'e1', title: 'Draft T', body: null }
+      const { db } = makeMockDb({ firstResult: draftRow })
+      const result = await new D1ContentRepository(db).getDraft(SEED, 'e1')
+      expect(result).not.toBeNull()
+      expect(result!.title).toBe('Draft T')
+      expect(result).not.toHaveProperty('body') // null branch values are omitted
+    })
+  })
+
+  // ─── hasDraft ─────────────────────────────────────────────────────────────────
+
+  describe('hasDraft', () => {
+    it('returns false immediately when seed does not allow drafts', async () => {
+      const { db, prepareMock } = makeMockDb()
+      expect(await new D1ContentRepository(db).hasDraft(NO_DRAFT_SEED, 'e1')).toBe(false)
+      expect(prepareMock).not.toHaveBeenCalled()
+    })
+
+    it('returns true when a draft exists', async () => {
+      const { db } = makeMockDb({ firstResult: { 1: 1 } })
+      expect(await new D1ContentRepository(db).hasDraft(SEED, 'e1')).toBe(true)
+    })
+
+    it('returns false when no draft exists', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      expect(await new D1ContentRepository(db).hasDraft(SEED, 'e1')).toBe(false)
+    })
+  })
+
+  // ─── publishDraft ─────────────────────────────────────────────────────────────
+
+  describe('publishDraft', () => {
+    it('returns early when seed does not allow drafts', async () => {
+      const { db, batchMock } = makeMockDb()
+      await new D1ContentRepository(db).publishDraft(NO_DRAFT_SEED, 'e1')
+      expect(batchMock).not.toHaveBeenCalled()
+    })
+
+    it('throws EntryNotFoundError when no draft exists', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      await expect(new D1ContentRepository(db).publishDraft(SEED, 'e1')).rejects.toBeInstanceOf(EntryNotFoundError)
+    })
+
+    it('calls batch with UPDATE and DELETE statements when draft exists', async () => {
+      const draftRow = { entry_id: 'e1', title: 'Draft', body: null }
+      const { db, batchMock, firstMock } = makeMockDb()
+      firstMock.mockResolvedValueOnce(draftRow)
+      batchMock.mockResolvedValueOnce([{}, {}])
+      await new D1ContentRepository(db).publishDraft(SEED, 'e1')
+      expect(batchMock).toHaveBeenCalledTimes(1)
+      const batchArgs: any[] = batchMock.mock.calls[0][0]
+      expect(batchArgs).toHaveLength(2)
+    })
+  })
+
+  // ─── deleteDraft ─────────────────────────────────────────────────────────────
+
+  describe('deleteDraft', () => {
+    it('returns early when seed does not allow drafts', async () => {
+      const { db, prepareMock } = makeMockDb()
+      await new D1ContentRepository(db).deleteDraft(NO_DRAFT_SEED, 'e1')
+      expect(prepareMock).not.toHaveBeenCalled()
+    })
+
+    it('calls DELETE on the draft table when drafts are allowed', async () => {
+      const { db, prepareMock } = makeMockDb()
+      await new D1ContentRepository(db).deleteDraft(SEED, 'e1')
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('content_posts_drafts'))
+    })
+  })
+})

package/src/shared/d1-activity-log.repository.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, vi } from 'vitest'
+import { D1ActivityLogRepository } from './d1-activity-log.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(() => ({ bind: bindMock }))
+  return { db: { prepare: prepareMock } as any, prepareMock, bindMock, allMock, firstMock }
+}
+
+describe('D1ActivityLogRepository', () => {
+  it('maps snake_case rows to camelCase records and parses the details JSON', async () => {
+    const row = {
+      id: 'log-1',
+      user_id: 'u1',
+      user_email: 'a@b.com',
+      user_name: 'Admin',
+      action: 'create',
+      entity_type: 'content',
+      entity_id: 'e1',
+      entity_slug: 'posts',
+      details: '{"title":"Hello"}',
+      created_at: 1234,
+    }
+    const { db } = makeMockDb([row])
+    const result = await new D1ActivityLogRepository(db).list({ limit: 10 })
+    expect(result).toEqual([
+      {
+        id: 'log-1',
+        userId: 'u1',
+        userEmail: 'a@b.com',
+        userName: 'Admin',
+        action: 'create',
+        entityType: 'content',
+        entityId: 'e1',
+        entitySlug: 'posts',
+        details: { title: 'Hello' },
+        createdAt: 1234,
+      },
+    ])
+  })
+
+  it('returns null details when the column is null', async () => {
+    const { db } = makeMockDb([
+      {
+        id: 'l',
+        user_id: 'u',
+        user_email: 'a',
+        user_name: null,
+        action: 'delete',
+        entity_type: 'content',
+        entity_id: 'e',
+        entity_slug: null,
+        details: null,
+        created_at: 1,
+      },
+    ])
+    const [record] = await new D1ActivityLogRepository(db).list({ limit: 1 })
+    expect(record.details).toBeNull()
+    expect(record.userName).toBeNull()
+    expect(record.entitySlug).toBeNull()
+  })
+
+  it('omits the WHERE clause when no filters are provided', async () => {
+    const { db, prepareMock, bindMock } = makeMockDb([])
+    await new D1ActivityLogRepository(db).list({ limit: 5 })
+    expect(prepareMock.mock.calls[0][0]).not.toMatch(/WHERE/)
+    expect(bindMock).toHaveBeenCalledWith(5)
+  })
+
+  it('builds a userId WHERE clause when the option is set', async () => {
+    const { db, prepareMock, bindMock } = makeMockDb([])
+    await new D1ActivityLogRepository(db).list({ userId: 'u-9', limit: 3 })
+    expect(prepareMock.mock.calls[0][0]).toMatch(/WHERE user_id = \?/)
+    expect(bindMock).toHaveBeenCalledWith('u-9', 3)
+  })
+
+  it('builds a combined userId + entitySlug WHERE clause with AND', async () => {
+    const { db, prepareMock, bindMock } = makeMockDb([])
+    await new D1ActivityLogRepository(db).list({ userId: 'u', entitySlug: 'posts', limit: 7 })
+    expect(prepareMock.mock.calls[0][0]).toMatch(/WHERE user_id = \? AND entity_slug = \?/)
+    expect(bindMock).toHaveBeenCalledWith('u', 'posts', 7)
+  })
+
+  it('always orders by created_at DESC and applies LIMIT', async () => {
+    const { db, prepareMock } = makeMockDb([])
+    await new D1ActivityLogRepository(db).list({ limit: 1 })
+    expect(prepareMock.mock.calls[0][0]).toMatch(/ORDER BY created_at DESC/)
+    expect(prepareMock.mock.calls[0][0]).toMatch(/LIMIT \?/)
+  })
+
+  describe('countSince', () => {
+    it('binds action, entityType and sinceTimestamp and returns the count', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb([], { count: 42 })
+      const result = await new D1ActivityLogRepository(db).countSince({
+        action: 'create',
+        entityType: 'content',
+        sinceTimestamp: 1000,
+      })
+      expect(result).toBe(42)
+      expect(prepareMock.mock.calls[0][0]).toMatch(/COUNT\(\*\)/)
+      expect(prepareMock.mock.calls[0][0]).toMatch(/WHERE action = \?\s+AND entity_type = \?\s+AND created_at >= \?/)
+      expect(bindMock).toHaveBeenCalledWith('create', 'content', 1000)
+    })
+
+    it('returns 0 when no rows match', async () => {
+      const { db } = makeMockDb([], null)
+      const result = await new D1ActivityLogRepository(db).countSince({
+        action: 'delete',
+        entityType: 'media',
+        sinceTimestamp: 0,
+      })
+      expect(result).toBe(0)
+    })
+  })
+
+  it('returns null details when the JSON payload cannot be parsed', async () => {
+    const { db } = makeMockDb([
+      {
+        id: 'l',
+        user_id: 'u',
+        user_email: 'a',
+        user_name: null,
+        action: 'create',
+        entity_type: 'content',
+        entity_id: 'e',
+        entity_slug: null,
+        details: 'not-json',
+        created_at: 1,
+      },
+    ])
+    const [record] = await new D1ActivityLogRepository(db).list({ limit: 1 })
+    expect(record.details).toBeNull()
+  })
+})

package/src/shared/d1-activity-log.repository.ts

@@ -0,0 +1,101 @@
+/// <reference types="@cloudflare/workers-types" />
+import type {
+  IActivityLogRepository,
+  ActivityLogRecord,
+  ActivityLogListOptions,
+  ActivityAction,
+  EntityType,
+  CountSinceOptions,
+} from '@beechcms/core'
+
+interface ActivityLogRow {
+  id: string
+  user_id: string
+  user_email: string
+  user_name: string | null
+  action: string
+  entity_type: string
+  entity_id: string
+  entity_slug: string | null
+  details: string | null
+  created_at: number
+}
+
+/**
+ * D1-backed implementation of {@link IActivityLogRepository}.
+ *
+ * Builds parameterised queries with optional WHERE clauses without nesting
+ * conditionals — guard clauses keep the body flat and the SQL deterministic.
+ */
+export class D1ActivityLogRepository implements IActivityLogRepository {
+  constructor(private readonly database: D1Database) {}
+
+  async list(options: ActivityLogListOptions): Promise<ActivityLogRecord[]> {
+    const whereClauses: string[] = []
+    const bindings: unknown[] = []
+
+    if (options.userId) {
+      whereClauses.push('user_id = ?')
+      bindings.push(options.userId)
+    }
+
+    if (options.entitySlug) {
+      whereClauses.push('entity_slug = ?')
+      bindings.push(options.entitySlug)
+    }
+
+    const whereSql = whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : ''
+
+    const sql =
+      `SELECT id, user_id, user_email, user_name, action, entity_type,
+              entity_id, entity_slug, details, created_at
+         FROM activity_logs
+         ${whereSql}
+         ORDER BY created_at DESC
+         LIMIT ?`
+
+    bindings.push(options.limit)
+
+    const queryResult = await this.database.prepare(sql).bind(...bindings).all<ActivityLogRow>()
+    return (queryResult.results ?? []).map(mapRowToRecord)
+  }
+
+  async countSince(options: CountSinceOptions): Promise<number> {
+    const row = await this.database
+      .prepare(
+        `SELECT COUNT(*) as count
+           FROM activity_logs
+          WHERE action = ?
+            AND entity_type = ?
+            AND created_at >= ?`
+      )
+      .bind(options.action, options.entityType, options.sinceTimestamp)
+      .first<{ count: number }>()
+    return row?.count ?? 0
+  }
+}
+
+function mapRowToRecord(row: ActivityLogRow): ActivityLogRecord {
+  return {
+    id: row.id,
+    userId: row.user_id,
+    userEmail: row.user_email,
+    userName: row.user_name,
+    action: row.action as ActivityAction,
+    entityType: row.entity_type as EntityType,
+    entityId: row.entity_id,
+    entitySlug: row.entity_slug,
+    details: parseDetails(row.details),
+    createdAt: row.created_at,
+  }
+}
+
+function parseDetails(raw: string | null): Record<string, unknown> | null {
+  if (raw === null) return null
+  try {
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : null
+  } catch {
+    return null
+  }
+}

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

@@ -0,0 +1,82 @@
+import { describe, it, expect, vi } from 'vitest'
+import { D1ActivityLogger } from './d1-activity-logger'
+import type { ActivityLogEntry } from '@beechcms/core'
+import { FixedClock } from './fixed-clock'
+import { SequentialIdGenerator } from './sequential-id-generator'
+
+const clock = new FixedClock(1700000000_000)
+const makeIdGen = () => new SequentialIdGenerator()
+
+function makeMockDb(opts: { runShouldThrow?: boolean } = {}) {
+  const runMock = opts.runShouldThrow
+    ? vi.fn().mockRejectedValue(new Error('db down'))
+    : vi.fn().mockResolvedValue({ success: true })
+  const bindMock = vi.fn(() => ({ run: runMock }))
+  const prepareMock = vi.fn(() => ({ bind: bindMock }))
+  return { db: { prepare: prepareMock } as any, prepareMock, bindMock, runMock }
+}
+
+const SAMPLE_ENTRY: ActivityLogEntry = {
+  action: 'create',
+  entityType: 'content',
+  entityId: 'entry-1',
+  entitySlug: 'posts',
+  details: { title: 'Hello' },
+  actor: { id: 'user-1', email: 'admin@example.com', name: 'Admin' },
+}
+
+describe('D1ActivityLogger', () => {
+  it('inserts into activity_logs with the actor and entry payload bound in order', async () => {
+    const { db, prepareMock, bindMock } = makeMockDb()
+    const logger = new D1ActivityLogger(db, clock, makeIdGen())
+
+    await logger.log(SAMPLE_ENTRY)
+
+    expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('INSERT INTO activity_logs'))
+    const boundArguments = bindMock.mock.calls[0]
+    expect(boundArguments[1]).toBe('user-1')
+    expect(boundArguments[2]).toBe('admin@example.com')
+    expect(boundArguments[3]).toBe('Admin')
+    expect(boundArguments[4]).toBe('create')
+    expect(boundArguments[5]).toBe('content')
+    expect(boundArguments[6]).toBe('entry-1')
+    expect(boundArguments[7]).toBe('posts')
+    expect(boundArguments[8]).toBe('{"title":"Hello"}')
+  })
+
+  it('serialises details as null when absent', async () => {
+    const { db, bindMock } = makeMockDb()
+    await new D1ActivityLogger(db, clock, makeIdGen()).log({ ...SAMPLE_ENTRY, details: undefined })
+    expect(bindMock.mock.calls[0][8]).toBeNull()
+  })
+
+  it('falls back to "unknown" when actor email is empty', async () => {
+    const { db, bindMock } = makeMockDb()
+    await new D1ActivityLogger(db, clock, makeIdGen()).log({
+      ...SAMPLE_ENTRY,
+      actor: { id: 'u', email: '', name: null },
+    })
+    expect(bindMock.mock.calls[0][2]).toBe('unknown')
+  })
+
+  it('schedules the insert via the background hook when provided', async () => {
+    const { db } = makeMockDb()
+    const scheduleBackgroundTask = vi.fn()
+    const logger = new D1ActivityLogger(db, clock, makeIdGen(), scheduleBackgroundTask)
+
+    logger.log(SAMPLE_ENTRY)
+
+    expect(scheduleBackgroundTask).toHaveBeenCalledTimes(1)
+    expect(scheduleBackgroundTask.mock.calls[0][0]).toBeInstanceOf(Promise)
+  })
+
+  it('never throws to the caller when the underlying INSERT fails', async () => {
+    const { db } = makeMockDb({ runShouldThrow: true })
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const logger = new D1ActivityLogger(db, clock, makeIdGen())
+
+    await expect(logger.log(SAMPLE_ENTRY)).resolves.toBeUndefined()
+    expect(consoleSpy).toHaveBeenCalled()
+    consoleSpy.mockRestore()
+  })
+})