@beechcms/api 0.4.0-preview.1

package/src/public/public-add.ts

@@ -0,0 +1,183 @@
+import { isValidContentStatus } from '@beechcms/core'
+import type { Seed } from '@beechcms/core'
+import type { Context } from 'hono'
+import { cleanStr } from '../shared/query-utils'
+import { buildInsertBindings } from '../shared/content-utils'
+import { checkPublicOperation } from './access-policy'
+import { publicProblem } from './problem-details'
+import { generateEntrySlug, slugify } from './slug-utils'
+import { sanitizePublicPayload } from './sanitize'
+import { createNotification } from '../shared/notification-service'
+
+type Bindings = {
+  DB: D1Database
+  PUBLIC_READ_API_KEY?: string
+  PUBLIC_WRITE_API_KEY?: string
+  PUBLIC_IDEMPOTENCY_TTL_SECONDS?: string
+  ENV?: string
+}
+
+type Variables = {
+  jwtPayload: { sub: string; email?: string }
+  getSeed: (slug: string) => Seed | null
+  seedRegistry: Record<string, Seed>
+}
+
+function errorMessage(c: Context<{ Bindings: Bindings; Variables: Variables }>, err: unknown): string {
+  if (c.env.ENV !== 'production' && err instanceof Error) return err.message
+  return 'An unexpected error occurred.'
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+function pickSlugFromBody(body: Record<string, unknown>, sanitizedData: Record<string, unknown>): string {
+  const explicitSlug = cleanStr(body.slug)
+  if (explicitSlug) return slugify(explicitSlug)
+  return generateEntrySlug({ title: sanitizedData.title, name: sanitizedData.name })
+}
+
+function parseIdempotencyKey(rawValue: string | undefined): string | null {
+  if (!rawValue) return null
+  const key = rawValue.trim()
+  if (!key || key.length > 128) return null
+  return key
+}
+
+function toHex(buffer: ArrayBuffer): string {
+  return [...new Uint8Array(buffer)].map((v) => v.toString(16).padStart(2, '0')).join('')
+}
+
+async function sha256Hex(input: string): Promise<string> {
+  const data = new TextEncoder().encode(input)
+  const digest = await crypto.subtle.digest('SHA-256', data)
+  return toHex(digest)
+}
+
+type StoredIdempotencyRecord = {
+  idempotency_key: string
+  request_fingerprint: string
+  response_status: number
+  response_body: string
+  expires_at: number
+}
+
+async function lookupIdempotency(db: D1Database, key: string): Promise<StoredIdempotencyRecord | null> {
+  return 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<StoredIdempotencyRecord>()
+}
+
+async function storeIdempotency(db: D1Database, input: {
+  key: string; fingerprint: string; responseStatus: number
+  responseBody: string; expiresAt: number; createdAt: number
+}): Promise<void> {
+  await 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(input.key, input.fingerprint, input.responseStatus, input.responseBody, input.createdAt, input.expiresAt).run()
+}
+
+export async function publicAddHandler(c: Context<{ Bindings: Bindings; Variables: Variables }>) {
+  const seedSlug = c.req.param('seed') ?? ''
+  const seed = c.get('getSeed')(seedSlug)
+  if (!seed) {
+    return publicProblem(c, { type: 'seed-not-found', title: 'Seed Not Found', status: 404, detail: `The content type '${seedSlug}' does not exist.` })
+  }
+  const access = checkPublicOperation(seed, 'add')
+  if (!access.ok) {
+    return publicProblem(c, { type: 'operation-not-allowed', title: access.error.error, status: 403, detail: access.error.message })
+  }
+
+  let body: Record<string, unknown>
+  try {
+    const parsed = await c.req.json<unknown>()
+    body = asRecord(parsed) ?? {}
+  } catch {
+    return publicProblem(c, { type: 'invalid-json-body', title: 'Bad Request', status: 400, detail: 'Invalid JSON body' })
+  }
+
+  const rawData = asRecord(body.data)
+  if (!rawData || Object.keys(rawData).length === 0) {
+    return publicProblem(c, { type: 'invalid-data-object', title: 'Bad Request', status: 400, detail: "Field 'data' is required and must be a non-empty object" })
+  }
+
+  const statusValue = body.status ?? 'draft'
+  if (!isValidContentStatus(statusValue)) {
+    return publicProblem(c, { type: 'invalid-status', title: 'Bad Request', status: 400, detail: 'Invalid status. Allowed values are: draft, review, published' })
+  }
+
+  const sanitized = sanitizePublicPayload(seed, rawData, {
+    operation: 'create', allowNull: false, requireAtLeastOneValidField: true, enforceRequiredFields: true,
+  })
+  if (!sanitized.ok) {
+    if (sanitized.status === 422) {
+      return publicProblem(c, { type: sanitized.code, title: 'Unprocessable Entity', status: 422, detail: sanitized.message })
+    }
+    return publicProblem(c, { type: sanitized.code, title: 'Bad Request', status: 400, detail: sanitized.message, errors: sanitized.details })
+  }
+
+  const idempotencyKey = parseIdempotencyKey(c.req.header('Idempotency-Key'))
+  const entrySlug = pickSlugFromBody(body, sanitized.data)
+  const finalSlug = entrySlug || crypto.randomUUID().slice(0, 8)
+  const table = `content_${seedSlug}`
+
+  try {
+    const { DB } = c.env
+    const now = Math.floor(Date.now() / 1000)
+    const fingerprintPayload = JSON.stringify({ seedSlug, statusValue, slug: cleanStr(body.slug) ?? null, data: sanitized.data })
+    const fingerprint = await sha256Hex(fingerprintPayload)
+    const idempotencyTtlSeconds = Math.max(60, Number.parseInt(c.env.PUBLIC_IDEMPOTENCY_TTL_SECONDS ?? '86400', 10) || 86400)
+
+    if (idempotencyKey) {
+      const existing = await lookupIdempotency(DB, idempotencyKey)
+      if (existing && existing.expires_at >= now) {
+        if (existing.request_fingerprint !== fingerprint) {
+          return publicProblem(c, { type: 'idempotency-key-conflict', title: 'Conflict', status: 409, detail: 'Idempotency-Key was already used with a different request payload.' })
+        }
+        let parsedBody: unknown = null
+        try { parsedBody = JSON.parse(existing.response_body) } catch { parsedBody = { success: true } }
+        return c.json(parsedBody, existing.response_status as 201)
+      }
+    }
+
+    const slugExisting = await DB.prepare(`SELECT id FROM ${table} WHERE slug = ? LIMIT 1`).bind(finalSlug).first<{ id: string }>()
+    if (slugExisting) {
+      return publicProblem(c, { type: 'slug-conflict', title: 'Conflict', status: 409, detail: `An entry with slug '${finalSlug}' already exists for content type '${seedSlug}'.` })
+    }
+
+    const id = crypto.randomUUID()
+    const { cols, placeholders, bindings } = buildInsertBindings(seed, sanitized.data)
+    const systemCols = ['id', 'slug', 'status', 'created_at', 'updated_at']
+    const systemVals = [id, finalSlug, statusValue, now, now]
+    const allCols = [...systemCols, ...cols].join(', ')
+    const allPlaceholders = [...systemVals.map(() => '?'), ...placeholders].join(', ')
+
+    await DB.prepare(`INSERT INTO ${table} (${allCols}) VALUES (${allPlaceholders})`).bind(...systemVals, ...bindings).run()
+
+    const responseBody = { success: true, id, slug: finalSlug }
+    if (idempotencyKey) {
+      await storeIdempotency(DB, { key: idempotencyKey, fingerprint, responseStatus: 201, responseBody: JSON.stringify(responseBody), createdAt: now, expiresAt: now + idempotencyTtlSeconds })
+    }
+
+    await createNotification(c, {
+      title: `${seed.label}: Nuovo inserimento`,
+      message: `Una nuova entry ("${sanitized.data.title || sanitized.data.name || finalSlug}") è stata aggiunta via API pubblica.`,
+      type: 'success',
+    })
+
+    return c.json(responseBody, 201)
+  } catch (err) {
+    return publicProblem(c, { type: 'internal-server-error', title: 'Internal Server Error', status: 500, detail: errorMessage(c, err) })
+  }
+}

package/src/public/public-edit.ts

@@ -0,0 +1,183 @@
+import { isValidContentStatus, resolvePolicies } from '@beechcms/core'
+import type { Seed } from '@beechcms/core'
+import type { Context } from 'hono'
+import { cleanStr } from '../shared/query-utils'
+import { rowToApiData, buildUpdateBindings } from '../shared/content-utils'
+import { checkPublicOperation } from './access-policy'
+import { publicProblem } from './problem-details'
+import { slugify } from './slug-utils'
+import { sanitizePublicPayload } from './sanitize'
+import { createNotification } from '../shared/notification-service'
+
+type Bindings = {
+  DB: D1Database
+  PUBLIC_READ_API_KEY?: string
+  PUBLIC_WRITE_API_KEY?: string
+  ENV?: string
+}
+
+type Variables = {
+  jwtPayload: { sub: string; email?: string }
+  getSeed: (slug: string) => Seed | null
+  seedRegistry: Record<string, Seed>
+}
+
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+type PublicCtx = Context<{ Bindings: Bindings; Variables: Variables }>
+type ResolveResult<T> = { ok: true; value: T } | { ok: false; response: Response }
+
+function errorMessage(c: PublicCtx, err: unknown): string {
+  if (c.env.ENV !== 'production' && err instanceof Error) return err.message
+  return 'An unexpected error occurred.'
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+function removeNullishFields(data: Record<string, unknown>): Record<string, unknown> {
+  const next: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(data)) {
+    if (value !== null) next[key] = value
+  }
+  return next
+}
+
+function parseBody(c: PublicCtx): Promise<ResolveResult<Record<string, unknown>>> {
+  return c.req.json<unknown>()
+    .then((parsed) => ({ ok: true, value: asRecord(parsed) ?? {} }) as const)
+    .catch(() => ({
+      ok: false,
+      response: publicProblem(c, { type: 'invalid-json-body', title: 'Bad Request', status: 400, detail: 'Invalid JSON body' }),
+    }))
+}
+
+function resolveSlug(c: PublicCtx, body: Record<string, unknown>, currentSlug: string): ResolveResult<{ slugRequested: boolean; nextSlug: string }> {
+  const slugRequested = Object.hasOwn(body, 'slug')
+  if (!slugRequested) return { ok: true, value: { slugRequested, nextSlug: currentSlug } }
+  const requestedSlug = cleanStr(body.slug)
+  if (!requestedSlug) {
+    return { ok: false, response: publicProblem(c, { type: 'invalid-slug', title: 'Bad Request', status: 400, detail: "Field 'slug' must be a non-empty string" }) }
+  }
+  return { ok: true, value: { slugRequested, nextSlug: slugify(requestedSlug) } }
+}
+
+function resolveStatus(c: PublicCtx, body: Record<string, unknown>, currentStatus: string): ResolveResult<string> {
+  if (!Object.hasOwn(body, 'status')) return { ok: true, value: currentStatus }
+  const statusValue = body.status
+  if (!isValidContentStatus(statusValue)) {
+    return { ok: false, response: publicProblem(c, { type: 'invalid-status', title: 'Bad Request', status: 400, detail: 'Invalid status. Allowed values are: draft, review, published' }) }
+  }
+  return { ok: true, value: statusValue }
+}
+
+function resolveData(
+  c: PublicCtx,
+  seed: Seed,
+  body: Record<string, unknown>,
+  currentRow: Record<string, unknown>
+): ResolveResult<Record<string, unknown>> {
+  if (!Object.hasOwn(body, 'data')) {
+    // No data update — return empty patch (caller keeps existing columns)
+    return { ok: true, value: {} }
+  }
+
+  const rawData = asRecord(body.data)
+  if (!rawData) {
+    return { ok: false, response: publicProblem(c, { type: 'invalid-data-object', title: 'Bad Request', status: 400, detail: "Field 'data' must be an object when provided" }) }
+  }
+
+  const sensitiveAliases = Object.keys(rawData).filter((alias) => {
+    const branch = seed.branches.find((b) => b.alias === alias)
+    return branch != null && resolvePolicies(branch).privacy !== 'plain'
+  })
+  if (sensitiveAliases.length > 0) {
+    return { ok: false, response: publicProblem(c, { type: 'sensitive-field-edit', title: 'Unprocessable Entity', status: 422, detail: `Cannot edit sensitive fields: ${sensitiveAliases.join(', ')}` }) }
+  }
+
+  const sanitized = sanitizePublicPayload(seed, rawData, { allowNull: true, operation: 'update', requireAtLeastOneValidField: true, enforceRequiredFields: true })
+  if (!sanitized.ok) {
+    if (sanitized.status === 422) {
+      return { ok: false, response: publicProblem(c, { type: sanitized.code, title: 'Unprocessable Entity', status: 422, detail: sanitized.message }) }
+    }
+    return { ok: false, response: publicProblem(c, { type: sanitized.code, title: 'Bad Request', status: 400, detail: sanitized.message, errors: sanitized.details }) }
+  }
+
+  // Merge: current columns + patch, remove nulls
+  const currentAliasData = rowToApiData(seed, currentRow)
+  const merged = removeNullishFields({ ...currentAliasData, ...sanitized.data })
+  return { ok: true, value: merged }
+}
+
+export async function publicEditHandler(c: PublicCtx) {
+  const seedSlug = c.req.param('seed') ?? ''
+  const id = c.req.param('id') ?? ''
+  const seed = c.get('getSeed')(seedSlug)
+  if (!seed) {
+    return publicProblem(c, { type: 'seed-not-found', title: 'Seed Not Found', status: 404, detail: `The content type '${seedSlug}' does not exist.` })
+  }
+  const access = checkPublicOperation(seed, 'edit')
+  if (!access.ok) {
+    return publicProblem(c, { type: 'operation-not-allowed', title: access.error.error, status: 403, detail: access.error.message })
+  }
+
+  if (!UUID_REGEX.test(id)) {
+    return publicProblem(c, { type: 'invalid-entry-id', title: 'Bad Request', status: 400, detail: 'Invalid entry ID format' })
+  }
+
+  const table = `content_${seedSlug}`
+
+  try {
+    const { DB } = c.env
+    const currentRow = await DB.prepare(`SELECT * FROM ${table} WHERE id = ? LIMIT 1`)
+      .bind(id)
+      .first<Record<string, unknown>>()
+
+    if (!currentRow) {
+      return publicProblem(c, { type: 'entry-not-found', title: 'Not Found', status: 404, detail: `Entry '${id}' not found for content type '${seedSlug}'.` })
+    }
+
+    const bodyResult = await parseBody(c)
+    if (!bodyResult.ok) return bodyResult.response
+
+    const slugResult = resolveSlug(c, bodyResult.value, (currentRow.slug as string) ?? '')
+    if (!slugResult.ok) return slugResult.response
+
+    const statusResult = resolveStatus(c, bodyResult.value, (currentRow.status as string) ?? 'draft')
+    if (!statusResult.ok) return statusResult.response
+
+    const dataResult = resolveData(c, seed, bodyResult.value, currentRow)
+    if (!dataResult.ok) return dataResult.response
+
+    if (slugResult.value.slugRequested) {
+      const slugExisting = await DB.prepare(`SELECT id FROM ${table} WHERE slug = ? AND id != ? LIMIT 1`)
+        .bind(slugResult.value.nextSlug, id)
+        .first<{ id: string }>()
+
+      if (slugExisting) {
+        return publicProblem(c, { type: 'slug-conflict', title: 'Conflict', status: 409, detail: `An entry with slug '${slugResult.value.nextSlug}' already exists for content type '${seedSlug}'.` })
+      }
+    }
+
+    const now = Math.floor(Date.now() / 1000)
+    const { setClause, bindings } = buildUpdateBindings(seed, dataResult.value)
+    const systemSet = `slug = ?, status = ?, updated_at = ?`
+    const fullSet = setClause ? `${systemSet}, ${setClause}` : systemSet
+
+    await DB.prepare(`UPDATE ${table} SET ${fullSet} WHERE id = ?`)
+      .bind(slugResult.value.nextSlug, statusResult.value, now, ...bindings, id)
+      .run()
+
+    await createNotification(c, {
+      title: `${seed.label}: Modifica`,
+      message: `L'entry "${slugResult.value.nextSlug}" è stata modificata via API pubblica.`,
+      type: 'info',
+    })
+
+    return c.json({ success: true, id, slug: slugResult.value.nextSlug }, 200)
+  } catch (err) {
+    return publicProblem(c, { type: 'internal-server-error', title: 'Internal Server Error', status: 500, detail: errorMessage(c, err) })
+  }
+}

package/src/public/public-errors.ts

@@ -0,0 +1,15 @@
+/**
+ * Error constants for Public API responses.
+ */
+export const PUBLIC_ERRORS = {
+  API_KEY_UNAUTHORIZED: {
+    error: 'Unauthorized',
+    message:
+      'Missing or invalid API key. Provide a valid key via X-API-Key header.',
+  },
+  API_KEY_FORBIDDEN: {
+    error: 'Forbidden',
+    message: 'Public API access is not configured for this instance.',
+  },
+} as const
+

package/src/public/public-read.ts

@@ -0,0 +1,217 @@
+import { resolvePolicies } from '@beechcms/core'
+import type { Seed } from '@beechcms/core'
+import type { Context } from 'hono'
+import { cleanStr } from '../shared/query-utils'
+import { rowToApiData } from '../shared/content-utils'
+import { checkPublicOperation } from './access-policy'
+import { publicProblem } from './problem-details'
+import { buildPublicListMeta, buildPublicSingleMeta } from './response-builder'
+import {
+  buildPublicFilterWhereClause,
+  parseLatestCount,
+  parsePublicFilter,
+  parsePublicPagination,
+} from './query-builder'
+
+type Bindings = {
+  DB: D1Database
+  PUBLIC_READ_API_KEY?: string
+  PUBLIC_WRITE_API_KEY?: string
+  PUBLIC_PUBLISHED_ONLY?: string
+  ENV?: string
+}
+
+type Variables = {
+  jwtPayload: { sub: string; email?: string }
+  getSeed: (slug: string) => Seed | null
+  seedRegistry: Record<string, Seed>
+}
+
+function buildSeedNotFoundMessage(seed: string, seedRegistry: Record<string, Seed>): string {
+  const available = Object.keys(seedRegistry).join(', ')
+  return `The content type '${seed}' does not exist. Available types: ${available}.`
+}
+
+/** Applica policy public/visibility per la Public API. */
+function applyPublicPolicies(aliasData: Record<string, unknown>, seed: Seed): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  for (const branch of seed.branches) {
+    const value = aliasData[branch.alias]
+    const { public: isPublic, visibility } = resolvePolicies(branch)
+    if (!isPublic) continue
+    if (visibility === 'hidden') continue
+    if (visibility === 'masked') {
+      result[branch.alias] = typeof value === 'string' && value.length > 0 ? '••••••••' : null
+    } else {
+      result[branch.alias] = value
+    }
+  }
+  return result
+}
+
+function toFlatPublicEntry(row: Record<string, unknown>, seed: Seed, fieldsParam?: string): Record<string, unknown> {
+  const aliasData = applyPublicPolicies(rowToApiData(seed, row), seed)
+  const base: Record<string, unknown> = {
+    id: row.id,
+    slug: row.slug,
+    status: row.status,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  }
+  const requestedFields = (fieldsParam ?? '').split(',').map((f) => f.trim()).filter(Boolean)
+  if (requestedFields.length === 0) return { ...base, ...aliasData }
+  const filteredData: Record<string, unknown> = {}
+  for (const field of requestedFields) {
+    if (field in aliasData) filteredData[field] = aliasData[field]
+  }
+  return { ...base, ...filteredData }
+}
+
+function withCache(
+  cache: Cache | undefined,
+  executionCtx: { waitUntil: (p: Promise<unknown>) => void } | undefined,
+  cacheKey: Request,
+  response: Response
+): Response {
+  if (cache && executionCtx) {
+    const cloned = response.clone()
+    const headers = new Headers(cloned.headers)
+    headers.set('Cache-Control', 'public, max-age=60')
+    executionCtx.waitUntil(cache.put(cacheKey, new Response(cloned.body, { status: cloned.status, headers })))
+  }
+  return response
+}
+
+function buildInternalErrorMessage(c: Context<{ Bindings: Bindings; Variables: Variables }>, err: unknown): string {
+  if (c.env.ENV !== 'production' && err instanceof Error) return err.message
+  return 'An unexpected error occurred.'
+}
+
+function buildOrderSql(seed: Seed, query: Record<string, string | undefined>, hasLatest: boolean): string {
+  if (hasLatest) return 'ORDER BY created_at DESC'
+  const orderBy = cleanStr(query.orderBy) ?? ''
+  const orderDir = (cleanStr(query.orderDir) ?? 'desc').toLowerCase()
+  if (orderBy === 'created_at' || orderBy === 'updated_at') {
+    return `ORDER BY ${orderBy} ${orderDir === 'asc' ? 'ASC' : 'DESC'}`
+  }
+  // Branch column — always a real column in v0.4.0
+  const branch = seed.branches.find((b) => b.alias === orderBy)
+  if (branch) {
+    const dir = orderDir === 'asc' ? 'ASC' : 'DESC'
+    return `ORDER BY ${branch.alias} ${dir} NULLS LAST`
+  }
+  return 'ORDER BY created_at DESC'
+}
+
+export async function publicReadHandler(c: Context<{ Bindings: Bindings; Variables: Variables }>) {
+  const seedSlug = c.req.param('seed') ?? ''
+  const seed = c.get('getSeed')(seedSlug)
+  if (!seed) {
+    return publicProblem(c, {
+      type: 'seed-not-found', title: 'Seed Not Found', status: 404,
+      detail: buildSeedNotFoundMessage(seedSlug, c.get('seedRegistry')),
+    })
+  }
+  const access = checkPublicOperation(seed, 'read')
+  if (!access.ok) {
+    return publicProblem(c, { type: 'operation-not-allowed', title: access.error.error, status: 403, detail: access.error.message })
+  }
+
+  let cache: Cache | undefined
+  let executionCtx: { waitUntil: (p: Promise<unknown>) => void } | undefined
+  try {
+    cache = caches.default
+    executionCtx = c.executionCtx as typeof executionCtx
+  } catch {}
+
+  const cacheKey = c.req.raw
+  if (cache) {
+    const hit = await cache.match(cacheKey)
+    if (hit) return hit
+  }
+
+  const query = c.req.query()
+  const id = cleanStr(query.id)
+  const table = `content_${seedSlug}`
+  const publishedOnly = c.env.PUBLIC_PUBLISHED_ONLY !== 'false'
+
+  try {
+    const { DB } = c.env
+
+    if (id) {
+      const row = await DB.prepare(
+        `SELECT * FROM ${table} WHERE id = ? ${publishedOnly ? "AND status = 'published'" : ''} LIMIT 1`
+      ).bind(id).first<Record<string, unknown>>()
+
+      if (!row) {
+        return publicProblem(c, { type: 'entry-not-found', title: 'Not Found', status: 404, detail: `Entry '${id}' not found for content type '${seedSlug}'.` })
+      }
+
+      return withCache(cache, executionCtx, cacheKey,
+        c.json({ data: toFlatPublicEntry(row, seed, query.fields), meta: buildPublicSingleMeta(seedSlug) }, 200)
+      )
+    }
+
+    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 whereParts: string[] = []
+    const whereBindings: Array<string | number> = []
+    if (publishedOnly) whereParts.push("status = 'published'")
+
+    if (search) {
+      // Search against slug and text/richtext columns
+      const searchableBranches = seed.branches.filter((b) => ['text', 'richtext'].includes(b.type))
+      const term = `%${search}%`
+      const searchExprs = ['slug LIKE ?', ...searchableBranches.map((b) => `${b.alias} LIKE ?`)]
+      whereParts.push(`(${searchExprs.join(' OR ')})`)
+      whereBindings.push(term, ...searchableBranches.map(() => term))
+    }
+
+    const filterClause = buildPublicFilterWhereClause(seed, parsedFilter)
+    if (filterClause.clause) {
+      whereParts.push(`(${filterClause.clause})`)
+      whereBindings.push(...filterClause.bindings)
+    }
+
+    const whereSql = whereParts.length > 0 ? `WHERE ${whereParts.join(' AND ')}` : ''
+    const countRow = await DB.prepare(`SELECT COUNT(*) as total FROM ${table} ${whereSql}`)
+      .bind(...whereBindings)
+      .first<{ total: number }>()
+    const total = countRow?.total ?? 0
+
+    const orderSql = buildOrderSql(seed, query, latestMode)
+    const effectiveLimit = latestMode ? (latestCount ?? 10) : pagination.limit
+    const effectiveOffset = latestMode ? 0 : offset
+
+    const rowsResult = await DB.prepare(`SELECT * FROM ${table} ${whereSql} ${orderSql} LIMIT ? OFFSET ?`)
+      .bind(...whereBindings, effectiveLimit, effectiveOffset)
+      .all<Record<string, unknown>>()
+
+    const rows = rowsResult.results ?? []
+    const data = rows.map((row) => toFlatPublicEntry(row, seed, query.fields))
+
+    if (latestMode) {
+      return withCache(cache, executionCtx, cacheKey,
+        c.json({ data, meta: { total, returned: data.length, seed: seedSlug } }, 200)
+      )
+    }
+
+    return withCache(cache, executionCtx, cacheKey,
+      c.json({
+        data,
+        meta: buildPublicListMeta({ total, page: pagination.page, limit: effectiveLimit, returned: data.length, seed: seedSlug }),
+      }, 200)
+    )
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith('Invalid filter:')) {
+      return publicProblem(c, { type: 'invalid-filter', title: 'Bad Request', status: 400, detail: err.message })
+    }
+    return publicProblem(c, { type: 'internal-server-error', title: 'Internal Server Error', status: 500, detail: buildInternalErrorMessage(c, err) })
+  }
+}

package/src/public/public-routes.ts

@@ -0,0 +1,31 @@
+import { Hono } from 'hono'
+import { publicReadHandler } from './public-read'
+import { publicAddHandler } from './public-add'
+import { publicEditHandler } from './public-edit'
+
+type Bindings = {
+  DB: D1Database
+  PUBLIC_READ_API_KEY?: string
+  PUBLIC_WRITE_API_KEY?: string
+  ENV?: string
+}
+
+type Variables = {
+  jwtPayload: { sub: string; email?: string }
+}
+
+const publicApp = new Hono<{ Bindings: Bindings; Variables: Variables }>()
+
+/**
+ * Step 1 smoke endpoint to validate API key middleware flow.
+ */
+publicApp.get('/health', (c) => {
+  return c.json({ ok: true, service: 'public-api' }, 200)
+})
+
+publicApp.get('/:seed', publicReadHandler)
+publicApp.post('/:seed/add', publicAddHandler)
+publicApp.put('/:seed/edit/:id', publicEditHandler)
+
+export const publicRoutes = publicApp
+