@beechcms/api 0.4.0-preview.10 → 0.4.0-preview.12

package/src/public/public-read.ts

@@ -1,31 +1,17 @@
-import { resolvePolicies } from '@beechcms/core'
+import { resolvePolicies, EntryNotFoundError } 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,
+  toEngineFilters,
 } 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>
-}
+import { AppEnv } from '../types'
 
 function buildSeedNotFoundMessage(seed: string, seedRegistry: Record<string, Seed>): string {
   const available = Object.keys(seedRegistry).join(', ')
@@ -33,10 +19,17 @@ function buildSeedNotFoundMessage(seed: string, seedRegistry: Record<string, See
 }
 
 /** Applica policy public/visibility per la Public API. */
-function applyPublicPolicies(aliasData: Record<string, unknown>, seed: Seed): Record<string, unknown> {
+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 = aliasData[branch.alias]
+    const value = data[branch.alias]
     const { public: isPublic, visibility } = resolvePolicies(branch)
     if (!isPublic) continue
     if (visibility === 'hidden') continue
@@ -49,22 +42,24 @@ function applyPublicPolicies(aliasData: Record<string, unknown>, seed: Seed): Re
   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,
-  }
+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 { ...base, ...aliasData }
+  
+  if (requestedFields.length === 0) return aliasData
+  
   const filteredData: Record<string, unknown> = {}
   for (const field of requestedFields) {
     if (field in aliasData) filteredData[field] = aliasData[field]
   }
-  return { ...base, ...filteredData }
+  
+  // 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(
@@ -82,74 +77,85 @@ function withCache(
   return response
 }
 
-function buildInternalErrorMessage(c: Context<{ Bindings: Bindings; Variables: Variables }>, err: unknown): string {
-  if (c.env.ENV !== 'production' && err instanceof Error) return err.message
+function buildInternalErrorMessage(context: Context<AppEnv>, error: unknown): string {
+  if (context.env.ENV !== 'production' && error instanceof Error) return error.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)
+export async function publicReadHandler(context: Context<AppEnv>) {
+  const seedSlug = context.req.param('seed') ?? ''
+  const seed = context.get('getSeed')(seedSlug)
   if (!seed) {
-    return publicProblem(c, {
-      type: 'seed-not-found', title: 'Seed Not Found', status: 404,
-      detail: buildSeedNotFoundMessage(seedSlug, c.get('seedRegistry')),
+    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(c, { type: 'operation-not-allowed', title: access.error.error, status: 403, detail: access.error.message })
+    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 = c.executionCtx as typeof executionCtx
+    executionCtx = context.executionCtx as typeof executionCtx
   } catch {}
 
-  const cacheKey = c.req.raw
+  const cacheKey = context.req.raw
   if (cache) {
     const hit = await cache.match(cacheKey)
     if (hit) return hit
   }
 
-  const query = c.req.query()
+  const query = context.req.query()
   const id = cleanStr(query.id)
-  const table = `content_${seedSlug}`
-  const publishedOnly = c.env.PUBLIC_PUBLISHED_ONLY !== 'false'
+  const slug = cleanStr(query.slug)
+  const publishedOnly = context.env.PUBLIC_PUBLISHED_ONLY !== 'false'
+  const repository = context.get('repository')
 
   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}'.` })
+    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
       }
-
-      return withCache(cache, executionCtx, cacheKey,
-        c.json({ data: toFlatPublicEntry(row, seed, query.fields), meta: buildPublicSingleMeta(seedSlug) }, 200)
-      )
     }
 
     const parsedFilter = parsePublicFilter(query.filter)
@@ -160,58 +166,51 @@ export async function publicReadHandler(c: Context<{ Bindings: Bindings; Variabl
     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 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 rows = rowsResult.results ?? []
-    const data = rows.map((row) => toFlatPublicEntry(row, seed, query.fields))
+    const data = items.map((item) => toFlatPublicEntry(item, seed, query.fields))
 
     if (latestMode) {
       return withCache(cache, executionCtx, cacheKey,
-        c.json({ data, meta: { total, returned: data.length, seed: seedSlug } }, 200)
+        context.json({ data, meta: { total, returned: data.length, seed: seedSlug } }, 200)
       )
     }
 
     return withCache(cache, executionCtx, cacheKey,
-      c.json({
+      context.json({
         data,
-        meta: buildPublicListMeta({ total, page: pagination.page, limit: effectiveLimit, returned: data.length, seed: seedSlug }),
+        meta: buildPublicListMeta({ 
+          total, 
+          page: pagination.page, 
+          limit: latestMode ? (latestCount ?? 10) : pagination.limit, 
+          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 })
+  } 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 })
     }
-    return publicProblem(c, { type: 'internal-server-error', title: 'Internal Server Error', status: 500, detail: buildInternalErrorMessage(c, err) })
+    console.error('Public read error:', error)
+    return publicProblem(context, { 
+      type: 'internal-server-error', 
+      title: 'Internal Server Error', 
+      status: 500, 
+      detail: buildInternalErrorMessage(context, error) 
+    })
   }
 }

package/src/public/query-builder.ts

@@ -1,4 +1,4 @@
-import type { Seed } from '@beechcms/core'
+import type { Seed, FilterGroup, FilterOperator, FilterType, BranchType } from '@beechcms/core'
 import { parsePositiveInt } from '../shared/query-utils'
 
 export type PublicQueryInput = {
@@ -7,8 +7,8 @@ export type PublicQueryInput = {
   latest?: string
 }
 
-type PublicFilterLogic = 'AND' | 'OR'
-type PublicFilterOperator =
+export type PublicFilterLogic = 'AND' | 'OR'
+export type PublicFilterOperator =
   | 'eq'
   | 'neq'
   | 'gt'
@@ -27,13 +27,13 @@ type PublicFilterOperator =
   | 'has_any_tag'
   | 'has_all_tags'
 
-type PublicFilterCondition = {
+export type PublicFilterCondition = {
   field: string
   op: PublicFilterOperator
   value?: unknown
 }
 
-type ParsedPublicFilter = {
+export type ParsedPublicFilter = {
   where: PublicFilterCondition[]
   logic: PublicFilterLogic
 }
@@ -45,29 +45,10 @@ const PUBLIC_FILTER_OPERATORS = new Set<PublicFilterOperator>([
   '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'")
@@ -105,124 +86,54 @@ export function parsePublicFilter(raw: string | undefined): ParsedPublicFilter |
   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}`] }
-}
+const SYSTEM_COLUMNS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at'])
 
-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 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'
   }
 }
 
-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`)
+/**
+ * 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 {
-      clause: `LOWER(TRIM(CAST(${expr} AS TEXT))) ${op === 'eq' ? '=' : '!='} LOWER(TRIM(?))`,
-      bindings: [textValue],
+      column: cond.field,
+      type,
+      conditions: [{
+        op: cond.op as FilterOperator,
+        value: cond.value as any
+      }]
     }
-  }
-
-  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 } {

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

@@ -0,0 +1,28 @@
+/// <reference types="@cloudflare/workers-types" />
+import { RepositoryError } from '@beechcms/core'
+
+/**
+ * Base class for D1-backed repositories.
+ * Handles the D1 instance and provides common database utilities and error mapping.
+ */
+export abstract class BaseD1Repository {
+  constructor(protected readonly db: D1Database) {}
+
+  /**
+   * Utility method to extract a table name for a given seed.
+   */
+  protected getTableName(slug: string, isDraft = false): string {
+    return isDraft ? `content_${slug}_drafts` : `content_${slug}`
+  }
+
+  /**
+   * Helper to map generic D1 errors to Beech RepositoryErrors.
+   * This centralizes error handling for all D1 repositories.
+   */
+  protected mapError(error: any, context: string): RepositoryError {
+    const message = error?.message || 'Unknown database error'
+    // In the future, we can add more specific SQLite error code checks here
+    // (e.g., checking for UNIQUE constraint via string matching or codes if available)
+    return new RepositoryError(`${context}: ${message}`, error)
+  }
+}