@beechcms/api 0.4.0 → 0.4.2

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/execution-context-scheduler.ts

@@ -0,0 +1,9 @@
+import type { IScheduler } from '@beechcms/core'
+
+export class ExecutionContextScheduler implements IScheduler {
+  constructor(private readonly ctx: ExecutionContext) {}
+
+  waitUntil(promise: Promise<unknown>): void {
+    this.ctx.waitUntil(promise)
+  }
+}

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

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

@@ -0,0 +1,103 @@
+import { describe, it, expect, vi } from 'vitest'
+import { D1MediaRepository } from './media.repository.d1'
+
+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 })
+  // bind() returns the same interface so chains like prepare().bind().all() work.
+  // The statement also exposes first/all/run directly for queries that skip bind().
+  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)
+  return { db: { prepare: prepareMock } as any, prepareMock, bindMock, runMock, firstMock, allMock }
+}
+
+describe('D1MediaRepository', () => {
+  describe('trackUpload', () => {
+    it('calls INSERT INTO media_objects with correct bound values', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      const obj = { key: 'k1', filename: 'img.png', mime_type: 'image/png', size_bytes: 1024, uploaded_by: 'user-1' }
+      await new D1MediaRepository(db).trackUpload(obj)
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('INSERT INTO media_objects'))
+      expect(bindMock).toHaveBeenCalledWith('k1', 'img.png', 'image/png', 1024, 'user-1')
+    })
+  })
+
+  describe('getByKey', () => {
+    it('returns the media object when found', async () => {
+      const row = { key: 'k1', filename: 'img.png', mime_type: 'image/png', size_bytes: 512, uploaded_by: 'u1', created_at: 1000 }
+      const { db } = makeMockDb({ firstResult: row })
+      const result = await new D1MediaRepository(db).getByKey('k1')
+      expect(result).toEqual(row)
+    })
+
+    it('returns null when the key is not found', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      expect(await new D1MediaRepository(db).getByKey('ghost')).toBeNull()
+    })
+
+    it('passes the key as bound value', async () => {
+      const { db, bindMock } = makeMockDb()
+      await new D1MediaRepository(db).getByKey('my-key')
+      expect(bindMock).toHaveBeenCalledWith('my-key')
+    })
+  })
+
+  describe('untrack', () => {
+    it('calls DELETE FROM media_objects with the key', async () => {
+      const { db, prepareMock, bindMock } = makeMockDb()
+      await new D1MediaRepository(db).untrack('k1')
+      expect(prepareMock).toHaveBeenCalledWith(expect.stringContaining('DELETE FROM media_objects'))
+      expect(bindMock).toHaveBeenCalledWith('k1')
+    })
+  })
+
+  describe('list', () => {
+    it('returns items and total from D1', async () => {
+      const rows = [
+        { key: 'k1', filename: 'a.png', mime_type: 'image/png', size_bytes: 100, uploaded_by: 'u1', created_at: 1000 },
+      ]
+      const { db, allMock, firstMock } = makeMockDb()
+      // list() calls all() for items then first() for count (without bind)
+      allMock.mockResolvedValueOnce({ results: rows })
+      firstMock.mockResolvedValueOnce({ total: 1 })
+
+      const result = await new D1MediaRepository(db).list({ limit: 10, offset: 0 })
+      expect(result.items).toHaveLength(1)
+      expect(result.total).toBe(1)
+    })
+
+    it('returns empty items and 0 total when D1 returns nothing', async () => {
+      const { db, allMock, firstMock } = makeMockDb()
+      allMock.mockResolvedValueOnce({ results: [] })
+      firstMock.mockResolvedValueOnce(null) // count row is null → 0
+
+      const result = await new D1MediaRepository(db).list({ limit: 10, offset: 0 })
+      expect(result.items).toEqual([])
+      expect(result.total).toBe(0)
+    })
+
+    it('passes limit and offset as bound values for the list query', async () => {
+      const { db, bindMock, allMock, firstMock } = makeMockDb()
+      allMock.mockResolvedValueOnce({ results: [] })
+      firstMock.mockResolvedValueOnce({ total: 0 })
+
+      await new D1MediaRepository(db).list({ limit: 5, offset: 10 })
+      expect(bindMock).toHaveBeenCalledWith(5, 10)
+    })
+  })
+
+  describe('count', () => {
+    it('returns the count from D1', async () => {
+      const { db } = makeMockDb({ firstResult: { total: 42 } })
+      expect(await new D1MediaRepository(db).count()).toBe(42)
+    })
+
+    it('returns 0 when D1 returns null', async () => {
+      const { db } = makeMockDb({ firstResult: null })
+      expect(await new D1MediaRepository(db).count()).toBe(0)
+    })
+  })
+})

