@beechcms/api 0.6.0-preview.1 → 0.6.0-preview.3

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

@@ -1,19 +0,0 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-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/in-memory-seed.repository.ts

@@ -1,51 +0,0 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-import type { ISeedRepository, Seed, SeedRecord } from '@beechcms/core'
-
-/**
- * In-memory ISeedRepository for testing and for the config.seeds back-compat shim.
- * Returns a fixed seed list with a static version token.
- */
-export class InMemorySeedRepository implements ISeedRepository {
-  private readonly seeds: Seed[]
-  private version = 1
-
-  constructor(seeds: Seed[]) {
-    this.seeds = seeds.filter(s => s && typeof s === 'object' && 'slug' in s)
-  }
-
-  async listActive(): Promise<Seed[]> {
-    return this.seeds
-  }
-
-  async listAll(): Promise<SeedRecord[]> {
-    return this.seeds.map(s => ({
-      slug: s.slug,
-      definition: s,
-      status: 'active' as const,
-      source: 'code' as const,
-      createdAt: 0,
-      updatedAt: 0,
-    }))
-  }
-
-  async get(slug: string): Promise<SeedRecord | null> {
-    const s = this.seeds.find(s => s.slug === slug)
-    if (!s) return null
-    return { slug: s.slug, definition: s, status: 'active', source: 'code', createdAt: 0, updatedAt: 0 }
-  }
-
-  async upsert(): Promise<void> {}
-  async softDelete(): Promise<void> {}
-  async hardDelete(): Promise<void> {}
-
-  async getRegistryVersion(): Promise<number> {
-    return this.version
-  }
-
-  async bumpRegistryVersion(): Promise<number> {
-    return ++this.version
-  }
-}

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

@@ -1,107 +0,0 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-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

@@ -1,68 +0,0 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-import { MediaRepository, MediaObject } from '@beechcms/core'
-
-/**
- * Implementation of MediaRepository using Cloudflare D1.
- * Provides methods to track media uploads, retrieve media metadata, and manage the media library state in the database.
- */
-export class D1MediaRepository implements MediaRepository {
-  constructor(private database: D1Database) {}
-
-  /**
-   * Registers a new media upload in the database.
-   */
-  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(
-      mediaObject.key, 
-      mediaObject.filename, 
-      mediaObject.mime_type, 
-      mediaObject.size_bytes, 
-      mediaObject.uploaded_by
-    ).run()
-  }
-
-  /**
-   * Retrieves a media object's metadata by its unique key.
-   */
-  async getByKey(mediaKey: string): Promise<MediaObject | null> {
-    return await this.database.prepare(
-      'SELECT key, filename, mime_type, size_bytes, uploaded_by, created_at FROM media_objects WHERE key = ?'
-    ).bind(mediaKey).first<MediaObject>()
-  }
-
-  /**
-   * Removes the metadata tracking for a specific media key.
-   */
-  async untrack(mediaKey: string): Promise<void> {
-    await this.database.prepare('DELETE FROM media_objects WHERE key = ?').bind(mediaKey).run()
-  }
-
-  /**
-   * Lists media objects with pagination support.
-   */
-  async list(paginationOptions: { limit: number; offset: number }): Promise<{ items: MediaObject[]; total: number }> {
-    const { results: mediaItems } = await this.database.prepare(
-      'SELECT key, filename, mime_type, size_bytes, uploaded_by, created_at FROM media_objects ORDER BY created_at DESC LIMIT ? OFFSET ?'
-    ).bind(paginationOptions.limit, paginationOptions.offset).all<MediaObject>()
-
-    const totalCountRecord = await this.database.prepare('SELECT COUNT(*) as total FROM media_objects').first<{ total: number }>()
-
-    return {
-      items: mediaItems ?? [],
-      total: totalCountRecord?.total ?? 0
-    }
-  }
-
-  /**
-   * Returns the total number of media objects in the database.
-   */
-  async count(): Promise<number> {
-    const totalCountRecord = await this.database.prepare('SELECT COUNT(*) as total FROM media_objects').first<{ total: number }>()
-    return totalCountRecord?.total ?? 0
-  }
-}

