@beechcms/api 0.4.0-preview.9 → 0.4.1

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()
+  })
+})

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
+  }
+}