@beechcms/api 0.4.0-preview.11 → 0.4.0-preview.13

package/src/shared/fts-sync.ts

@@ -1,4 +1,4 @@
-// v0.4.0: FTS sync handled automatically by SQL triggers (generateFtsTriggers).
-// syncFts/deleteFts eliminated. This file kept as empty module to avoid import errors
-// during the Phase 4 → Phase 6 transition.
-export {}
+// v0.4.0: FTS sync handled automatically by SQL triggers (generateFtsTriggers).
+// syncFts/deleteFts eliminated. This file kept as empty module to avoid import errors
+// during the Phase 4 → Phase 6 transition.
+export {}

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

@@ -1,45 +1,56 @@
-import { IdempotencyRepository, IdempotencyRecord } from '@beechcms/core'
-import { BaseD1Repository } from './base.repository.d1.js'
-
-export class D1IdempotencyRepository extends BaseD1Repository implements IdempotencyRepository {
-  async lookup(key: string): Promise<IdempotencyRecord | null> {
-    const row = await this.db.prepare(
-      `SELECT idempotency_key, request_fingerprint, response_status, response_body, expires_at
-       FROM public_idempotency_keys WHERE idempotency_key = ? LIMIT 1`
-    ).bind(key).first<any>()
-
-    if (!row) return null
-
-    return {
-      key: row.idempotency_key,
-      fingerprint: row.request_fingerprint,
-      responseStatus: row.response_status,
-      responseBody: row.response_body,
-      expiresAt: row.expires_at
-    }
-  }
-
-  async store(record: IdempotencyRecord): Promise<void> {
-    await this.db.prepare(
-      `INSERT INTO public_idempotency_keys (idempotency_key, request_fingerprint, response_status, response_body, created_at, expires_at)
-       VALUES (?, ?, ?, ?, ?, ?)
-       ON CONFLICT(idempotency_key) DO UPDATE SET
-         request_fingerprint = excluded.request_fingerprint,
-         response_status = excluded.response_status,
-         response_body = excluded.response_body,
-         created_at = excluded.created_at,
-         expires_at = excluded.expires_at`
-    ).bind(
-      record.key, 
-      record.fingerprint, 
-      record.responseStatus, 
-      record.responseBody, 
-      Math.floor(Date.now() / 1000), 
-      record.expiresAt
-    ).run()
-  }
-
-  async cleanup(now: number): Promise<void> {
-    await this.db.prepare(`DELETE FROM public_idempotency_keys WHERE expires_at < ?`).bind(now).run()
-  }
-}
+import { IdempotencyRepository, IdempotencyRecord } from '@beechcms/core'
+import { BaseD1Repository } from './base.repository.d1.js'
+
+export class D1IdempotencyRepository extends BaseD1Repository implements IdempotencyRepository {
+  /**
+   * Looks up an idempotency record by its key.
+   */
+  async lookup(idempotencyKey: string): Promise<IdempotencyRecord | null> {
+    const idempotencyRecordResult = await this.database.prepare(
+      `SELECT idempotency_key, request_fingerprint, response_status, response_body, expires_at
+       FROM public_idempotency_keys WHERE idempotency_key = ? LIMIT 1`
+    ).bind(idempotencyKey).first<any>()
+
+    if (!idempotencyRecordResult) {
+      return null
+    }
+
+    return {
+      key: idempotencyRecordResult.idempotency_key,
+      fingerprint: idempotencyRecordResult.request_fingerprint,
+      responseStatus: idempotencyRecordResult.response_status,
+      responseBody: idempotencyRecordResult.response_body,
+      expiresAt: idempotencyRecordResult.expires_at
+    }
+  }
+
+  /**
+   * Stores or updates an idempotency record.
+   */
+  async store(idempotencyData: IdempotencyRecord): Promise<void> {
+    await this.database.prepare(
+      `INSERT INTO public_idempotency_keys (idempotency_key, request_fingerprint, response_status, response_body, created_at, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(idempotency_key) DO UPDATE SET
+         request_fingerprint = excluded.request_fingerprint,
+         response_status = excluded.response_status,
+         response_body = excluded.response_body,
+         created_at = excluded.created_at,
+         expires_at = excluded.expires_at`
+    ).bind(
+      idempotencyData.key, 
+      idempotencyData.fingerprint, 
+      idempotencyData.responseStatus, 
+      idempotencyData.responseBody, 
+      Math.floor(Date.now() / 1000), 
+      idempotencyData.expiresAt
+    ).run()
+  }
+
+  /**
+   * Cleans up expired idempotency records.
+   */
+  async cleanup(expirationTimestamp: number): Promise<void> {
+    await this.database.prepare(`DELETE FROM public_idempotency_keys WHERE expires_at < ?`).bind(expirationTimestamp).run()
+  }
+}

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

@@ -0,0 +1,64 @@
+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: MediaObject): 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/notification-service.ts

