@beechcms/api 0.4.0-preview.9 → 0.4.1

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

package/src/shared/storage/r2-binding-bucket.ts

@@ -0,0 +1,81 @@
+import { BeechBucket, PutBucketOptions, GetBucketResult } from '@beechcms/core'
+
+/**
+ * Implementation of BeechBucket using Cloudflare R2 native binding.
+ * Used for local development (Miniflare) or native Cloudflare Workers deployment.
+ */
+export class R2BindingBucket implements BeechBucket {
+  constructor(
+    private bucket: R2Bucket,
+    private baseUrl: string
+  ) {}
+
+  async put(key: string, body: ArrayBuffer | Uint8Array | ReadableStream, options?: PutBucketOptions): Promise<void> {
+    await this.bucket.put(key, body, {
+      httpMetadata: { contentType: options?.contentType },
+      customMetadata: options?.metadata
+    })
+  }
+
+  async get(key: string): Promise<GetBucketResult | null> {
+    const object = await this.bucket.get(key)
+    if (!object) return null
+
+    return {
+      body: object.body,
+      contentType: object.httpMetadata?.contentType,
+      size: object.size,
+      metadata: object.customMetadata
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.bucket.delete(key)
+  }
+
+  async head(key: string): Promise<{ size: number; contentType?: string; metadata?: Record<string, string> } | null> {
+    const object = await this.bucket.head(key)
+    if (!object) return null
+
+    return {
+      size: object.size,
+      contentType: object.httpMetadata?.contentType,
+      metadata: object.customMetadata
+    }
+  }
+
+  getUrl(key: string): string {
+    // If baseUrl is just the origin, we use the proxied route.
+    // If it's a custom CDN/R2 domain, it might not need /api/media/
+    // but for now, we maintain the contract: the provider decides the full URL.
+    if (this.baseUrl.includes('/api/media')) {
+       return `${this.baseUrl}/${encodeURIComponent(key)}`
+    }
+    return `${this.baseUrl}/api/media/${encodeURIComponent(key)}`
+  }
+
+  async getTotalSize(): Promise<number> {
+    let total = 0
+    let cursor: string | undefined
+    do {
+      const result: R2Objects = await this.bucket.list({ cursor })
+      for (const obj of result.objects) {
+        total += obj.size
+      }
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+    return total
+  }
+
+  async list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{ objects: Array<{ key: string; size: number }>; cursor?: string }> {
+    const result = await this.bucket.list({
+      prefix: options?.prefix,
+      limit: options?.limit,
+      cursor: options?.cursor
+    })
+    return {
+      objects: result.objects.map(obj => ({ key: obj.key, size: obj.size })),
+      cursor: result.truncated ? result.cursor : undefined
+    }
+  }
+}

package/src/shared/storage/s3-bucket.ts

@@ -0,0 +1,163 @@
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, HeadObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3'
+import { BeechBucket, PutBucketOptions, GetBucketResult } from '@beechcms/core'
+
+/**
+ * Implementation of BeechBucket using S3-compatible API (AWS SDK).
+ * Used for production when connecting to R2 or any other S3 provider via HTTP.
+ */
+export class S3Bucket implements BeechBucket {
+  private client: S3Client
+  private bucketName: string
+  private baseUrl: string
+
+  private cdnUrl: string | null
+
+  constructor(config: {
+    endpoint: string,
+    accessKeyId: string,
+    secretAccessKey: string,
+    bucketName: string,
+    baseUrl: string,
+    cdnUrl?: string,
+  }) {
+    this.client = new S3Client({
+      region: 'auto',
+      endpoint: config.endpoint,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey,
+      },
+      forcePathStyle: true,
+    })
+    this.bucketName = config.bucketName
+    this.baseUrl = config.baseUrl
+    this.cdnUrl = config.cdnUrl ?? null
+  }
+
+  async put(key: string, body: ArrayBuffer | Uint8Array | ReadableStream, options?: PutBucketOptions): Promise<void> {
+    const command = new PutObjectCommand({
+      Bucket: this.bucketName,
+      Key: key,
+      Body: body instanceof ReadableStream ? await this.streamToUint8Array(body) : new Uint8Array(body as ArrayBuffer),
+      ContentType: options?.contentType,
+      Metadata: options?.metadata
+    })
+    await this.client.send(command)
+  }
+
+  private async streamToUint8Array(stream: ReadableStream): Promise<Uint8Array> {
+    const reader = stream.getReader()
+    const chunks: Uint8Array[] = []
+    let totalLength = 0
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      chunks.push(value)
+      totalLength += value.length
+    }
+    const result = new Uint8Array(totalLength)
+    let offset = 0
+    for (const chunk of chunks) {
+      result.set(chunk, offset)
+      offset += chunk.length
+    }
+    return result
+  }
+
+  async get(key: string): Promise<GetBucketResult | null> {
+    try {
+      const command = new GetObjectCommand({
+        Bucket: this.bucketName,
+        Key: key
+      })
+      const response = await this.client.send(command)
+      
+      if (!response.Body) return null
+
+      const rawBody = response.Body as any
+      const body: ReadableStream = typeof rawBody.transformToWebStream === 'function'
+        ? rawBody.transformToWebStream()
+        : rawBody as ReadableStream
+
+      return {
+        body,
+        contentType: response.ContentType,
+        size: response.ContentLength ?? 0,
+        metadata: response.Metadata
+      }
+    } catch (err: any) {
+      if (err.name === 'NoSuchKey' || err.name === 'NotFound' || err.message === 'NoSuchKey') {
+        return null
+      }
+      // Rethrow other errors (AccessDenied, Timeout, etc.)
+      throw err
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    const command = new DeleteObjectCommand({
+      Bucket: this.bucketName,
+      Key: key
+    })
+    await this.client.send(command)
+  }
+
+  async head(key: string): Promise<{ size: number; contentType?: string; metadata?: Record<string, string> } | null> {
+    try {
+      const command = new HeadObjectCommand({
+        Bucket: this.bucketName,
+        Key: key
+      })
+      const response = await this.client.send(command)
+      return {
+        size: response.ContentLength ?? 0,
+        contentType: response.ContentType,
+        metadata: response.Metadata
+      }
+    } catch (err: any) {
+      if (err.name === 'NoSuchKey' || err.name === 'NotFound') return null
+      throw err
+    }
+  }
+
+  getUrl(key: string): string {
+    if (this.cdnUrl) {
+      return `${this.cdnUrl}/${encodeURIComponent(key)}`
+    }
+    return `${this.baseUrl}/api/media/${encodeURIComponent(key)}`
+  }
+
+  async getTotalSize(): Promise<number> {
+    let total = 0
+    let token: string | undefined
+    do {
+      const command = new ListObjectsV2Command({
+        Bucket: this.bucketName,
+        ContinuationToken: token
+      })
+      const response = await this.client.send(command)
+      for (const obj of response.Contents ?? []) {
+        total += obj.Size ?? 0
+      }
+      token = response.NextContinuationToken
+    } while (token)
+    return total
+  }
+
+  async list(options?: { prefix?: string; limit?: number; cursor?: string }): Promise<{ objects: Array<{ key: string; size: number }>; cursor?: string }> {
+    const command = new ListObjectsV2Command({
+      Bucket: this.bucketName,
+      Prefix: options?.prefix,
+      MaxKeys: options?.limit,
+      ContinuationToken: options?.cursor
+    })
+    const response = await this.client.send(command)
+    return {
+      objects: (response.Contents ?? []).map(obj => ({
+        key: obj.Key ?? '',
+        size: obj.Size ?? 0
+      })),
+      cursor: response.NextContinuationToken
+    }
+  }
+}