@beechcms/api 0.4.0 → 0.4.2

package/src/public/public-read.ts

@@ -1,216 +1,59 @@
-import { resolvePolicies, EntryNotFoundError } from '@beechcms/core'
-import type { Seed } from '@beechcms/core'
-import type { Context } from 'hono'
-import { cleanStr } from '../shared/query-utils'
-import { checkPublicOperation } from './access-policy'
-import { publicProblem } from './problem-details'
-import { buildPublicListMeta, buildPublicSingleMeta } from './response-builder'
-import {
-  parseLatestCount,
-  parsePublicFilter,
-  parsePublicPagination,
-  toEngineFilters,
-} from './query-builder'
-import { AppEnv } from '../types'
-
-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}.`
-}
-
-/** Applies public/visibility policies for the Public API. */
-function applyPublicPolicies(data: Record<string, unknown>, seed: Seed): Record<string, unknown> {
-  const result: Record<string, unknown> = {}
-  
-  // System fields are mapped to top-level for public API
-  const system = ['id', 'slug', 'status', 'created_at', 'updated_at']
-  for (const key of system) {
-    if (key in data) result[key] = data[key]
-  }
-
-  for (const branch of seed.branches) {
-    const value = data[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(data: Record<string, unknown>, seed: Seed, fieldsParam?: string): Record<string, unknown> {
-  const aliasData = applyPublicPolicies(data, seed)
-  const requestedFields = (fieldsParam ?? '').split(',').map((f) => f.trim()).filter(Boolean)
-  
-  if (requestedFields.length === 0) return aliasData
-  
-  const filteredData: Record<string, unknown> = {}
-  for (const field of requestedFields) {
-    if (field in aliasData) filteredData[field] = aliasData[field]
-  }
-  
-  // Always include basic identity fields if they exist in filtered data or if requested
-  const identity = ['id', 'slug']
-  for (const key of identity) {
-    if (key in aliasData && !filteredData[key]) filteredData[key] = aliasData[key]
-  }
-  
-  return 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(context: Context<AppEnv>, error: unknown): string {
-  if (context.env.ENV !== 'production' && error instanceof Error) return error.message
-  return 'An unexpected error occurred.'
-}
-
-export async function publicReadHandler(context: Context<AppEnv>) {
-  const seedSlug = context.req.param('seed') ?? ''
-  const seed = context.get('getSeed')(seedSlug)
-  if (!seed) {
-    return publicProblem(context, {
-      type: 'seed-not-found', 
-      title: 'Seed Not Found', 
-      status: 404,
-      detail: buildSeedNotFoundMessage(seedSlug, context.get('seedRegistry')),
-    })
-  }
-  
-  const access = checkPublicOperation(seed, 'read')
-  if (!access.ok) {
-    return publicProblem(context, { 
-      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 = context.executionCtx as typeof executionCtx
-  } catch {}
-
-  const cacheKey = context.req.raw
-  if (cache) {
-    const hit = await cache.match(cacheKey)
-    if (hit) return hit
-  }
-
-  const query = context.req.query()
-  const id = cleanStr(query.id)
-  const slug = cleanStr(query.slug)
-  const publishedOnly = context.env.PUBLIC_PUBLISHED_ONLY !== 'false'
-  const repository = context.get('repository')
-
-  try {
-    if (id || slug) {
-      try {
-        const entry = id 
-          ? await repository.findById(seed, id)
-          : await repository.findBySlug(seed, slug!)
-        
-        if (publishedOnly && entry.status !== 'published') {
-          return publicProblem(context, { 
-            type: 'entry-not-found', 
-            title: 'Not Found', 
-            status: 404, 
-            detail: `Entry '${id || slug}' not found or not published.` 
-          })
-        }
-
-        return withCache(cache, executionCtx, cacheKey,
-          context.json({ 
-            data: toFlatPublicEntry(entry, seed, query.fields), 
-            meta: buildPublicSingleMeta(seedSlug) 
-          }, 200)
-        )
-      } catch (error) {
-        if (error instanceof EntryNotFoundError) {
-          return publicProblem(context, { 
-            type: 'entry-not-found', 
-            title: 'Not Found', 
-            status: 404, 
-            detail: `Entry '${id || slug}' not found for content type '${seedSlug}'.` 
-          })
-        }
-        throw error
-      }
-    }
-
-    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 withCache(cache, executionCtx, cacheKey,
-        context.json({ data, meta: { total, returned: data.length, seed: seedSlug } }, 200)
-      )
-    }
-
-    return withCache(cache, executionCtx, cacheKey,
-      context.json({
-        data,
-        meta: buildPublicListMeta({ 
-          total, 
-          page: pagination.page, 
-          limit: latestMode ? (latestCount ?? 10) : pagination.limit, 
-          returned: data.length, 
-          seed: seedSlug 
-        }),
-      }, 200)
-    )
-  } catch (error) {
-    if (error instanceof Error && error.message.startsWith('Invalid filter:')) {
-      return publicProblem(context, { type: 'invalid-filter', title: 'Bad Request', status: 400, detail: error.message })
-    }
-    console.error('Public read error:', error)
-    return publicProblem(context, { 
-      type: 'internal-server-error', 
-      title: 'Internal Server Error', 
-      status: 500, 
-      detail: buildInternalErrorMessage(context, error) 
-    })
-  }
-}
+import type { Context } from 'hono'
+import { cleanStr } from '../shared/query-utils'
+import { checkPublicOperation } from './access-policy'
+import { publicProblem, internalErrorDetail } from './problem-details'
+import { resolveEdgeCache, withCachedResponse } from './cache-utils'
+import { readSingleEntry } from './read-single'
+import { readListEntries } from './read-list'
+import { AppEnv } from '../types'
+
+export async function publicReadHandler(context: Context<AppEnv>) {
+  const seedSlug = context.req.param('seed') ?? ''
+  const seed = context.get('getSeed')(seedSlug)
+  if (!seed) {
+    const available = context.get('seedRegistry').all().map(s => s.slug).join(', ')
+    return publicProblem(context, {
+      type: 'seed-not-found',
+      title: 'Seed Not Found',
+      status: 404,
+      detail: `The content type '${seedSlug}' does not exist. Available types: ${available}.`,
+    })
+  }
+
+  const access = checkPublicOperation(seed, 'read')
+  if (!access.ok) {
+    return publicProblem(context, { type: 'operation-not-allowed', title: access.error.error, status: 403, detail: access.error.message })
+  }
+
+  const edgeCache = resolveEdgeCache(context)
+  const cacheKey = context.req.raw
+  if (edgeCache) {
+    const hit = await edgeCache.cache.match(cacheKey)
+    if (hit) return hit
+  }
+
+  const query = context.req.query()
+  const id = cleanStr(query.id)
+  const slug = cleanStr(query.slug)
+  const publishedOnly = context.env.PUBLIC_PUBLISHED_ONLY !== 'false'
+  const repository = context.get('repository')
+
+  try {
+    if (id || slug) {
+      const result = await readSingleEntry({ seed, seedSlug, repository, id, slug, publishedOnly, fieldsParam: query.fields })
+      if (!result.ok) {
+        return publicProblem(context, { type: 'entry-not-found', title: 'Not Found', status: 404, detail: result.detail })
+      }
+      return withCachedResponse(edgeCache, cacheKey, context.json({ data: result.data, meta: result.meta }, 200))
+    }
+
+    const result = await readListEntries({ seed, seedSlug, repository, query, publishedOnly })
+    return withCachedResponse(edgeCache, cacheKey, context.json(result, 200))
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('Invalid filter:')) {
+      return publicProblem(context, { type: 'invalid-filter', title: 'Bad Request', status: 400, detail: error.message })
+    }
+    console.error('Public read error:', error)
+    return publicProblem(context, { type: 'internal-server-error', title: 'Internal Server Error', status: 500, detail: internalErrorDetail(context.env, error) })
+  }
+}

package/src/public/public-routes.ts

@@ -13,7 +13,7 @@ publicApp.get('/health', (c) => {
 /** Returns the public-facing schema: only seeds with public read or post enabled. */
 publicApp.get('/schema', (c) => {
   const registry = c.get('seedRegistry')
-  const publicSeeds = Object.values(registry)
+  const publicSeeds = registry.all()
     .filter(seed => seed.allowPublicRead === true || seed.allowPublicPost === true || seed.allowPublicEdit === true)
     .map(seed => ({
       slug: seed.slug,
@@ -39,7 +39,7 @@ publicApp.get('/schema', (c) => {
 /** HTML render of the public schema for quick browser inspection. */
 publicApp.get('/schema.html', (c) => {
   const registry = c.get('seedRegistry')
-  const publicSeeds = Object.values(registry)
+  const publicSeeds = registry.all()
     .filter(seed => seed.allowPublicRead === true || seed.allowPublicPost === true || seed.allowPublicEdit === true)
 
   const seedHtml = publicSeeds.map(seed => {

package/src/public/query-builder.test.ts

@@ -0,0 +1,220 @@
+import { describe, it, expect } from 'vitest'
+import {
+  parsePublicFilter,
+  toEngineFilters,
+  parsePublicPagination,
+  parseLatestCount,
+} from './query-builder'
+import type { Seed } from '@beechcms/core'
+
+const SEED = {
+  slug: 'posts',
+  displayNameAlias: 'title',
+  branches: [
+    { id: 'br_01', alias: 'title', type: 'text' },
+    { id: 'br_02', alias: 'count', type: 'number' },
+    { id: 'br_03', alias: 'active', type: 'boolean' },
+    { id: 'br_04', alias: 'published_at', type: 'date' },
+    { id: 'br_05', alias: 'tags', type: 'tags' },
+    { id: 'br_06', alias: 'body', type: 'richtext' },
+    { id: 'br_07', alias: 'attachment', type: 'file' },
+    { id: 'br_08', alias: 'meta', type: 'json' },
+  ],
+} as unknown as Seed
+
+// ─── parsePublicFilter ────────────────────────────────────────────────────────
+
+describe('parsePublicFilter', () => {
+  it('returns null for undefined input', () => {
+    expect(parsePublicFilter(undefined)).toBeNull()
+  })
+
+  it('returns null for empty string', () => {
+    expect(parsePublicFilter('')).toBeNull()
+  })
+
+  it('parses a valid filter with explicit AND logic', () => {
+    const raw = JSON.stringify({ logic: 'AND', where: [{ field: 'title', op: 'eq', value: 'Hello' }] })
+    const result = parsePublicFilter(raw)!
+    expect(result.logic).toBe('AND')
+    expect(result.where).toHaveLength(1)
+    expect(result.where[0]).toEqual({ field: 'title', op: 'eq', value: 'Hello' })
+  })
+
+  it('defaults logic to AND when omitted', () => {
+    const raw = JSON.stringify({ where: [{ field: 'title', op: 'contains', value: 'x' }] })
+    expect(parsePublicFilter(raw)!.logic).toBe('AND')
+  })
+
+  it('accepts case-insensitive logic value', () => {
+    const raw = JSON.stringify({ logic: 'or', where: [] })
+    expect(parsePublicFilter(raw)!.logic).toBe('OR')
+  })
+
+  it('throws for malformed JSON', () => {
+    expect(() => parsePublicFilter('{not-json')).toThrow('malformed JSON')
+  })
+
+  it('throws when parsed value is not an object', () => {
+    expect(() => parsePublicFilter('"a string"')).toThrow('object expected')
+  })
+
+  it('throws for an invalid logic value', () => {
+    const raw = JSON.stringify({ logic: 'BOTH', where: [] })
+    expect(() => parsePublicFilter(raw)).toThrow("'AND' or 'OR'")
+  })
+
+  it('throws for an unknown operator in a where condition', () => {
+    const raw = JSON.stringify({ where: [{ field: 'title', op: 'like', value: 'x' }] })
+    expect(() => parsePublicFilter(raw)).toThrow("unknown operator 'like'")
+  })
+
+  it('throws when where is not an array', () => {
+    const raw = JSON.stringify({ where: { field: 'title', op: 'eq' } })
+    expect(() => parsePublicFilter(raw)).toThrow("'where' must be an array")
+  })
+
+  it('filters out null conditions from where (missing field/op)', () => {
+    const raw = JSON.stringify({ where: [null, { field: 'title', op: 'eq', value: 'x' }] })
+    const result = parsePublicFilter(raw)!
+    expect(result.where).toHaveLength(1)
+  })
+
+  it('accepts all valid operators without throwing', () => {
+    const operators = ['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']
+    for (const op of operators) {
+      const raw = JSON.stringify({ where: [{ field: 'title', op, value: 'x' }] })
+      expect(() => parsePublicFilter(raw)).not.toThrow()
+    }
+  })
+})
+
+// ─── toEngineFilters ──────────────────────────────────────────────────────────
+
+describe('toEngineFilters', () => {
+  it('returns [] for null filter', () => {
+    expect(toEngineFilters(SEED, null)).toEqual([])
+  })
+
+  it('returns [] when where array is empty', () => {
+    expect(toEngineFilters(SEED, { where: [], logic: 'AND' })).toEqual([])
+  })
+
+  it('maps text branch to FilterType "text"', () => {
+    const result = toEngineFilters(SEED, { where: [{ field: 'title', op: 'eq', value: 'Hi' }], logic: 'AND' })
+    expect(result[0].type).toBe('text')
+  })
+
+  it('maps number branch to FilterType "number"', () => {
+    const result = toEngineFilters(SEED, { where: [{ field: 'count', op: 'gt', value: 5 }], logic: 'AND' })
+    expect(result[0].type).toBe('number')
+  })
+
+  it('maps boolean branch to FilterType "boolean"', () => {
+    const result = toEngineFilters(SEED, { where: [{ field: 'active', op: 'eq', value: true }], logic: 'AND' })
+    expect(result[0].type).toBe('boolean')
+  })
+
+  it('maps date branch to FilterType "date"', () => {
+    const result = toEngineFilters(SEED, { where: [{ field: 'published_at', op: 'gt', value: '2024-01-01' }], logic: 'AND' })
+    expect(result[0].type).toBe('date')
+  })
+
+  it('maps tags branch to FilterType "tags"', () => {
+    const result = toEngineFilters(SEED, { where: [{ field: 'tags', op: 'has_tag', value: 'news' }], logic: 'AND' })
+    expect(result[0].type).toBe('tags')
+  })
+
+  it('maps richtext branch to FilterType "text"', () => {
+    const result = toEngineFilters(SEED, { where: [{ field: 'body', op: 'contains', value: 'x' }], logic: 'AND' })
+    expect(result[0].type).toBe('text')
+  })
+
+  it('maps file branch to FilterType "text"', () => {
+    const result = toEngineFilters(SEED, { where: [{ field: 'attachment', op: 'contains', value: 'url' }], logic: 'AND' })
+    expect(result[0].type).toBe('text')
+  })
+
+  it('maps json branch to FilterType "json"', () => {
+    const result = toEngineFilters(SEED, { where: [{ field: 'meta', op: 'eq', value: '{}' }], logic: 'AND' })
+    expect(result[0].type).toBe('json')
+  })
+
+  it('maps system columns (id, slug, status) to FilterType "system"', () => {
+    for (const field of ['id', 'slug', 'status', 'created_at', 'updated_at']) {
+      const result = toEngineFilters(SEED, { where: [{ field, op: 'eq', value: 'x' }], logic: 'AND' })
+      expect(result[0].type).toBe('system')
+    }
+  })
+
+  it('maps unknown fields to FilterType "text"', () => {
+    const result = toEngineFilters(SEED, { where: [{ field: 'ghost_field', op: 'eq', value: 'x' }], logic: 'AND' })
+    expect(result[0].type).toBe('text')
+  })
+
+  it('produces one FilterGroup per condition', () => {
+    const filter = {
+      where: [
+        { field: 'title', op: 'eq' as const, value: 'A' },
+        { field: 'count', op: 'gt' as const, value: 5 },
+      ],
+      logic: 'AND' as const,
+    }
+    expect(toEngineFilters(SEED, filter)).toHaveLength(2)
+  })
+
+  it('includes column and conditions in each FilterGroup', () => {
+    const filter = { where: [{ field: 'title', op: 'contains' as const, value: 'hi' }], logic: 'AND' as const }
+    const [group] = toEngineFilters(SEED, filter)
+    expect(group.column).toBe('title')
+    expect(group.conditions[0].op).toBe('contains')
+    expect(group.conditions[0].value).toBe('hi')
+  })
+})
+
+// ─── parsePublicPagination ────────────────────────────────────────────────────
+
+describe('parsePublicPagination', () => {
+  it('defaults to page=1 and limit=25 when input is empty', () => {
+    expect(parsePublicPagination({})).toEqual({ page: 1, limit: 25 })
+  })
+
+  it('parses valid page and limit values', () => {
+    expect(parsePublicPagination({ page: '3', limit: '10' })).toEqual({ page: 3, limit: 10 })
+  })
+
+  it('clamps limit to a maximum of 100', () => {
+    expect(parsePublicPagination({ limit: '500' }).limit).toBe(100)
+  })
+
+  it('uses default for invalid (non-numeric) input', () => {
+    expect(parsePublicPagination({ page: 'abc', limit: 'xyz' })).toEqual({ page: 1, limit: 25 })
+  })
+})
+
+// ─── parseLatestCount ─────────────────────────────────────────────────────────
+
+describe('parseLatestCount', () => {
+  it('returns 10 for undefined', () => {
+    expect(parseLatestCount(undefined)).toBe(10)
+  })
+
+  it('parses a valid integer string', () => {
+    expect(parseLatestCount('5')).toBe(5)
+  })
+
+  it('clamps to 1 for values below minimum', () => {
+    expect(parseLatestCount('0')).toBe(1)
+    expect(parseLatestCount('-5')).toBe(1)
+  })
+
+  it('clamps to 100 for values above maximum', () => {
+    expect(parseLatestCount('200')).toBe(100)
+  })
+
+  it('returns 10 for non-numeric input', () => {
+    expect(parseLatestCount('abc')).toBe(10)
+  })
+})

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

@@ -1,34 +1,22 @@
 import type { Context, Next } from 'hono'
+import type { AppEnv } from '../types'
 import { publicProblem } from './problem-details'
-
-type PublicBindings = {
-  PUBLIC_READ_RATE_LIMITER?: RateLimit
-  PUBLIC_WRITE_RATE_LIMITER?: RateLimit
-}
+import { getClientIp } from '../shared/request-utils'
 
 function isReadMethod(method: string): boolean {
   return method === 'GET' || method === 'HEAD' || method === 'OPTIONS'
 }
 
-function getClientIp(headers: Headers): string {
-  return headers.get('cf-connecting-ip') ?? 'unknown'
-}
-
 export function publicRateLimitMiddleware() {
-  return async (c: Context, next: Next): Promise<Response | void> => {
-    const env = c.env as PublicBindings
+  return async (c: Context<AppEnv>, next: Next): Promise<Response | void> => {
     const readMethod = isReadMethod(c.req.method)
-    const limiter = readMethod ? env.PUBLIC_READ_RATE_LIMITER : env.PUBLIC_WRITE_RATE_LIMITER
-    if (!limiter) {
-      await next()
-      return
-    }
+    const limiterName = readMethod ? ('publicApiRead' as const) : ('publicApiWrite' as const)
 
     const seed = c.req.param('seed') ?? 'no-seed'
-    const key = `${getClientIp(c.req.raw.headers)}:${seed}:${readMethod ? 'read' : 'write'}`
-    const { success } = await limiter.limit({ key })
+    const key = `${getClientIp(c.req)}:${seed}:${limiterName}`
+    const result = await c.get('rateLimiters').getLimiter(limiterName).checkLimit(key)
 
-    if (!success) {
+    if (!result.isAllowed) {
       return publicProblem(c, {
         type: 'rate-limit-exceeded',
         title: 'Too Many Requests',

package/src/public/read-list.ts

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

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