@beechcms/api 0.4.0-preview.9 → 0.4.1

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/query-builder.ts

@@ -1,241 +1,152 @@
-import type { Seed } from '@beechcms/core'
-import { parsePositiveInt } from '../shared/query-utils'
-
-export type PublicQueryInput = {
-  page?: string
-  limit?: string
-  latest?: string
-}
-
-type PublicFilterLogic = 'AND' | 'OR'
-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'
-
-type PublicFilterCondition = {
-  field: string
-  op: PublicFilterOperator
-  value?: unknown
-}
-
-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',
-])
-
-const SYSTEM_COLUMNS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at'])
-
-function asString(value: unknown): string | null {
-  return typeof value === 'string' && value.trim() ? value.trim() : null
-}
-
-/**
- * Risolve il nome colonna SQL per un campo.
- * In v0.4.0 il nome colonna = branch.alias (nessun json_extract).
- */
-function resolveFieldExpression(
-  seed: Seed | null,
-  field: string
-): { expr: string; fieldType: string } | null {
-  if (SYSTEM_COLUMNS.has(field)) {
-    const type = field === 'created_at' || field === 'updated_at' ? 'number' : 'text'
-    return { expr: field, fieldType: type }
-  }
-  const branch = seed?.branches.find((b) => b.alias === field)
-  if (!branch) return null
-  return { expr: branch.alias, fieldType: branch.type }
-}
-
-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 }
-}
-
-function ensureValueArray(value: unknown, op: PublicFilterOperator, field: string): unknown[] {
-  if (!Array.isArray(value) || value.length === 0) {
-    throw new TypeError(`Invalid filter: operator '${op}' for field '${field}' requires a non-empty array`)
-  }
-  return value
-}
-
-function buildTextOperation(
-  op: PublicFilterOperator,
-  expr: string,
-  field: string,
-  value: unknown
-): { clause: string; bindings: Array<string | number> } {
-  const str = asString(value)
-  if (!str) throw new TypeError(`Invalid filter: operator '${op}' for field '${field}' requires a string value`)
-  if (op === 'contains')     return { clause: `LOWER(CAST(${expr} AS TEXT)) LIKE LOWER(?)`, bindings: [`%${str}%`] }
-  if (op === 'not_contains') return { clause: `LOWER(CAST(${expr} AS TEXT)) NOT LIKE LOWER(?)`, bindings: [`%${str}%`] }
-  if (op === 'starts_with')  return { clause: `LOWER(CAST(${expr} AS TEXT)) LIKE LOWER(?)`, bindings: [`${str}%`] }
-  return { clause: `LOWER(CAST(${expr} AS TEXT)) LIKE LOWER(?)`, bindings: [`%${str}`] }
-}
-
-function buildSetOperation(
-  op: PublicFilterOperator,
-  expr: string,
-  field: string,
-  value: unknown
-): { clause: string; bindings: Array<string | number> } {
-  const values = ensureValueArray(value, op, field)
-  const placeholders = values.map(() => '?').join(',')
-  return {
-    clause: `${expr} ${op === 'in' ? 'IN' : 'NOT IN'} (${placeholders})`,
-    bindings: values as Array<string | number>,
-  }
-}
-
-function buildTagOperation(
-  op: PublicFilterOperator,
-  expr: string,
-  field: string,
-  value: unknown
-): { clause: string; bindings: Array<string | number> } {
-  const tags = op === 'has_tag' ? [value] : ensureValueArray(value, op, field)
-  const cleaned = tags.map((item) => asString(item)).filter((item): item is string => item !== null)
-  if (cleaned.length === 0) {
-    throw new TypeError(`Invalid filter: operator '${op}' for field '${field}' requires tag string values`)
-  }
-  if (op === 'has_tag' || op === 'has_any_tag') {
-    const placeholders = cleaned.map(() => '?').join(',')
-    return {
-      clause: `EXISTS (SELECT 1 FROM json_each(${expr}) je WHERE CAST(je.value AS TEXT) IN (${placeholders}))`,
-      bindings: cleaned,
-    }
-  }
-  const allParts = cleaned.map(() => `EXISTS (SELECT 1 FROM json_each(${expr}) je WHERE CAST(je.value AS TEXT) = ?)`)
-  return { clause: allParts.join(' AND '), bindings: cleaned }
-}
-
-function buildConditionClause(
-  condition: PublicFilterCondition,
-  seed: Seed | null
-): { clause: string; bindings: Array<string | number> } | null {
-  const fieldMeta = resolveFieldExpression(seed, condition.field)
-  if (!fieldMeta) return null
-  const { expr, fieldType } = fieldMeta
-  const { op, value, field } = condition
-
-  if (op === 'is_empty')     return { clause: `(${expr} IS NULL OR TRIM(CAST(${expr} AS TEXT)) = '')`, bindings: [] }
-  if (op === 'is_not_empty') return { clause: `(${expr} IS NOT NULL AND TRIM(CAST(${expr} AS TEXT)) <> '')`, bindings: [] }
-  if (op === 'contains' || op === 'not_contains' || op === 'starts_with' || op === 'ends_with') {
-    return buildTextOperation(op, expr, field, value)
-  }
-  if (op === 'in' || op === 'not_in') return buildSetOperation(op, expr, field, value)
-  if (op === 'has_tag' || op === 'has_any_tag' || op === 'has_all_tags') {
-    if (fieldType !== 'json') throw new TypeError(`Invalid filter: operator '${op}' requires a json field`)
-    return buildTagOperation(op, expr, field, value)
-  }
-
-  if (op === 'eq' || op === 'neq') {
-    if (typeof value === 'boolean') {
-      return { clause: `${expr} ${op === 'eq' ? '=' : '!='} ?`, bindings: [value ? 1 : 0] }
-    }
-    if (typeof value === 'number' && !Number.isNaN(value)) {
-      return { clause: `${expr} ${op === 'eq' ? '=' : '!='} ?`, bindings: [value] }
-    }
-    const textValue = asString(value)
-    if (!textValue) throw new TypeError(`Invalid filter: operator '${op}' for field '${field}' requires a scalar value`)
-    return {
-      clause: `LOWER(TRIM(CAST(${expr} AS TEXT))) ${op === 'eq' ? '=' : '!='} LOWER(TRIM(?))`,
-      bindings: [textValue],
-    }
-  }
-
-  const numberValue = typeof value === 'number' && !Number.isNaN(value) ? value : null
-  const textValue = asString(value)
-  const mathOp = op === 'gt' ? '>' : op === 'gte' ? '>=' : op === 'lt' ? '<' : op === 'lte' ? '<=' : null
-  if (!mathOp) throw new TypeError(`Invalid filter: operator '${op}' is not supported`)
-  if ((fieldType === 'number' || field === 'created_at' || field === 'updated_at') && numberValue !== null) {
-    return { clause: `${expr} ${mathOp} ?`, bindings: [numberValue] }
-  }
-  if (textValue) return { clause: `CAST(${expr} AS TEXT) ${mathOp} ?`, bindings: [textValue] }
-  throw new TypeError(`Invalid filter: operator '${op}' for field '${field}' requires a compatible value`)
-}
-
-export function buildPublicFilterWhereClause(
-  seed: Seed | null,
-  parsedFilter: ParsedPublicFilter | null
-): { clause: string; bindings: Array<string | number> } {
-  if (!parsedFilter || parsedFilter.where.length === 0) return { clause: '', bindings: [] }
-  const clauses: string[] = []
-  const bindings: Array<string | number> = []
-  for (const condition of parsedFilter.where) {
-    const built = buildConditionClause(condition, seed)
-    if (!built) continue
-    clauses.push(`(${built.clause})`)
-    bindings.push(...built.bindings)
-  }
-  if (clauses.length === 0) return { clause: '', bindings: [] }
-  return { clause: clauses.join(` ${parsedFilter.logic} `), bindings }
-}
-
-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
-}
+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
+}