@beechcms/api 0.4.3 → 0.6.0-preview.1

package/src/features/backrefs/__tests__/backrefs.handler.test.ts

@@ -0,0 +1,359 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { Hono } from 'hono'
+import type { BackrefMap } from '@beechcms/core'
+import { backrefsApp } from '../backrefs.handler'
+
+// ---------------------------------------------------------------------------
+// Seed fixtures
+// ---------------------------------------------------------------------------
+
+const teamSeed = {
+  slug: 'team',
+  label: 'Team Member',
+  labelPlural: 'Team Members',
+  displayNameAlias: 'name',
+  branches: [
+    { id: 'br_01', alias: 'name', label: 'Name', type: 'text' as const },
+  ],
+  allowPublicRead: false,
+}
+
+const articlesSeed = {
+  slug: 'articles',
+  label: 'Article',
+  labelPlural: 'Articles',
+  displayNameAlias: 'title',
+  branches: [
+    { id: 'br_01', alias: 'title', label: 'Title', type: 'text' as const },
+    { id: 'br_02', alias: 'author_id', label: 'Author', type: 'relation' as const, targetSeed: 'team' },
+  ],
+  allowPublicRead: false,
+}
+
+const tagsSeed = {
+  slug: 'tags',
+  label: 'Tag',
+  labelPlural: 'Tags',
+  displayNameAlias: 'name',
+  branches: [
+    { id: 'br_01', alias: 'name', label: 'Name', type: 'text' as const },
+  ],
+  allowPublicRead: false,
+}
+
+const articleTagsSeed = {
+  slug: 'articles',
+  label: 'Article',
+  labelPlural: 'Articles',
+  displayNameAlias: 'title',
+  branches: [
+    { id: 'br_01', alias: 'title', label: 'Title', type: 'text' as const },
+    { id: 'br_02', alias: 'tags', label: 'Tags', type: 'relation' as const, targetSeed: 'tags', multiple: true },
+  ],
+  allowPublicRead: false,
+}
+
+// ---------------------------------------------------------------------------
+// D1 mock helpers
+// ---------------------------------------------------------------------------
+
+function makeD1First<T>(result: T | null) {
+  return vi.fn().mockResolvedValue(result)
+}
+
+function makeD1All<T>(results: T[]) {
+  return vi.fn().mockResolvedValue({ results })
+}
+
+interface D1PrepareStub {
+  firstResult?: unknown
+  allResults?: unknown[]
+}
+
+function makeD1(stubs: D1PrepareStub[] = []) {
+  let callCount = 0
+  return {
+    prepare: vi.fn().mockImplementation(() => {
+      const stub = stubs[callCount++] ?? { firstResult: null, allResults: [] }
+      return {
+        bind: vi.fn().mockReturnThis(),
+        first: makeD1First(stub.firstResult ?? null),
+        all: makeD1All((stub.allResults ?? []) as unknown[]),
+      }
+    }),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// App builder
+// ---------------------------------------------------------------------------
+
+function buildApp({
+  db,
+  backrefMap,
+  getSeed,
+}: {
+  db: ReturnType<typeof makeD1>
+  backrefMap: BackrefMap
+  getSeed: (slug: string) => unknown
+}) {
+  const app = new Hono()
+  app.use('*', async (c, next) => {
+    ;(c as any).env = { DB: db }
+    ;(c as any).set('backrefMap', backrefMap)
+    ;(c as any).set('getSeed', getSeed)
+    await next()
+  })
+  app.route('/', backrefsApp)
+  return app
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('GET /:targetSlug/:targetId/backrefs', () => {
+  describe('404 cases', () => {
+    it('returns 404 when target slug is unknown', async () => {
+      const db = makeD1()
+      const app = buildApp({
+        db,
+        backrefMap: new Map(),
+        getSeed: () => null,
+      })
+
+      const res = await app.request('/unknown-slug/id-1/backrefs')
+      expect(res.status).toBe(404)
+      const body = await res.json() as { type: string }
+      expect(body.type).toContain('not-found')
+    })
+
+    it('returns 404 when target id does not exist in DB', async () => {
+      const db = makeD1([{ firstResult: null }])
+      const app = buildApp({
+        db,
+        backrefMap: new Map(),
+        getSeed: (s) => s === 'team' ? teamSeed : null,
+      })
+
+      const res = await app.request('/team/nonexistent-id/backrefs')
+      expect(res.status).toBe(404)
+    })
+  })
+
+  describe('no inbound relations', () => {
+    it('returns empty groups when backrefMap has no entry for target', async () => {
+      const db = makeD1([{ firstResult: { id: 'ada-1' } }])
+      const app = buildApp({
+        db,
+        backrefMap: new Map(),
+        getSeed: (s) => s === 'team' ? teamSeed : null,
+      })
+
+      const res = await app.request('/team/ada-1/backrefs')
+      expect(res.status).toBe(200)
+      const body = await res.json() as { groups: unknown[] }
+      expect(body.groups).toHaveLength(0)
+    })
+  })
+
+  describe('single-value source with 5 referencing rows', () => {
+    it('preview: returns 3 items, total=5, restricts=false', async () => {
+      const backrefMap: BackrefMap = new Map([
+        ['team', [{
+          sourceSlug: 'articles',
+          branchAlias: 'author_id',
+          branchLabel: 'Author',
+          relationship: 'single',
+          restricts: false,
+        }]],
+      ])
+
+      const previewItems = Array.from({ length: 3 }, (_, i) => ({
+        id: `art-${i + 1}`,
+        displayName: `Article ${i + 1}`,
+        status: 'published',
+        updated_at: 1000 + i,
+      }))
+
+      // prepare calls: 1) exists check, 2) rows query, 3) count query
+      const db = makeD1([
+        { firstResult: { id: 'ada-1' } },            // exists
+        { allResults: previewItems },                  // rows
+        { firstResult: { total: 5 } },                // count
+      ])
+
+      const app = buildApp({
+        db,
+        backrefMap,
+        getSeed: (s) => {
+          if (s === 'team') return teamSeed
+          if (s === 'articles') return articlesSeed
+          return null
+        },
+      })
+
+      const res = await app.request('/team/ada-1/backrefs')
+      expect(res.status).toBe(200)
+      const body = await res.json() as { groups: any[] }
+      expect(body.groups).toHaveLength(1)
+      const g = body.groups[0]
+      expect(g.total).toBe(5)
+      expect(g.items).toHaveLength(3)
+      expect(g.restricts).toBe(false)
+      expect(g.relationship).toBe('single')
+    })
+  })
+
+  describe('multi-relation source with 12 referencing rows', () => {
+    it('preview: returns 3 items, total=12', async () => {
+      const backrefMap: BackrefMap = new Map([
+        ['tags', [{
+          sourceSlug: 'articles',
+          branchAlias: 'tags',
+          branchLabel: 'Tags',
+          relationship: 'multi',
+          restricts: false,
+        }]],
+      ])
+
+      const previewItems = Array.from({ length: 3 }, (_, i) => ({
+        id: `art-${i}`,
+        displayName: `Article ${i}`,
+        status: 'published',
+        updated_at: 1000,
+      }))
+
+      const db = makeD1([
+        { firstResult: { id: 'tag-1' } },   // exists
+        { allResults: previewItems },          // rows
+        { firstResult: { total: 12 } },       // count
+      ])
+
+      const app = buildApp({
+        db,
+        backrefMap,
+        getSeed: (s) => {
+          if (s === 'tags') return tagsSeed
+          if (s === 'articles') return articleTagsSeed
+          return null
+        },
+      })
+
+      const res = await app.request('/tags/tag-1/backrefs')
+      expect(res.status).toBe(200)
+      const body = await res.json() as { groups: any[] }
+      const g = body.groups[0]
+      expect(g.total).toBe(12)
+      expect(g.items).toHaveLength(3)
+      expect(g.relationship).toBe('multi')
+    })
+  })
+
+  describe('paginated ?group= request', () => {
+    it('page=2&limit=4 returns correct offset (rows 5–8)', async () => {
+      const backrefMap: BackrefMap = new Map([
+        ['team', [{
+          sourceSlug: 'articles',
+          branchAlias: 'author_id',
+          branchLabel: 'Author',
+          relationship: 'single',
+          restricts: false,
+        }]],
+      ])
+
+      const page2Items = Array.from({ length: 4 }, (_, i) => ({
+        id: `art-${i + 5}`,
+        displayName: `Article ${i + 5}`,
+        status: 'published',
+        updated_at: 1000,
+      }))
+
+      const db = makeD1([
+        { firstResult: { id: 'ada-1' } },  // exists
+        { allResults: page2Items },          // rows (page 2, limit 4 → offset 4)
+        { firstResult: { total: 12 } },      // count
+      ])
+
+      const app = buildApp({
+        db,
+        backrefMap,
+        getSeed: (s) => {
+          if (s === 'team') return teamSeed
+          if (s === 'articles') return articlesSeed
+          return null
+        },
+      })
+
+      const res = await app.request('/team/ada-1/backrefs?group=articles:author_id&page=2&limit=4')
+      expect(res.status).toBe(200)
+      const body = await res.json() as { groups: any[] }
+      expect(body.groups).toHaveLength(1)
+      const g = body.groups[0]
+      expect(g.items).toHaveLength(4)
+      expect(g.items[0].id).toBe('art-5')
+    })
+
+    it('returns 404 for unknown group key', async () => {
+      const backrefMap: BackrefMap = new Map([
+        ['team', [{
+          sourceSlug: 'articles',
+          branchAlias: 'author_id',
+          branchLabel: 'Author',
+          relationship: 'single',
+          restricts: false,
+        }]],
+      ])
+
+      const db = makeD1([{ firstResult: { id: 'ada-1' } }])
+
+      const app = buildApp({
+        db,
+        backrefMap,
+        getSeed: (s) => s === 'team' ? teamSeed : null,
+      })
+
+      const res = await app.request('/team/ada-1/backrefs?group=articles:unknown_field')
+      expect(res.status).toBe(404)
+    })
+  })
+
+  describe('restricts flag', () => {
+    it('exposes restricts=true when branch has onDelete RESTRICT', async () => {
+      const backrefMap: BackrefMap = new Map([
+        ['team', [{
+          sourceSlug: 'articles',
+          branchAlias: 'author_id',
+          branchLabel: 'Author',
+          relationship: 'single',
+          restricts: true,
+        }]],
+      ])
+
+      const db = makeD1([
+        { firstResult: { id: 'ada-1' } },
+        { allResults: [{ id: 'art-1', displayName: 'Art', status: 'published', updated_at: 1000 }] },
+        { firstResult: { total: 1 } },
+      ])
+
+      const app = buildApp({
+        db,
+        backrefMap,
+        getSeed: (s) => {
+          if (s === 'team') return teamSeed
+          if (s === 'articles') return articlesSeed
+          return null
+        },
+      })
+
+      const res = await app.request('/team/ada-1/backrefs')
+      expect(res.status).toBe(200)
+      const body = await res.json() as { groups: any[] }
+      expect(body.groups[0].restricts).toBe(true)
+    })
+  })
+})

package/src/features/backrefs/backrefs.handler.ts

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+/// <reference types="@cloudflare/workers-types" />
+import { Hono } from 'hono'
+import { resolvePolicies } from '@beechcms/core'
+import { publicProblem } from '../../public/problem-details'
+import type { AppEnv } from '../../types'
+import { D1BackrefRepository, type BackrefItem } from './d1-backref.repository'
+
+const PREVIEW_LIMIT = 3
+const DEFAULT_PAGE_LIMIT = 20
+const MAX_PAGE_LIMIT = 100
+
+export const backrefsApp = new Hono<AppEnv>()
+
+// ---------------------------------------------------------------------------
+// GET /content/:targetSlug/:targetId/backrefs
+// ---------------------------------------------------------------------------
+
+backrefsApp.get('/:targetSlug/:targetId/backrefs', async (c) => {
+  const targetSlug = c.req.param('targetSlug')
+  const targetId = c.req.param('targetId')
+  const groupParam = c.req.query('group')      // '<sourceSlug>:<branchAlias>'
+  const pageParam = c.req.query('page')
+  const limitParam = c.req.query('limit')
+
+  const getSeed = c.get('getSeed')
+  const backrefMap = c.get('backrefMap')
+  const backrefRepository = new D1BackrefRepository(c.env.DB)
+
+  // 1. Resolve target seed
+  const targetSeed = getSeed(targetSlug)
+  if (!targetSeed) {
+    return publicProblem(c, {
+      type: 'not-found',
+      title: 'Not Found',
+      status: 404,
+      detail: `Seed '${targetSlug}' does not exist`,
+    })
+  }
+
+  // 2. Verify targetId exists
+  const exists = await backrefRepository.entryExists(targetSlug, targetId)
+  if (!exists) {
+    return publicProblem(c, {
+      type: 'not-found',
+      title: 'Not Found',
+      status: 404,
+      detail: `Entry '${targetId}' not found in '${targetSlug}'`,
+    })
+  }
+
+  // 3. Get sources for this target
+  const sources = backrefMap.get(targetSlug)
+  if (!sources || sources.length === 0) {
+    return c.json({ groups: [] })
+  }
+
+  // 4. Pagination
+  const page = Math.max(1, Number.parseInt(pageParam ?? '1', 10) || 1)
+  const rawLimit = Number.parseInt(limitParam ?? String(DEFAULT_PAGE_LIMIT), 10) || DEFAULT_PAGE_LIMIT
+  const limit = Math.min(Math.max(1, rawLimit), MAX_PAGE_LIMIT)
+  const offset = (page - 1) * limit
+
+  // 5. Paginated single-group request
+  if (groupParam) {
+    const colonIdx = groupParam.indexOf(':')
+    if (colonIdx === -1) {
+      return publicProblem(c, {
+        type: 'bad-request',
+        title: 'Bad Request',
+        status: 400,
+        detail: `'group' must be '<sourceSlug>:<branchAlias>'`,
+      })
+    }
+    const sourceSlug = groupParam.slice(0, colonIdx)
+    const branchAlias = groupParam.slice(colonIdx + 1)
+
+    const source = sources.find(
+      s => s.sourceSlug === sourceSlug && s.branchAlias === branchAlias
+    )
+    if (!source) {
+      return publicProblem(c, {
+        type: 'not-found',
+        title: 'Not Found',
+        status: 404,
+        detail: `Back-ref group '${groupParam}' not found for target '${targetSlug}'`,
+      })
+    }
+
+    const sourceSeed = getSeed(sourceSlug)
+    if (!sourceSeed) {
+      return c.json({ groups: [] })
+    }
+
+    const { items, total } = await backrefRepository.queryGroup(source, sourceSeed, targetId, limit, offset)
+    const filteredItems = filterVisibility(items, sourceSeed)
+
+    return c.json({
+      groups: [{
+        sourceSlug: source.sourceSlug,
+        sourceLabel: sourceSeed.labelPlural ?? sourceSeed.label,
+        branchAlias: source.branchAlias,
+        branchLabel: source.branchLabel,
+        relationship: source.relationship,
+        restricts: source.restricts,
+        total,
+        items: filteredItems,
+      }],
+    })
+  }
+
+  // 6. Preview mode — all groups, PREVIEW_LIMIT each
+  const groupResults = await Promise.all(
+    sources.map(async (source) => {
+      const sourceSeed = getSeed(source.sourceSlug)
+      if (!sourceSeed) return null
+
+      const { items, total } = await backrefRepository.queryGroup(source, sourceSeed, targetId, PREVIEW_LIMIT, 0)
+      const filteredItems = filterVisibility(items, sourceSeed)
+
+      return {
+        sourceSlug: source.sourceSlug,
+        sourceLabel: sourceSeed.labelPlural ?? sourceSeed.label,
+        branchAlias: source.branchAlias,
+        branchLabel: source.branchLabel,
+        relationship: source.relationship,
+        restricts: source.restricts,
+        total,
+        items: filteredItems,
+      }
+    })
+  )
+
+  const groups = groupResults.filter(
+    (g): g is NonNullable<typeof g> => g !== null && g.total > 0
+  )
+
+  return c.json({ groups })
+})
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function filterVisibility(
+  items: BackrefItem[],
+  sourceSeed: import('@beechcms/core').Seed
+): BackrefItem[] {
+  const displayBranch = sourceSeed.branches.find(
+    b => b.alias === sourceSeed.displayNameAlias
+  )
+  if (!displayBranch) return items
+
+  const { visibility } = resolvePolicies(displayBranch)
+  if (visibility === 'hidden') {
+    return items.map(item => ({ ...item, displayName: null }))
+  }
+  if (visibility === 'masked') {
+    return items.map(item => ({
+      ...item,
+      displayName: item.displayName ? '••••••••' : null,
+    }))
+  }
+  return items
+}

package/src/features/backrefs/d1-backref.repository.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+/// <reference types="@cloudflare/workers-types" />
+import type { BackrefSource, Seed } from '@beechcms/core'
+
+export interface BackrefItem {
+  id: string
+  displayName: string | null
+  status: string
+  updated_at: number | null
+}
+
+export interface QueryGroupResult {
+  items: BackrefItem[]
+  total: number
+}
+
+export class D1BackrefRepository {
+  constructor(private readonly db: D1Database) {}
+
+  async entryExists(slug: string, id: string): Promise<boolean> {
+    const row = await this.db
+      .prepare(`SELECT id FROM content_${slug} WHERE id = ? LIMIT 1`)
+      .bind(id)
+      .first<{ id: string }>()
+    return row !== null
+  }
+
+  async queryGroup(
+    source: BackrefSource,
+    sourceSeed: Seed,
+    targetId: string,
+    limit: number,
+    offset: number,
+  ): Promise<QueryGroupResult> {
+    const displayCol = sourceSeed.displayNameAlias
+
+    if (source.relationship === 'single') {
+      const [rowsResult, countResult] = await Promise.all([
+        this.db
+          .prepare(
+            `SELECT id, status, updated_at, ${displayCol} AS displayName
+               FROM content_${source.sourceSlug}
+              WHERE ${source.branchAlias} = ?
+              ORDER BY updated_at DESC
+              LIMIT ? OFFSET ?`,
+          )
+          .bind(targetId, limit, offset)
+          .all<BackrefItem>(),
+        this.db
+          .prepare(
+            `SELECT COUNT(*) AS total FROM content_${source.sourceSlug} WHERE ${source.branchAlias} = ?`,
+          )
+          .bind(targetId)
+          .first<{ total: number }>(),
+      ])
+      return { items: rowsResult.results ?? [], total: countResult?.total ?? 0 }
+    }
+
+    const joinTable = `rel_${source.sourceSlug}_${source.branchAlias}`
+    const [rowsResult, countResult] = await Promise.all([
+      this.db
+        .prepare(
+          `SELECT c.id, c.status, c.updated_at, c.${displayCol} AS displayName
+             FROM content_${source.sourceSlug} c
+             JOIN ${joinTable} r ON r.parent_id = c.id
+            WHERE r.target_id = ?
+            ORDER BY c.updated_at DESC
+            LIMIT ? OFFSET ?`,
+        )
+        .bind(targetId, limit, offset)
+        .all<BackrefItem>(),
+      this.db
+        .prepare(
+          `SELECT COUNT(DISTINCT parent_id) AS total FROM ${joinTable} WHERE target_id = ?`,
+        )
+        .bind(targetId)
+        .first<{ total: number }>(),
+    ])
+    return { items: rowsResult.results ?? [], total: countResult?.total ?? 0 }
+  }
+}

package/src/features/backrefs/index.ts

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
+export { backrefsApp } from './backrefs.handler'

package/src/features/content/constants.ts

@@ -1,3 +1,7 @@
+// SPDX-License-Identifier: BUSL-1.1
+// Copyright (c) 2024–2026 Flavio De Musso. All rights reserved.
+// See LICENSE in the repository root for license terms.
+
 export const CONTENT_ERRORS = {
   INVALID_SLUG: 'Invalid slug',
   INVALID_SLUG_OR_ID: 'Invalid slug or id',
@@ -7,4 +11,6 @@ export const CONTENT_ERRORS = {
   DATABASE_ERROR: 'Database error',
   SLUG_CONFLICT: 'Slug already exists for this schema',
   SENSITIVE_FIELD_EDIT: 'Cannot edit sensitive fields',
+  BULK_SIZE_EXCEEDED: 'Cannot edit more than 500 entries at once',
+  FIELD_NOT_BULK_EDITABLE: 'Field cannot be bulk-edited',
 } as const