@beechcms/api 0.5.0 → 0.6.0-preview.2

package/src/public/query-builder.ts

@@ -1,152 +1,156 @@
-import type { Seed, FilterGroup, FilterOperator, FilterType, BranchType } from '@beechcms/core'
-import { parsePositiveInt } from '../shared/query-utils'
-
-export type PublicQueryInput = {
-  page?: string
-  limit?: string
-  latest?: string
-}
-
-export type PublicFilterLogic = 'AND' | 'OR'
-export type PublicFilterOperator =
-  | 'eq'
-  | 'neq'
-  | 'gt'
-  | 'gte'
-  | 'lt'
-  | 'lte'
-  | 'contains'
-  | 'not_contains'
-  | 'starts_with'
-  | 'ends_with'
-  | 'is_empty'
-  | 'is_not_empty'
-  | 'in'
-  | 'not_in'
-  | 'has_tag'
-  | 'has_any_tag'
-  | 'has_all_tags'
-
-export type PublicFilterCondition = {
-  field: string
-  op: PublicFilterOperator
-  value?: unknown
-}
-
-export type ParsedPublicFilter = {
-  where: PublicFilterCondition[]
-  logic: PublicFilterLogic
-}
-
-const PUBLIC_FILTER_OPERATORS = new Set<PublicFilterOperator>([
-  'eq', 'neq', 'gt', 'gte', 'lt', 'lte',
-  'contains', 'not_contains', 'starts_with', 'ends_with',
-  'is_empty', 'is_not_empty', 'in', 'not_in',
-  'has_tag', 'has_any_tag', 'has_all_tags',
-])
-
-function asString(value: unknown): string | null {
-  return typeof value === 'string' && value.trim() ? value.trim() : null
-}
-
-function validateLogic(logicRaw: unknown): PublicFilterLogic {
-  if (logicRaw === undefined) return 'AND'
-  if (typeof logicRaw !== 'string') throw new TypeError("Invalid filter: 'logic' must be 'AND' or 'OR'")
-  const normalized = logicRaw.toUpperCase()
-  if (normalized !== 'AND' && normalized !== 'OR') throw new TypeError("Invalid filter: 'logic' must be 'AND' or 'OR'")
-  return normalized
-}
-
-function parseWhereCondition(raw: unknown): PublicFilterCondition | null {
-  if (!raw || typeof raw !== 'object') return null
-  const maybe = raw as Record<string, unknown>
-  const field = asString(maybe.field)
-  const opRaw = asString(maybe.op)
-  if (!field || !opRaw || !PUBLIC_FILTER_OPERATORS.has(opRaw as PublicFilterOperator)) {
-    throw new TypeError(`Invalid filter: unknown operator '${opRaw ?? 'undefined'}'`)
-  }
-  return { field, op: opRaw as PublicFilterOperator, value: maybe.value }
-}
-
-export function parsePublicFilter(raw: string | undefined): ParsedPublicFilter | null {
-  if (!raw) return null
-  let parsed: unknown
-  try {
-    parsed = JSON.parse(raw)
-  } catch {
-    throw new TypeError('Invalid filter: malformed JSON')
-  }
-  if (!parsed || typeof parsed !== 'object') throw new TypeError('Invalid filter: object expected')
-  const filterObj = parsed as Record<string, unknown>
-  const logic = validateLogic(filterObj.logic)
-  if (!Array.isArray(filterObj.where)) throw new TypeError("Invalid filter: 'where' must be an array")
-  const where = filterObj.where
-    .map(parseWhereCondition)
-    .filter((item): item is PublicFilterCondition => item !== null)
-  return { where, logic }
-}
-
-const SYSTEM_COLUMNS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at'])
-
-function mapBranchToFilterType(type: BranchType): FilterType {
-  switch (type) {
-    case 'richtext':
-    case 'file':
-      return 'text'
-    case 'json':
-      return 'json'
-    case 'tags':
-      return 'tags'
-    case 'number':
-      return 'number'
-    case 'boolean':
-      return 'boolean'
-    case 'date':
-      return 'date'
-    case 'text':
-    default:
-      return 'text'
-  }
-}
-
-/**
- * Trasforma il filtro pubblico in FilterGroup[] per il Repository.
- * Zero SQL: la logica di generazione query risiede esclusivamente nel Repository/Engine core.
- */
-export function toEngineFilters(seed: Seed, parsedFilter: ParsedPublicFilter | null): FilterGroup[] {
-  if (!parsedFilter || parsedFilter.where.length === 0) return []
-  
-  // Note: Repository currently joins groups with AND. 
-  // Public API supports logic: OR but the core engine currently defaults to AND for top-level groups.
-  // We map each condition to a group for maximum compatibility with the engine's buildFilterCondition.
-  return parsedFilter.where.map((cond) => {
-    const branch = seed.branches.find(b => b.alias === cond.field)
-    const type: FilterType = branch 
-      ? mapBranchToFilterType(branch.type) 
-      : (SYSTEM_COLUMNS.has(cond.field) ? 'system' : 'text')
-    
-    return {
-      column: cond.field,
-      type,
-      conditions: [{
-        op: cond.op as FilterOperator,
-        value: cond.value as any
-      }]
-    }
-  })
-}
-
-export function parsePublicPagination(input: PublicQueryInput): { page: number; limit: number } {
-  const page = parsePositiveInt(input.page, 1)
-  const limit = Math.min(parsePositiveInt(input.limit, 25), 100)
-  return { page, limit }
-}
-
-export function parseLatestCount(latest: string | undefined): number {
-  if (!latest) return 10
-  const raw = Number.parseInt(latest, 10)
-  const parsed = Number.isNaN(raw) ? 10 : raw
-  if (parsed < 1) return 1
-  if (parsed > 100) return 100
-  return parsed
-}
+// 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 { Seed, FilterGroup, FilterOperator, FilterType, BranchType } from '@beechcms/core'
+import { parsePositiveInt } from '../shared/query-utils'
+
+export type PublicQueryInput = {
+  page?: string
+  limit?: string
+  latest?: string
+}
+
+export type PublicFilterLogic = 'AND' | 'OR'
+export type PublicFilterOperator =
+  | 'eq'
+  | 'neq'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'contains'
+  | 'not_contains'
+  | 'starts_with'
+  | 'ends_with'
+  | 'is_empty'
+  | 'is_not_empty'
+  | 'in'
+  | 'not_in'
+  | 'has_tag'
+  | 'has_any_tag'
+  | 'has_all_tags'
+
+export type PublicFilterCondition = {
+  field: string
+  op: PublicFilterOperator
+  value?: unknown
+}
+
+export type ParsedPublicFilter = {
+  where: PublicFilterCondition[]
+  logic: PublicFilterLogic
+}
+
+const PUBLIC_FILTER_OPERATORS = new Set<PublicFilterOperator>([
+  'eq', 'neq', 'gt', 'gte', 'lt', 'lte',
+  'contains', 'not_contains', 'starts_with', 'ends_with',
+  'is_empty', 'is_not_empty', 'in', 'not_in',
+  'has_tag', 'has_any_tag', 'has_all_tags',
+])
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null
+}
+
+function validateLogic(logicRaw: unknown): PublicFilterLogic {
+  if (logicRaw === undefined) return 'AND'
+  if (typeof logicRaw !== 'string') throw new TypeError("Invalid filter: 'logic' must be 'AND' or 'OR'")
+  const normalized = logicRaw.toUpperCase()
+  if (normalized !== 'AND' && normalized !== 'OR') throw new TypeError("Invalid filter: 'logic' must be 'AND' or 'OR'")
+  return normalized
+}
+
+function parseWhereCondition(raw: unknown): PublicFilterCondition | null {
+  if (!raw || typeof raw !== 'object') return null
+  const maybe = raw as Record<string, unknown>
+  const field = asString(maybe.field)
+  const opRaw = asString(maybe.op)
+  if (!field || !opRaw || !PUBLIC_FILTER_OPERATORS.has(opRaw as PublicFilterOperator)) {
+    throw new TypeError(`Invalid filter: unknown operator '${opRaw ?? 'undefined'}'`)
+  }
+  return { field, op: opRaw as PublicFilterOperator, value: maybe.value }
+}
+
+export function parsePublicFilter(raw: string | undefined): ParsedPublicFilter | null {
+  if (!raw) return null
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new TypeError('Invalid filter: malformed JSON')
+  }
+  if (!parsed || typeof parsed !== 'object') throw new TypeError('Invalid filter: object expected')
+  const filterObj = parsed as Record<string, unknown>
+  const logic = validateLogic(filterObj.logic)
+  if (!Array.isArray(filterObj.where)) throw new TypeError("Invalid filter: 'where' must be an array")
+  const where = filterObj.where
+    .map(parseWhereCondition)
+    .filter((item): item is PublicFilterCondition => item !== null)
+  return { where, logic }
+}
+
+const SYSTEM_COLUMNS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at'])
+
+function mapBranchToFilterType(type: BranchType): FilterType {
+  switch (type) {
+    case 'richtext':
+    case 'file':
+      return 'text'
+    case 'json':
+      return 'json'
+    case 'tags':
+      return 'tags'
+    case 'number':
+      return 'number'
+    case 'boolean':
+      return 'boolean'
+    case 'date':
+      return 'date'
+    case 'text':
+    default:
+      return 'text'
+  }
+}
+
+/**
+ * Trasforma il filtro pubblico in FilterGroup[] per il Repository.
+ * Zero SQL: la logica di generazione query risiede esclusivamente nel Repository/Engine core.
+ */
+export function toEngineFilters(seed: Seed, parsedFilter: ParsedPublicFilter | null): FilterGroup[] {
+  if (!parsedFilter || parsedFilter.where.length === 0) return []
+  
+  // Note: Repository currently joins groups with AND. 
+  // Public API supports logic: OR but the core engine currently defaults to AND for top-level groups.
+  // We map each condition to a group for maximum compatibility with the engine's buildFilterCondition.
+  return parsedFilter.where.map((cond) => {
+    const branch = seed.branches.find(b => b.alias === cond.field)
+    const type: FilterType = branch 
+      ? mapBranchToFilterType(branch.type) 
+      : (SYSTEM_COLUMNS.has(cond.field) ? 'system' : 'text')
+    
+    return {
+      column: cond.field,
+      type,
+      conditions: [{
+        op: cond.op as FilterOperator,
+        value: cond.value as any
+      }]
+    }
+  })
+}
+
+export function parsePublicPagination(input: PublicQueryInput): { page: number; limit: number } {
+  const page = parsePositiveInt(input.page, 1)
+  const limit = Math.min(parsePositiveInt(input.limit, 25), 100)
+  return { page, limit }
+}
+
+export function parseLatestCount(latest: string | undefined): number {
+  if (!latest) return 10
+  const raw = Number.parseInt(latest, 10)
+  const parsed = Number.isNaN(raw) ? 10 : raw
+  if (parsed < 1) return 1
+  if (parsed > 100) return 100
+  return parsed
+}

