@beechcms/api 0.5.0 → 0.6.0-preview.2

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

@@ -1,64 +1,68 @@
-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
-  }
-}
+// 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

@@ -0,0 +1,67 @@
+// 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

@@ -0,0 +1,55 @@
+// 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,137 +1,141 @@
-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,
-  }))
-}
+// 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,22 +1,26 @@
-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
-}
+// 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
+}