package/src/shared/qstash-notification-service.test.ts

@@ -1,67 +0,0 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-import { describe, it, expect, vi, beforeEach } from 'vitest'
-import { QStashNotificationService } from './qstash-notification-service'
-import { Client } from '@upstash/qstash'
-
-// Mock the @upstash/qstash Client
-vi.mock('@upstash/qstash', () => {
-  const publishJSON = vi.fn().mockResolvedValue({ messageId: 'msg_123' })
-  return {
-    Client: vi.fn().mockImplementation(function () {
-      return { publishJSON }
-    }),
-  }
-})
-
-describe('QStashNotificationService', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  it('delegates publishing to the QStash client with correct URL', async () => {
-    const service = new QStashNotificationService('fake_token', 'https://beechcms.test/')
-    await service.notify({
-      title: 'Hello',
-      message: 'World',
-      type: 'success',
-    })
-
-    const clientInstance = vi.mocked(Client).mock.results[0].value
-    expect(clientInstance.publishJSON).toHaveBeenCalledWith({
-      url: 'https://beechcms.test/api/webhooks/qstash',
-      body: {
-        title: 'Hello',
-        message: 'World',
-        type: 'success',
-      },
-    })
-  })
-
-  it('delegates to the background scheduler when provided', () => {
-    const schedule = vi.fn()
-    const service = new QStashNotificationService('fake_token', 'https://beechcms.test', schedule)
-    
-    service.notify({ title: 'T', message: 'M' })
-    
-    expect(schedule).toHaveBeenCalledTimes(1)
-    expect(schedule.mock.calls[0][0]).toBeInstanceOf(Promise)
-  })
-
-  it('never throws to the caller when the publish write fails', async () => {
-    // Override the mock for this specific test
-    const mockPublish = vi.fn().mockRejectedValue(new Error('network error'))
-    vi.mocked(Client).mockImplementationOnce(function () {
-      return { publishJSON: mockPublish }
-    } as any)
-
-    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
-    const service = new QStashNotificationService('fake_token', 'https://beechcms.test')
-    
-    await expect(service.notify({ title: 'T', message: 'M' })).resolves.toBeUndefined()
-    expect(consoleSpy).toHaveBeenCalled()
-    consoleSpy.mockRestore()
-  })
-})

package/src/shared/qstash-notification-service.ts

@@ -1,55 +0,0 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-import type { INotificationService, CreateNotificationInput } from '@beechcms/core'
-import { Client } from '@upstash/qstash'
-
-type ScheduleBackgroundTask = (task: Promise<unknown>) => void
-
-/**
- * QStash implementation of {@link INotificationService}.
- *
- * This service acts as a publisher, sending the notification payload to Upstash QStash,
- * which guarantees delivery and retries. QStash will then forward the payload to the
- * local webhook endpoint where it is actually inserted into D1.
- */
-export class QStashNotificationService implements INotificationService {
-  private readonly client: Client
-  private readonly webhookUrl: string
-
-  constructor(
-    token: string,
-    appUrl: string,
-    private readonly scheduleBackgroundTask?: ScheduleBackgroundTask,
-    qstashUrl?: string
-  ) {
-    this.client = new Client({ 
-      token,
-      ...(qstashUrl ? { baseUrl: qstashUrl } : {})
-    })
-    this.webhookUrl = `${appUrl.replace(/\/$/, '')}/api/webhooks/qstash`
-  }
-
-  notify(input: CreateNotificationInput): Promise<void> | void {
-    const publishPromise = this.runPublish(input)
-
-    if (this.scheduleBackgroundTask) {
-      this.scheduleBackgroundTask(publishPromise)
-      return
-    }
-
-    return publishPromise
-  }
-
-  private async runPublish(input: CreateNotificationInput): Promise<void> {
-    try {
-      await this.client.publishJSON({
-        url: this.webhookUrl,
-        body: input,
-      })
-    } catch (error) {
-      console.error('QStashNotificationService: failed to publish notification', error)
-    }
-  }
-}