package/src/public/rate-limit-middleware.ts

@@ -1,30 +1,34 @@
-import type { Context, Next } from 'hono'
-import type { AppEnv } from '../types'
-import { publicProblem } from './problem-details'
-import { getClientIp } from '../shared/request-utils'
-
-function isReadMethod(method: string): boolean {
-  return method === 'GET' || method === 'HEAD' || method === 'OPTIONS'
-}
-
-export function publicRateLimitMiddleware() {
-  return async (c: Context<AppEnv>, next: Next): Promise<Response | void> => {
-    const readMethod = isReadMethod(c.req.method)
-    const limiterName = readMethod ? ('publicApiRead' as const) : ('publicApiWrite' as const)
-
-    const seed = c.req.param('seed') ?? 'no-seed'
-    const key = `${getClientIp(c.req)}:${seed}:${limiterName}`
-    const result = await c.get('rateLimiters').getLimiter(limiterName).checkLimit(key)
-
-    if (!result.isAllowed) {
-      return publicProblem(c, {
-        type: 'rate-limit-exceeded',
-        title: 'Too Many Requests',
-        status: 429,
-        detail: 'Too many requests',
-      })
-    }
-
-    await next()
-  }
-}
+// 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 { Context, Next } from 'hono'
+import type { AppEnv } from '../types'
+import { publicProblem } from './problem-details'
+import { getClientIp } from '../shared/request-utils'
+
+function isReadMethod(method: string): boolean {
+  return method === 'GET' || method === 'HEAD' || method === 'OPTIONS'
+}
+
+export function publicRateLimitMiddleware() {
+  return async (c: Context<AppEnv>, next: Next): Promise<Response | void> => {
+    const readMethod = isReadMethod(c.req.method)
+    const limiterName = readMethod ? ('publicApiRead' as const) : ('publicApiWrite' as const)
+
+    const seed = c.req.param('seed') ?? 'no-seed'
+    const key = `${getClientIp(c.req)}:${seed}:${limiterName}`
+    const result = await c.get('rateLimiters').getLimiter(limiterName).checkLimit(key)
+
+    if (!result.isAllowed) {
+      return publicProblem(c, {
+        type: 'rate-limit-exceeded',
+        title: 'Too Many Requests',
+        status: 429,
+        detail: 'Too many requests',
+      })
+    }
+
+    await next()
+  }
+}

