@beechcms/api 0.4.0-preview.1

package/src/shared/activity-logger.ts

@@ -0,0 +1,79 @@
+import { Context } from 'hono'
+
+export type ActivityAction = 'create' | 'update' | 'delete' | 'upload'
+export type EntityType = 'content' | 'media'
+
+export interface ActivityLogParams {
+  action: ActivityAction
+  entityType: EntityType
+  entityId: string
+  entitySlug?: string
+  details?: Record<string, any>
+}
+
+/**
+ * Logga un'azione utente asincronamente nel database D1.
+ * Estrae le info dell'utente dal JWT payload presente nel contesto Hono.
+ */
+export function logActivity(
+  c: Context<any>,
+  params: ActivityLogParams
+): void {
+  const db = c.env.DB as D1Database
+  const user = c.get('jwtPayload') as { sub: string; email: string; name?: string } | undefined
+
+  if (!db || !user) return
+
+  const { action, entityType, entityId, entitySlug, details } = params
+  const id = crypto.randomUUID()
+
+  // Usa waitUntil per non bloccare la risposta al client
+  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 activity_logs (id, user_id, user_email, user_name, action, entity_type, entity_id, entity_slug, details)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        ).bind(
+          id,
+          user.sub,
+          user.email || 'unknown',
+          user.name || null,
+          action,
+          entityType,
+          entityId,
+          entitySlug || null,
+          details ? JSON.stringify(details) : null
+        ).run()
+      } catch (err) {
+        console.error('Failed to log activity:', err)
+      }
+    })())
+  } else {
+    try {
+      db.prepare(
+        `INSERT INTO activity_logs (id, user_id, user_email, user_name, action, entity_type, entity_id, entity_slug, details)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      ).bind(
+        id,
+        user.sub,
+        user.email || 'unknown',
+        user.name || null,
+        action,
+        entityType,
+        entityId,
+        entitySlug || null,
+        details ? JSON.stringify(details) : null
+      ).run().catch(err => console.error('Failed to log activity (sync fallback):', err))
+    } catch (err) {
+      console.error('Failed to log activity (sync fallback):', err)
+    }
+  }
+}

package/src/shared/apply-policies.ts

@@ -0,0 +1,63 @@
+/// <reference types="@cloudflare/workers-types" />
+import { resolvePolicies, sha256hex } from '@beechcms/core'
+import type { Seed } from '@beechcms/core'
+
+class PrivacyPolicyError extends Error {
+  readonly status = 501 as const
+  constructor(message: string) {
+    super(message)
+    this.name = 'PrivacyPolicyError'
+  }
+}
+
+export { PrivacyPolicyError }
+
+/** Applica la privacy policy ai campi del payload prima della scrittura su DB. */
+export async function applyPrivacy(
+  data: Record<string, unknown>,
+  seed: Seed,
+): Promise<Record<string, unknown>> {
+  const result: Record<string, unknown> = {}
+  for (const [alias, value] of Object.entries(data)) {
+    const branch = seed.branches.find((b) => b.alias === alias)
+    if (!branch) {
+      result[alias] = value
+      continue
+    }
+    const { privacy } = resolvePolicies(branch)
+    if (privacy === 'encrypt') {
+      throw new PrivacyPolicyError(
+        `Field '${alias}' uses 'encrypt' privacy which is not yet implemented.`,
+      )
+    }
+    if (privacy === 'hash' && value != null) {
+      result[alias] = await sha256hex(String(value))
+    } else {
+      result[alias] = value
+    }
+  }
+  return result
+}
+
+/** Applica la visibility policy ai campi del payload in uscita verso il client. */
+export function applyVisibility(
+  data: Record<string, unknown>,
+  seed: Seed,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const [alias, value] of Object.entries(data)) {
+    const branch = seed.branches.find((b) => b.alias === alias)
+    if (!branch) {
+      result[alias] = value
+      continue
+    }
+    const { visibility } = resolvePolicies(branch)
+    if (visibility === 'hidden') continue
+    if (visibility === 'masked') {
+      result[alias] = typeof value === 'string' && value.length > 0 ? '••••••••' : null
+    } else {
+      result[alias] = value
+    }
+  }
+  return result
+}

package/src/shared/content-utils.ts

@@ -0,0 +1,108 @@
+/// <reference types="@cloudflare/workers-types" />
+import { deserializeFromDb, serializeForDb } from '@beechcms/core'
+import type { Seed } from '@beechcms/core'
+import type { ContentEntry } from './query-utils'
+
+/** Deserializza ogni branch colonna di un DB row in formato API alias. */
+export function rowToApiData(seed: Seed, row: Record<string, unknown>): Record<string, unknown> {
+  const data: Record<string, unknown> = {}
+  for (const branch of seed.branches) {
+    data[branch.alias] = deserializeFromDb(branch, row[branch.alias] ?? null)
+  }
+  return data
+}
+
+/** Converte un row della tabella content_{slug} in ContentEntry per le risposte API. */
+export function rowToEntry(
+  seed: Seed,
+  row: Record<string, unknown>,
+  hasPendingDraft = false
+): ContentEntry {
+  return {
+    id: row.id as string,
+    schema_slug: seed.slug,
+    slug: (row.slug as string | null) ?? null,
+    status: (row.status as string) ?? 'draft',
+    data: rowToApiData(seed, row),
+    hasPendingDraft,
+    created_at: (row.created_at as number | null) ?? null,
+    updated_at: (row.updated_at as number | null) ?? null,
+  }
+}
+
+export interface InsertBindings {
+  cols: string[]
+  placeholders: string[]
+  bindings: (string | number | null)[]
+}
+
+/** Costruisce colonne, placeholders e bindings per INSERT INTO content_{slug}. */
+export function buildInsertBindings(seed: Seed, payload: Record<string, unknown>): InsertBindings {
+  const cols: string[] = []
+  const placeholders: string[] = []
+  const bindings: (string | number | null)[] = []
+  for (const branch of seed.branches) {
+    if (Object.hasOwn(payload, branch.alias)) {
+      cols.push(branch.alias)
+      placeholders.push('?')
+      bindings.push(serializeForDb(branch, payload[branch.alias]))
+    }
+  }
+  return { cols, placeholders, bindings }
+}
+
+export interface UpdateBindings {
+  setClause: string
+  bindings: (string | number | null)[]
+}
+
+/** Costruisce SET clause e bindings per UPDATE content_{slug}. */
+export function buildUpdateBindings(seed: Seed, payload: Record<string, unknown>): UpdateBindings {
+  const setParts: string[] = []
+  const bindings: (string | number | null)[] = []
+  for (const branch of seed.branches) {
+    if (Object.hasOwn(payload, branch.alias)) {
+      setParts.push(`${branch.alias} = ?`)
+      bindings.push(serializeForDb(branch, payload[branch.alias]))
+    }
+  }
+  return { setClause: setParts.join(', '), bindings }
+}
+
+/** Controlla se esiste un draft pendente in content_{slug}_drafts. */
+export async function hasDraft(db: D1Database, seed: Seed, entryId: string): Promise<boolean> {
+  if (!seed.allowDrafts) return false
+  const row = await db
+    .prepare(`SELECT 1 FROM content_${seed.slug}_drafts WHERE entry_id = ? LIMIT 1`)
+    .bind(entryId)
+    .first()
+  return row !== null
+}
+
+/** Scrive un evento CRUD in content_event_log per l'activity feed. */
+export async function logContentEvent(
+  db: D1Database,
+  opts: {
+    action: 'create' | 'update' | 'delete'
+    schemaSlug: string
+    entryId: string
+    userId?: string | null
+    details?: Record<string, unknown>
+  }
+): Promise<void> {
+  await db
+    .prepare(
+      `INSERT INTO content_event_log (id, schema_slug, entry_id, action, user_id, details, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`
+    )
+    .bind(
+      crypto.randomUUID(),
+      opts.schemaSlug,
+      opts.entryId,
+      opts.action,
+      opts.userId ?? null,
+      opts.details ? JSON.stringify(opts.details) : null,
+      Math.floor(Date.now() / 1000)
+    )
+    .run()
+}

package/src/shared/fts-sync.ts

@@ -0,0 +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 {}

package/src/shared/notification-service.ts

@@ -0,0 +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)
+    }
+  }
+}

package/src/shared/query-utils.ts

@@ -0,0 +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,
+  }))
+}

package/src/shared/storage-utils.ts

@@ -0,0 +1,36 @@
+import { S3Client, ListObjectsV2Command, ListObjectsV2CommandOutput } from '@aws-sdk/client-s3'
+
+/**
+ * Calcola la dimensione totale occupata in un bucket R2 (in byte).
+ * Nota: esegue una scansione completa del bucket. Per bucket molto grandi 
+ * andrebbe implementata una cache o usato Cloudflare Logpush/Analytics.
+ */
+export async function getBucketSize(client: S3Client, bucketName: string): Promise<number> {
+  let totalSize = 0
+  let isTruncatedFlag = true
+  let continuationToken: string | undefined = undefined
+
+  try {
+    while (isTruncatedFlag) {
+      const command = new ListObjectsV2Command({
+        Bucket: bucketName,
+        ContinuationToken: continuationToken,
+      })
+
+      const response = (await client.send(command)) as ListObjectsV2CommandOutput
+      
+      if (response.Contents) {
+        for (const obj of response.Contents) {
+          totalSize += obj.Size ?? 0
+        }
+      }
+
+      isTruncatedFlag = response.IsTruncated ?? false
+      continuationToken = response.NextContinuationToken
+    }
+    return totalSize
+  } catch (err) {
+    console.error('Error calculating bucket size:', err)
+    return 0
+  }
+}

package/src/types.ts

@@ -0,0 +1,35 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { Seed } from '@beechcms/core'
+
+export interface Env {
+  DB: D1Database
+  JWT_SECRET: string
+  JWT_ISSUER?: string
+  JWT_AUDIENCE?: string
+  R2_ACCESS_KEY_ID?: string
+  R2_SECRET_ACCESS_KEY?: string
+  R2_ENDPOINT?: string
+  R2_BUCKET_NAME?: string
+  LOGIN_RATE_LIMITER?: RateLimit
+  REFRESH_RATE_LIMITER?: RateLimit
+  PUBLIC_READ_RATE_LIMITER?: RateLimit
+  PUBLIC_WRITE_RATE_LIMITER?: RateLimit
+  CORS_ORIGINS?: string
+  PUBLIC_READ_API_KEY?: string
+  PUBLIC_WRITE_API_KEY?: string
+  PUBLIC_PUBLISHED_ONLY?: string
+  PUBLIC_IDEMPOTENCY_TTL_SECONDS?: string
+  MEDIA_BASE_URL?: string
+  RESEND_API_KEY?: string
+  APP_URL?: string
+  EMAIL_FROM?: string
+  FORGOT_PASSWORD_RATE_LIMITER?: RateLimit
+  RESET_PASSWORD_RATE_LIMITER?: RateLimit
+  ENV?: string
+}
+
+export interface Variables {
+  jwtPayload: { sub: string; email?: string }
+  getSeed: (slug: string) => Seed | null
+  seedRegistry: Record<string, Seed>
+}