@@ -1,56 +1,56 @@
-import { Context } from 'hono'
-
-export interface NotificationParams {
-  title: string
-  message: string
-  type?: 'info' | 'success' | 'warning' | 'error'
-}
-
-/**
- * Crea una notifica persistente nel database D1.
- * Usata principalmente per segnalare azioni provenienti dalle Public API.
- */
-export async function createNotification(
-  c: Context<any>,
-  params: NotificationParams
-): Promise<void> {
-  const db = c.env.DB as D1Database
-  if (!db) return
-
-  const { title, message, type = 'info' } = params
-  const id = crypto.randomUUID()
-
-  // Usiamo waitUntil per non bloccare la richiesta dell'utente esterno
-  let executionCtx: { waitUntil: (p: Promise<any>) => void } | undefined
-  try {
-    executionCtx = c.executionCtx
-  } catch {
-    // In ambiente di test Hono lancia se non presente
-  }
-
-  if (executionCtx) {
-    executionCtx.waitUntil((async () => {
-      try {
-        await db.prepare(
-          `INSERT INTO notifications (id, title, message, type)
-           VALUES (?, ?, ?, ?)`
-        ).bind(id, title, message, type).run()
-      } catch (err) {
-        console.error('Failed to create notification:', err)
-      }
-    })())
-  } else {
-    // Fallback sync per test o ambienti senza executionCtx (se vogliamo che le notifiche siano create)
-    // Oppure semplicemente ignoriamo. In questo caso, per i test, meglio tentare di crearle
-    // ma dato che è un'azione opzionale "background", in test possiamo saltarla o farla sync.
-    // Facciamola sync se non c'è executionCtx per garantire che i test che verificano le notifiche (se ce ne sono) passino.
-    try {
-      await db.prepare(
-        `INSERT INTO notifications (id, title, message, type)
-         VALUES (?, ?, ?, ?)`
-      ).bind(id, title, message, type).run()
-    } catch (err) {
-      console.error('Failed to create notification (sync fallback):', err)
-    }
-  }
-}
+import { Context } from 'hono'
+
+export interface NotificationParams {
+  title: string
+  message: string
+  type?: 'info' | 'success' | 'warning' | 'error'
+}
+
+/**
+ * Crea una notifica persistente nel database D1.
+ * Usata principalmente per segnalare azioni provenienti dalle Public API.
+ */
+export async function createNotification(
+  c: Context<any>,
+  params: NotificationParams
+): Promise<void> {
+  const db = c.env.DB as D1Database
+  if (!db) return
+
+  const { title, message, type = 'info' } = params
+  const id = crypto.randomUUID()
+
+  // Usiamo waitUntil per non bloccare la richiesta dell'utente esterno
+  let executionCtx: { waitUntil: (p: Promise<any>) => void } | undefined
+  try {
+    executionCtx = c.executionCtx
+  } catch {
+    // In ambiente di test Hono lancia se non presente
+  }
+
+  if (executionCtx) {
+    executionCtx.waitUntil((async () => {
+      try {
+        await db.prepare(
+          `INSERT INTO notifications (id, title, message, type)
+           VALUES (?, ?, ?, ?)`
+        ).bind(id, title, message, type).run()
+      } catch (err) {
+        console.error('Failed to create notification:', err)
+      }
+    })())
+  } else {
+    // Fallback sync per test o ambienti senza executionCtx (se vogliamo che le notifiche siano create)
+    // Oppure semplicemente ignoriamo. In questo caso, per i test, meglio tentare di crearle
+    // ma dato che è un'azione opzionale "background", in test possiamo saltarla o farla sync.
+    // Facciamola sync se non c'è executionCtx per garantire che i test che verificano le notifiche (se ce ne sono) passino.
+    try {
+      await db.prepare(
+        `INSERT INTO notifications (id, title, message, type)
+         VALUES (?, ?, ?, ?)`
+      ).bind(id, title, message, type).run()
+    } catch (err) {
+      console.error('Failed to create notification (sync fallback):', err)
+    }
+  }
+}

package/src/shared/query-utils.ts

@@ -1,137 +1,137 @@
-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,
-  }))
-}
+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/storage/factory.ts

@@ -0,0 +1,40 @@
+import { BeechBucket, PutBucketOptions, GetBucketResult } from '@beechcms/core'
+import { Env } from '../../types'
+import { R2BindingBucket } from './r2-binding-bucket'
+import { S3Bucket } from './s3-bucket'
+
+class NullBucket implements BeechBucket {
+  private fail(): never {
+    throw new Error('No storage provider configured. Set MEDIA_BUCKET or R2 credentials.')
+  }
+  put(_key: string, _body: ArrayBuffer | Uint8Array | ReadableStream, _options?: PutBucketOptions): Promise<void> { return this.fail() }
+  get(_key: string): Promise<GetBucketResult | null> { return this.fail() }
+  delete(_key: string): Promise<void> { return this.fail() }
+  head(_key: string): Promise<{ size: number; contentType?: string; metadata?: Record<string, string> } | null> { return this.fail() }
+  getUrl(_key: string): string { return this.fail() }
+  getTotalSize(): Promise<number> { return this.fail() }
+  list(_options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{ objects: Array<{ key: string; size: number }>; cursor?: string }> { return this.fail() }
+}
+
+/**
+ * Creates the appropriate BeechBucket based on available bindings/credentials.
+ * Uses capability detection: R2 binding takes precedence over S3-compatible credentials.
+ */
+export function createBucketProvider(env: Env, baseUrl: string): BeechBucket {
+  if (env.MEDIA_BUCKET) {
+    return new R2BindingBucket(env.MEDIA_BUCKET, baseUrl)
+  }
+
+  if (env.R2_ACCESS_KEY_ID && env.R2_SECRET_ACCESS_KEY && env.R2_ENDPOINT && env.R2_BUCKET_NAME) {
+    return new S3Bucket({
+      endpoint: env.R2_ENDPOINT,
+      accessKeyId: env.R2_ACCESS_KEY_ID,
+      secretAccessKey: env.R2_SECRET_ACCESS_KEY,
+      bucketName: env.R2_BUCKET_NAME,
+      baseUrl,
+      cdnUrl: env.MEDIA_CDN_URL?.trim().replace(/\/$/, '') || undefined,
+    })
+  }
+
+  return new NullBucket()
+}