package/src/public/read-list.ts

@@ -1,50 +1,54 @@
-import type { Seed, ContentRepository } from '@beechcms/core'
-import { cleanStr } from '../shared/query-utils'
-import { toFlatPublicEntry } from './entry-projection'
-import { buildPublicListMeta } from './response-builder'
-import { parsePublicFilter, parsePublicPagination, parseLatestCount, toEngineFilters } from './query-builder'
-
-type ReadListInput = {
-  seed: Seed
-  seedSlug: string
-  repository: ContentRepository
-  query: Record<string, string | undefined>
-  publishedOnly: boolean
-}
-
-export async function readListEntries(input: ReadListInput) {
-  const { seed, seedSlug, repository, query, publishedOnly } = input
-
-  const parsedFilter = parsePublicFilter(query.filter)
-  const allMode = cleanStr(query.all)?.toLowerCase() === 'true'
-  const latestMode = cleanStr(query.latest) !== null
-  const latestCount = latestMode ? parseLatestCount(query.latest ?? '') : null
-  const pagination = allMode ? { page: 1, limit: 100 } : parsePublicPagination(query)
-  const offset = (pagination.page - 1) * pagination.limit
-  const search = cleanStr(query.search) ?? ''
-  const engineFilters = toEngineFilters(seed, parsedFilter)
-  const sortBy = cleanStr(query.orderBy) ?? 'created_at'
-  const sortDir = (cleanStr(query.orderDir) ?? 'desc').toLowerCase() === 'asc' ? 'ASC' : 'DESC'
-
-  const { items, total } = await repository.findMany(seed, {
-    filters: engineFilters,
-    search: search || undefined,
-    status: publishedOnly ? 'published' : null,
-    pagination: {
-      limit: latestMode ? (latestCount ?? 10) : pagination.limit,
-      offset: latestMode ? 0 : offset,
-    },
-    orderBy: latestMode ? { column: 'created_at', dir: 'DESC' } : { column: sortBy, dir: sortDir },
-  })
-
-  const data = items.map(item => toFlatPublicEntry(item, seed, query.fields))
-
-  if (latestMode) {
-    return { data, meta: { total, returned: data.length, seed: seedSlug } }
-  }
-
-  return {
-    data,
-    meta: buildPublicListMeta({ total, page: pagination.page, limit: pagination.limit, returned: data.length, seed: seedSlug }),
-  }
-}
+// 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 { Seed, ContentRepository } from '@beechcms/core'
+import { cleanStr } from '../shared/query-utils'
+import { toFlatPublicEntry } from './entry-projection'
+import { buildPublicListMeta } from './response-builder'
+import { parsePublicFilter, parsePublicPagination, parseLatestCount, toEngineFilters } from './query-builder'
+
+type ReadListInput = {
+  seed: Seed
+  seedSlug: string
+  repository: ContentRepository
+  query: Record<string, string | undefined>
+  publishedOnly: boolean
+}
+
+export async function readListEntries(input: ReadListInput) {
+  const { seed, seedSlug, repository, query, publishedOnly } = input
+
+  const parsedFilter = parsePublicFilter(query.filter)
+  const allMode = cleanStr(query.all)?.toLowerCase() === 'true'
+  const latestMode = cleanStr(query.latest) !== null
+  const latestCount = latestMode ? parseLatestCount(query.latest ?? '') : null
+  const pagination = allMode ? { page: 1, limit: 100 } : parsePublicPagination(query)
+  const offset = (pagination.page - 1) * pagination.limit
+  const search = cleanStr(query.search) ?? ''
+  const engineFilters = toEngineFilters(seed, parsedFilter)
+  const sortBy = cleanStr(query.orderBy) ?? 'created_at'
+  const sortDir = (cleanStr(query.orderDir) ?? 'desc').toLowerCase() === 'asc' ? 'ASC' : 'DESC'
+
+  const { items, total } = await repository.findMany(seed, {
+    filters: engineFilters,
+    search: search || undefined,
+    status: publishedOnly ? 'published' : null,
+    pagination: {
+      limit: latestMode ? (latestCount ?? 10) : pagination.limit,
+      offset: latestMode ? 0 : offset,
+    },
+    orderBy: latestMode ? { column: 'created_at', dir: 'DESC' } : { column: sortBy, dir: sortDir },
+  })
+
+  const data = items.map(item => toFlatPublicEntry(item, seed, query.fields))
+
+  if (latestMode) {
+    return { data, meta: { total, returned: data.length, seed: seedSlug } }
+  }
+
+  return {
+    data,
+    meta: buildPublicListMeta({ total, page: pagination.page, limit: pagination.limit, returned: data.length, seed: seedSlug }),
+  }
+}