package/src/shared/media.repository.d1.ts

@@ -10,7 +10,7 @@ export class D1MediaRepository implements MediaRepository {
   /**
    * Registers a new media upload in the database.
    */
-  async trackUpload(mediaObject: MediaObject): Promise<void> {
+  async trackUpload(mediaObject: Omit<MediaObject, 'created_at'>): Promise<void> {
     await this.database.prepare(
       'INSERT INTO media_objects (key, filename, mime_type, size_bytes, uploaded_by) VALUES (?, ?, ?, ?, ?)'
     ).bind(

package/src/shared/request-utils.ts

@@ -0,0 +1,22 @@
+import type { HonoRequest } from "hono"
+
+/** The header Cloudflare sets on every incoming request to the Worker. */
+const CLOUDFLARE_CLIENT_IP_HEADER = "cf-connecting-ip"
+
+/** The fallback value used when the IP header is absent (local dev, unit tests). */
+const UNKNOWN_IP = "unknown"
+
+/**
+ * Extracts the real client IP address from a Cloudflare Worker request.
+ *
+ * Cloudflare injects the cf-connecting-ip header on every request that
+ * passes through the edge. In local development (wrangler dev) or in
+ * unit tests the header may be absent, in which case the string "unknown"
+ * is returned so that rate-limiter keys remain non-empty and safe to use.
+ *
+ * Never derive security decisions from this value alone; treat it as a
+ * best-effort hint for rate-limiting and logging purposes only.
+ */
+export function getClientIp(request: HonoRequest): string {
+  return request.raw.headers.get(CLOUDFLARE_CLIENT_IP_HEADER) ?? UNKNOWN_IP
+}

package/src/shared/sequential-id-generator.ts

@@ -0,0 +1,22 @@
+import type { IIdGenerator } from '@beechcms/core'
+
+const ID_PADDING_WIDTH = 4
+
+/**
+ * Test-only IIdGenerator implementation. Each call returns a stable,
+ * monotonically increasing identifier (`test-id-0001`, `test-id-0002`, …)
+ * so snapshot assertions and insert-order checks remain deterministic
+ * across runs.
+ */
+export class SequentialIdGenerator implements IIdGenerator {
+  private counter = 0
+
+  uuid(): string {
+    this.counter += 1
+    return `test-id-${String(this.counter).padStart(ID_PADDING_WIDTH, '0')}`
+  }
+
+  reset(): void {
+    this.counter = 0
+  }
+}

package/src/shared/storage-utils.ts

@@ -12,13 +12,13 @@ export async function getBucketSize(client: S3Client, bucketName: string): Promi
 
   try {
     while (isTruncatedFlag) {
-      const command = new ListObjectsV2Command({
+      const command: ListObjectsV2Command = new ListObjectsV2Command({
         Bucket: bucketName,
         ContinuationToken: continuationToken,
       })
 
-      const response = (await client.send(command)) as ListObjectsV2CommandOutput
-      
+      const response: ListObjectsV2CommandOutput = await client.send(command)
+
       if (response.Contents) {
         for (const obj of response.Contents) {
           totalSize += obj.Size ?? 0