package/src/shared/query-utils.ts

@@ -1,141 +0,0 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-import type { FilterGroup, FilterType } from '@beechcms/core'
-
-/** Entry parsata per le risposte API — contratto immutabile (C7). */
-export interface ContentEntry {
-  id: string
-  schema_slug: string
-  slug: string | null
-  status: string
-  data: Record<string, unknown>
-  hasPendingDraft: boolean
-  created_at: number | null
-  updated_at: number | null
-}
-
-export type QueryFilterType = FilterType
-
-export type QueryFilterOperator =
-  | 'eq'
-  | 'gt'
-  | 'gte'
-  | 'lt'
-  | 'lte'
-  | 'contains'
-  | 'is_empty'
-  | 'is_not_empty'
-
-export interface QueryFilterCondition {
-  id?: string
-  op: QueryFilterOperator
-  value: string | number | boolean | null
-}
-
-/** Formato inviato dalla dashboard (usa columnId). */
-export interface QueryFilterGroup {
-  columnId: string
-  label?: string
-  type: QueryFilterType
-  conditions: QueryFilterCondition[]
-}
-
-const QUERY_FILTER_OPERATOR_SET = new Set<QueryFilterOperator>([
-  'eq', 'gt', 'gte', 'lt', 'lte', 'contains', 'is_empty', 'is_not_empty',
-])
-
-function isQueryFilterOperator(value: unknown): value is QueryFilterOperator {
-  return typeof value === 'string' && QUERY_FILTER_OPERATOR_SET.has(value as QueryFilterOperator)
-}
-
-export function cleanStr(val: unknown): string | null {
-  return (typeof val === 'string' && val.trim()) || null
-}
-
-export function safeParseJson(data: unknown): Record<string, unknown> {
-  const cleaned = cleanStr(data)
-  if (!cleaned) return {}
-  try {
-    const parsed = JSON.parse(cleaned)
-    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : {}
-  } catch {
-    return {}
-  }
-}
-
-export function parsePositiveInt(value: string | undefined, fallback: number): number {
-  if (!value) return fallback
-  const parsed = Number.parseInt(value, 10)
-  if (Number.isNaN(parsed) || parsed < 1) return fallback
-  return parsed
-}
-
-function parseCondition(cond: unknown): QueryFilterCondition | null {
-  if (!cond || typeof cond !== 'object') return null
-  const candidate = cond as Record<string, unknown>
-  if (!isQueryFilterOperator(candidate.op)) return null
-  const rawValue = candidate.value
-  let parsedValue: QueryFilterCondition['value'] = null
-  if (typeof rawValue === 'string' || typeof rawValue === 'number' || typeof rawValue === 'boolean') {
-    parsedValue = rawValue
-  }
-  return {
-    id: typeof candidate.id === 'string' ? candidate.id : undefined,
-    op: candidate.op,
-    value: parsedValue,
-  }
-}
-
-function parseFilterGroup(group: unknown): QueryFilterGroup | null {
-  if (!group || typeof group !== 'object') return null
-  const { columnId, type, label, conditions: rawConds } = group as Partial<QueryFilterGroup>
-  if (typeof columnId !== 'string' || typeof type !== 'string' || !Array.isArray(rawConds)) {
-    return null
-  }
-  const validConditions: QueryFilterCondition[] = []
-  for (const cond of rawConds) {
-    const parsedCond = parseCondition(cond)
-    if (parsedCond) validConditions.push(parsedCond)
-  }
-  if (validConditions.length === 0) return null
-  return {
-    columnId,
-    label: typeof label === 'string' ? label : undefined,
-    type,
-    conditions: validConditions,
-  }
-}
-
-/** Parse sicuro dei filtri da query-string (formato dashboard con columnId). */
-export function parseQueryFilters(raw: string | undefined): QueryFilterGroup[] {
-  if (!raw) return []
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(raw)
-  } catch {
-    return []
-  }
-  if (!parsed || typeof parsed !== 'object') return []
-  const result: QueryFilterGroup[] = []
-  for (const group of Object.values(parsed as Record<string, unknown>)) {
-    const parsedGroup = parseFilterGroup(group)
-    if (parsedGroup) result.push(parsedGroup)
-  }
-  return result
-}
-
-/**
- * Converte QueryFilterGroup[] (formato dashboard, columnId) in FilterGroup[]
- * compatibile con buildSelectQuery del Botanical Engine.
- */
-export function toEngineFilters(groups: QueryFilterGroup[]): FilterGroup[] {
-  return groups.map((g) => ({
-    column: g.columnId,
-    type: g.type,
-    conditions: g.conditions,
-  }))
-}