package/src/public/read-single.ts

@@ -1,44 +1,48 @@
-import { EntryNotFoundError } from '@beechcms/core'
-import type { Seed, ContentRepository } from '@beechcms/core'
-import { toFlatPublicEntry } from './entry-projection'
-import { buildPublicSingleMeta } from './response-builder'
-
-type ReadSingleInput = {
-  seed: Seed
-  seedSlug: string
-  repository: ContentRepository
-  id: string | null
-  slug: string | null
-  publishedOnly: boolean
-  fieldsParam?: string
-}
-
-export type ReadSingleResult =
-  | { ok: true; data: Record<string, unknown>; meta: { seed: string } }
-  | { ok: false; detail: string }
-
-export async function readSingleEntry(input: ReadSingleInput): Promise<ReadSingleResult> {
-  const { seed, seedSlug, repository, id, slug, publishedOnly, fieldsParam } = input
-  const label = id ?? slug!
-
-  try {
-    const entry = id
-      ? await repository.findById(seed, id)
-      : await repository.findBySlug(seed, slug!)
-
-    if (publishedOnly && entry.status !== 'published') {
-      return { ok: false, detail: `Entry '${label}' not found or not published.` }
-    }
-
-    return {
-      ok: true,
-      data: toFlatPublicEntry(entry, seed, fieldsParam),
-      meta: buildPublicSingleMeta(seedSlug),
-    }
-  } catch (error) {
-    if (error instanceof EntryNotFoundError) {
-      return { ok: false, detail: `Entry '${label}' not found for content type '${seedSlug}'.` }
-    }
-    throw error
-  }
-}
+// 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 { EntryNotFoundError } from '@beechcms/core'
+import type { Seed, ContentRepository } from '@beechcms/core'
+import { toFlatPublicEntry } from './entry-projection'
+import { buildPublicSingleMeta } from './response-builder'
+
+type ReadSingleInput = {
+  seed: Seed
+  seedSlug: string
+  repository: ContentRepository
+  id: string | null
+  slug: string | null
+  publishedOnly: boolean
+  fieldsParam?: string
+}
+
+export type ReadSingleResult =
+  | { ok: true; data: Record<string, unknown>; meta: { seed: string } }
+  | { ok: false; detail: string }
+
+export async function readSingleEntry(input: ReadSingleInput): Promise<ReadSingleResult> {
+  const { seed, seedSlug, repository, id, slug, publishedOnly, fieldsParam } = input
+  const label = id ?? slug!
+
+  try {
+    const entry = id
+      ? await repository.findById(seed, id)
+      : await repository.findBySlug(seed, slug!)
+
+    if (publishedOnly && entry.status !== 'published') {
+      return { ok: false, detail: `Entry '${label}' not found or not published.` }
+    }
+
+    return {
+      ok: true,
+      data: toFlatPublicEntry(entry, seed, fieldsParam),
+      meta: buildPublicSingleMeta(seedSlug),
+    }
+  } catch (error) {
+    if (error instanceof EntryNotFoundError) {
+      return { ok: false, detail: `Entry '${label}' not found for content type '${seedSlug}'.` }
+    }
+    throw error
+  }
+}

package/src/public/response-builder.ts

@@ -1,26 +1,30 @@
-/**
- * Helper meta per risposta lista Public API.
- */
-export function buildPublicListMeta(input: {
-  total: number
-  page: number
-  limit: number
-  returned: number
-  seed: string
-}) {
-  return {
-    total: input.total,
-    page: input.page,
-    limit: input.limit,
-    returned: input.returned,
-    seed: input.seed,
-  }
-}
-
-/**
- * Helper meta per risposta singolo elemento Public API.
- */
-export function buildPublicSingleMeta(seed: string) {
-  return { seed }
-}
-
+// 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.
+
+/**
+ * Helper meta per risposta lista Public API.
+ */
+export function buildPublicListMeta(input: {
+  total: number
+  page: number
+  limit: number
+  returned: number
+  seed: string
+}) {
+  return {
+    total: input.total,
+    page: input.page,
+    limit: input.limit,
+    returned: input.returned,
+    seed: input.seed,
+  }
+}
+
+/**
+ * Helper meta per risposta singolo elemento Public API.
+ */
+export function buildPublicSingleMeta(seed: string) {
+  return { seed }
+}
+