package/src/shared/request-utils.ts

@@ -1,26 +0,0 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-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/schema-mutator.d1.ts

@@ -1,64 +0,0 @@
-// SPDX-License-Identifier: BUSL-1.1
-// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
-// See LICENSE in the repository root for license terms.
-
-/// <reference types="@cloudflare/workers-types" />
-import type { ISchemaMutator } from '@beechcms/core'
-
-export class D1SchemaMutator implements ISchemaMutator {
-  constructor(private readonly db: D1Database) {}
-
-  async getColumns(table: string): Promise<Set<string> | null> {
-    // PRAGMA table_info returns rows {cid,name,type,notnull,dflt_value,pk}.
-    // Table name cannot be parameterized in PRAGMA — validate it is a safe identifier.
-    if (!/^[A-Za-z0-9_]+$/.test(table)) throw new Error(`Unsafe table name: ${table}`)
-    const rs = await this.db.prepare(`PRAGMA table_info(${table})`).all<{ name: string }>()
-    const rows = rs.results ?? []
-    if (rows.length === 0) return null // table absent
-    return new Set(rows.map(r => r.name))
-  }
-
-  async execDdl(statements: string[]): Promise<void> {
-    if (statements.length === 0) return
-    // D1 batch is atomic per call; if one statement fails, the rest roll back.
-    await this.db.batch(statements.map(s => this.db.prepare(s)))
-  }
-
-  // --- destructive (sprint 06 — Danger Zone) -------------------------------
-  // These emit IRREVERSIBLE SQL. Identifiers cannot be parameterized in DDL, so
-  // every table/column name is validated against the same `^[A-Za-z0-9_]+$`
-  // guard getColumns already applies before interpolation.
-
-  private static assertIdentifier(name: string): void {
-    if (!/^[A-Za-z0-9_]+$/.test(name)) throw new Error(`Unsafe identifier: ${name}`)
-  }
-
-  async dropTable(table: string): Promise<void> {
-    D1SchemaMutator.assertIdentifier(table)
-    await this.db.prepare(`DROP TABLE IF EXISTS ${table}`).run()
-  }
-
-  async dropColumn(table: string, column: string): Promise<void> {
-    D1SchemaMutator.assertIdentifier(table)
-    D1SchemaMutator.assertIdentifier(column)
-    await this.db.prepare(`ALTER TABLE ${table} DROP COLUMN ${column}`).run()
-  }
-
-  async renameColumn(table: string, from: string, to: string): Promise<void> {
-    D1SchemaMutator.assertIdentifier(table)
-    D1SchemaMutator.assertIdentifier(from)
-    D1SchemaMutator.assertIdentifier(to)
-    await this.db.prepare(`ALTER TABLE ${table} RENAME COLUMN ${from} TO ${to}`).run()
-  }
-
-  async execDestructive(statements: string[]): Promise<void> {
-    if (statements.length === 0) return
-    // The statements come from the core destructive generators
-    // (generateDropTable / generateRetypeColumn / planFtsRebuild), which only
-    // interpolate slugs/aliases already validated by the seed registry
-    // (`^[a-z0-9_]+$`). FTS trigger bodies legitimately contain internal
-    // semicolons (BEGIN … ; END), so we do not split or reject on `;`.
-    // D1 batch is atomic per call; if one statement fails, the rest roll back.
-    await this.db.batch(statements.map(s => this.db.prepare(s)))
-  }
-}