@beechcms/api 0.4.0-preview.9 → 0.4.1

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

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

package/src/public/response-builder.ts

@@ -1,26 +1,26 @@
-/**
- * Helper meta per risposta lista Public API.
- */
-export function buildPublicListMeta(input: {
-  total: number
-  page: number
-  limit: number
-  returned: number
-  seed: string
-}) {
-  return {
-    total: input.total,
-    page: input.page,
-    limit: input.limit,
-    returned: input.returned,
-    seed: input.seed,
-  }
-}
-
-/**
- * Helper meta per risposta singolo elemento Public API.
- */
-export function buildPublicSingleMeta(seed: string) {
-  return { seed }
-}
-
+/**
+ * Helper meta per risposta lista Public API.
+ */
+export function buildPublicListMeta(input: {
+  total: number
+  page: number
+  limit: number
+  returned: number
+  seed: string
+}) {
+  return {
+    total: input.total,
+    page: input.page,
+    limit: input.limit,
+    returned: input.returned,
+    seed: input.seed,
+  }
+}
+
+/**
+ * Helper meta per risposta singolo elemento Public API.
+ */
+export function buildPublicSingleMeta(seed: string) {
+  return { seed }
+}
+

package/src/public/sanitize.ts

@@ -1,65 +1,65 @@
-import { validateAndSanitizeSeedPayload } from '@beechcms/core'
-import type { Seed, ValidationDetail } from '@beechcms/core'
-
-type PublicSanitizeSuccess = {
-  ok: true
-  data: Record<string, unknown>
-}
-
-type PublicSanitizeFailure = {
-  ok: false
-  status: 400 | 422
-  code: 'validation_failed' | 'dangerous_content'
-  message: string
-  details?: ValidationDetail[]
-}
-
-export type PublicSanitizeResult = PublicSanitizeSuccess | PublicSanitizeFailure
-
-/**
- * Adapter Public API: usa la foundation del core e mappa errori nel formato sprint.
- */
-export function sanitizePublicPayload(
-  seed: Seed,
-  payload: Record<string, unknown>,
-  options: {
-    allowNull?: boolean
-    operation?: 'create' | 'update'
-    requireAtLeastOneValidField?: boolean
-    enforceRequiredFields?: boolean
-  } = {}
-): PublicSanitizeResult {
-  const operation = options.operation ?? 'create'
-  const result = validateAndSanitizeSeedPayload(seed, payload, {
-    allowNull: options.allowNull ?? false,
-    operation,
-    requireAtLeastOneValidField: options.requireAtLeastOneValidField ?? true,
-    enforceRequiredFields: options.enforceRequiredFields ?? true,
-  })
-
-  if (result.dangerousFields.length > 0) {
-    const field = result.dangerousFields[0]
-    return {
-      ok: false,
-      status: 422,
-      code: 'dangerous_content',
-      message: `Content rejected: dangerous markup detected in field '${field}'`,
-    }
-  }
-
-  if (result.details.length > 0) {
-    return {
-      ok: false,
-      status: 400,
-      code: 'validation_failed',
-      message: 'Validation failed',
-      details: result.details,
-    }
-  }
-
-  return {
-    ok: true,
-    data: result.data,
-  }
-}
-
+import { validateAndSanitizeSeedPayload } from '@beechcms/core'
+import type { Seed, ValidationDetail } from '@beechcms/core'
+
+type PublicSanitizeSuccess = {
+  ok: true
+  data: Record<string, unknown>
+}
+
+type PublicSanitizeFailure = {
+  ok: false
+  status: 400 | 422
+  code: 'validation_failed' | 'dangerous_content'
+  message: string
+  details?: ValidationDetail[]
+}
+
+export type PublicSanitizeResult = PublicSanitizeSuccess | PublicSanitizeFailure
+
+/**
+ * Public API Adapter: uses the core foundation and maps errors into the sprint format.
+ */
+export function sanitizePublicPayload(
+  seed: Seed,
+  payload: Record<string, unknown>,
+  options: {
+    allowNull?: boolean
+    operation?: 'create' | 'update'
+    requireAtLeastOneValidField?: boolean
+    enforceRequiredFields?: boolean
+  } = {}
+): PublicSanitizeResult {
+  const operation = options.operation ?? 'create'
+  const result = validateAndSanitizeSeedPayload(seed, payload, {
+    allowNull: options.allowNull ?? false,
+    operation,
+    requireAtLeastOneValidField: options.requireAtLeastOneValidField ?? true,
+    enforceRequiredFields: options.enforceRequiredFields ?? true,
+  })
+
+  if (result.dangerousFields.length > 0) {
+    const field = result.dangerousFields[0]
+    return {
+      ok: false,
+      status: 422,
+      code: 'dangerous_content',
+      message: `Content rejected: dangerous markup detected in field '${field}'`,
+    }
+  }
+
+  if (result.details.length > 0) {
+    return {
+      ok: false,
+      status: 400,
+      code: 'validation_failed',
+      message: 'Validation failed',
+      details: result.details,
+    }
+  }
+
+  return {
+    ok: true,
+    data: result.data,
+  }
+}
+

package/src/public/slug-utils.ts

@@ -1,14 +1,14 @@
-import { slugify, generateEntrySlug } from '@beechcms/core'
-
-/**
- * Converte stringa in slug URL-safe.
- * Logica spostata in @beechcms/core per consistenza tra Dashboard e API.
- */
-export { slugify }
-
-/**
- * Genera slug da title/name o fallback UUID-like.
- * Logica spostata in @beechcms/core per consistenza tra Dashboard e API.
- */
-export { generateEntrySlug }
-
+import { slugify, generateEntrySlug } from '@beechcms/core'
+
+/**
+ * Converts a string into a URL-safe slug.
+ * Logic moved to @beechcms/core for consistency between Dashboard and API.
+ */
+export { slugify }
+
+/**
+ * Generates a slug from a title/name or a UUID-like fallback.
+ * Logic moved to @beechcms/core for consistency between Dashboard and API.
+ */
+export { generateEntrySlug }
+

package/src/rate-limit/cloudflare-rate-limiter.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect, vi } from 'vitest'
+import { CloudflareRateLimiter } from './cloudflare-rate-limiter'
+
+describe('CloudflareRateLimiter', () => {
+  it('returns isAllowed: true when the Cloudflare binding grants the request', async () => {
+    const mockBinding = { limit: vi.fn().mockResolvedValue({ success: true }) }
+    const limiter = new CloudflareRateLimiter(mockBinding as any)
+    const result = await limiter.checkLimit('192.168.1.1:login')
+    expect(result.isAllowed).toBe(true)
+  })
+
+  it('returns isAllowed: false when the Cloudflare binding blocks the request', async () => {
+    const mockBinding = { limit: vi.fn().mockResolvedValue({ success: false }) }
+    const limiter = new CloudflareRateLimiter(mockBinding as any)
+    const result = await limiter.checkLimit('192.168.1.1:login')
+    expect(result.isAllowed).toBe(false)
+  })
+
+  it('forwards the exact key to the binding so per-key accounting is correct', async () => {
+    const mockBinding = { limit: vi.fn().mockResolvedValue({ success: true }) }
+    const limiter = new CloudflareRateLimiter(mockBinding as any)
+    const key = '10.0.0.1:some-seed:publicApiRead'
+    await limiter.checkLimit(key)
+    expect(mockBinding.limit).toHaveBeenCalledWith({ key })
+  })
+})

package/src/rate-limit/cloudflare-rate-limiter.ts

@@ -0,0 +1,11 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { IRateLimiter, RateLimitResult } from '@beechcms/core'
+
+export class CloudflareRateLimiter implements IRateLimiter {
+  constructor(private readonly binding: RateLimit) {}
+
+  async checkLimit(key: string): Promise<RateLimitResult> {
+    const { success } = await this.binding.limit({ key })
+    return { isAllowed: success }
+  }
+}

package/src/rate-limit/in-memory-rate-limiter.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from 'vitest'
+import { InMemoryRateLimiter } from './in-memory-rate-limiter'
+
+describe('InMemoryRateLimiter', () => {
+  it('allows requests up to the configured maximum hit count', async () => {
+    const limiter = new InMemoryRateLimiter(3)
+    expect((await limiter.checkLimit('key')).isAllowed).toBe(true)
+    expect((await limiter.checkLimit('key')).isAllowed).toBe(true)
+    expect((await limiter.checkLimit('key')).isAllowed).toBe(true)
+  })
+
+  it('blocks the very next request after maxAllowedHits is reached', async () => {
+    const limiter = new InMemoryRateLimiter(2)
+    await limiter.checkLimit('key')
+    await limiter.checkLimit('key')
+    expect((await limiter.checkLimit('key')).isAllowed).toBe(false)
+  })
+
+  it('tracks hit counts independently for each key', async () => {
+    const limiter = new InMemoryRateLimiter(1)
+    expect((await limiter.checkLimit('ip-a')).isAllowed).toBe(true)
+    expect((await limiter.checkLimit('ip-b')).isAllowed).toBe(true)
+    // Both keys exhausted independently
+    expect((await limiter.checkLimit('ip-a')).isAllowed).toBe(false)
+    expect((await limiter.checkLimit('ip-b')).isAllowed).toBe(false)
+  })
+
+  it('maxAllowedHits = 1 allows exactly one request before blocking', async () => {
+    const limiter = new InMemoryRateLimiter(1)
+    expect((await limiter.checkLimit('k')).isAllowed).toBe(true)
+    expect((await limiter.checkLimit('k')).isAllowed).toBe(false)
+  })
+})

package/src/rate-limit/in-memory-rate-limiter.ts

@@ -0,0 +1,13 @@
+import type { IRateLimiter, RateLimitResult } from '@beechcms/core'
+
+export class InMemoryRateLimiter implements IRateLimiter {
+  private readonly hitCounts = new Map<string, number>()
+
+  constructor(private readonly maxAllowedHits: number) {}
+
+  async checkLimit(key: string): Promise<RateLimitResult> {
+    const currentHits = (this.hitCounts.get(key) ?? 0) + 1
+    this.hitCounts.set(key, currentHits)
+    return { isAllowed: currentHits <= this.maxAllowedHits }
+  }
+}

package/src/rate-limit/no-op-rate-limiter.test.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest'
+import { NoOpRateLimiter } from './no-op-rate-limiter'
+
+describe('NoOpRateLimiter', () => {
+  it('always returns isAllowed: true regardless of the key', async () => {
+    const limiter = new NoOpRateLimiter()
+    for (let i = 0; i < 100; i++) {
+      expect((await limiter.checkLimit('any-key')).isAllowed).toBe(true)
+    }
+  })
+
+  it('allows all keys without accumulating state', async () => {
+    const limiter = new NoOpRateLimiter()
+    expect((await limiter.checkLimit('ip-a')).isAllowed).toBe(true)
+    expect((await limiter.checkLimit('ip-b')).isAllowed).toBe(true)
+    expect((await limiter.checkLimit('ip-a')).isAllowed).toBe(true)
+  })
+})

package/src/rate-limit/no-op-rate-limiter.ts

@@ -0,0 +1,7 @@
+import type { IRateLimiter, RateLimitResult } from '@beechcms/core'
+
+export class NoOpRateLimiter implements IRateLimiter {
+  async checkLimit(_key: string): Promise<RateLimitResult> {
+    return { isAllowed: true }
+  }
+}

package/src/search-utils.test.ts

@@ -0,0 +1,207 @@
+import { describe, it, expect } from 'vitest'
+import { encodeCursor, decodeCursor, buildFtsQuery, mapFtsRow } from './search-utils'
+import type { Seed } from '@beechcms/core'
+
+const TEXT_SEED = {
+  slug: 'articoli',
+  displayNameAlias: 'title',
+  branches: [
+    { id: 'br_01', alias: 'title', type: 'text', policies: { search: true } },
+  ],
+} as unknown as Seed
+
+const SECOND_SEED = {
+  slug: 'team',
+  displayNameAlias: 'name',
+  branches: [
+    { id: 'br_01', alias: 'name', type: 'text', policies: { search: true } },
+  ],
+} as unknown as Seed
+
+const NO_FTS_SEED = {
+  slug: 'prodotti',
+  displayNameAlias: 'nome',
+  branches: [
+    { id: 'br_01', alias: 'price', type: 'number' },
+  ],
+} as unknown as Seed
+
+// ─── encodeCursor / decodeCursor ─────────────────────────────────────────────
+
+describe('encodeCursor / decodeCursor', () => {
+  it('roundtrip preserves rank and entryId', () => {
+    const cursor = encodeCursor(-1.23456, 'entry-abc')
+    const decoded = decodeCursor(cursor)
+    expect(decoded?.rank).toBeCloseTo(-1.23456)
+    expect(decoded?.entryId).toBe('entry-abc')
+  })
+
+  it('entryId without colons roundtrips correctly (UUID-style IDs)', () => {
+    const entryId = 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+    const cursor = encodeCursor(-3.7, entryId)
+    const decoded = decodeCursor(cursor)
+    expect(decoded?.rank).toBeCloseTo(-3.7)
+    expect(decoded?.entryId).toBe(entryId)
+  })
+
+  it('returns null for invalid base64', () => {
+    expect(decodeCursor('!!!not-base64!!!')).toBeNull()
+  })
+
+  it('returns null when decoded string has no colon separator', () => {
+    expect(decodeCursor(btoa('noseparator'))).toBeNull()
+  })
+})
+
+// ─── buildFtsQuery ───────────────────────────────────────────────────────────
+
+describe('buildFtsQuery', () => {
+  it('returns empty-result query when no seed has a searchable FTS branch', () => {
+    const result = buildFtsQuery(
+      { q: 'hello', schemaSlug: null, status: null, limit: 20, cursor: null },
+      [NO_FTS_SEED],
+    )
+    expect(result.sql).toContain('WHERE 1=0')
+    expect(result.binds).toHaveLength(0)
+    expect(result.countSql).toContain('SELECT 0 as total')
+  })
+
+  it('throws EMPTY_QUERY when all terms are stripped or too short (single chars)', () => {
+    expect(() =>
+      buildFtsQuery({ q: 'a b', schemaSlug: null, status: null, limit: 20, cursor: null }, [TEXT_SEED]),
+    ).toThrow('EMPTY_QUERY')
+  })
+
+  it('generates a query referencing the seed FTS and content tables', () => {
+    const result = buildFtsQuery(
+      { q: 'hello', schemaSlug: null, status: null, limit: 20, cursor: null },
+      [TEXT_SEED],
+    )
+    expect(result.sql).toContain('fts_articoli')
+    expect(result.sql).toContain('content_articoli')
+    expect(result.sql).toContain('LIMIT ?')
+    expect(result.binds.at(-1)).toBe(21) // limit + 1 for has-more detection
+  })
+
+  it('UNION ALLs multiple seeds when no schemaSlug filter is set', () => {
+    const result = buildFtsQuery(
+      { q: 'test', schemaSlug: null, status: null, limit: 10, cursor: null },
+      [TEXT_SEED, SECOND_SEED],
+    )
+    expect(result.sql).toContain('UNION ALL')
+    expect(result.sql).toContain('fts_articoli')
+    expect(result.sql).toContain('fts_team')
+  })
+
+  it('limits query to the requested schemaSlug when provided', () => {
+    const result = buildFtsQuery(
+      { q: 'test', schemaSlug: 'articoli', status: null, limit: 20, cursor: null },
+      [TEXT_SEED, SECOND_SEED],
+    )
+    expect(result.sql).toContain('fts_articoli')
+    expect(result.sql).not.toContain('fts_team')
+  })
+
+  it('adds status filter to WHERE clause and bind values', () => {
+    const result = buildFtsQuery(
+      { q: 'hello', schemaSlug: null, status: 'published', limit: 20, cursor: null },
+      [TEXT_SEED],
+    )
+    expect(result.sql).toContain('ce.status = ?')
+    expect(result.binds).toContain('published')
+  })
+
+  it('adds cursor-based pagination condition when cursor is valid', () => {
+    const cursor = encodeCursor(-1.5, 'entry-123')
+    const result = buildFtsQuery(
+      { q: 'hello', schemaSlug: null, status: null, limit: 20, cursor },
+      [TEXT_SEED],
+    )
+    expect(result.sql).toContain('bm25')
+    expect(result.binds).toContain('entry-123')
+  })
+
+  it('ignores an invalid cursor and produces no pagination condition', () => {
+    const result = buildFtsQuery(
+      { q: 'hello', schemaSlug: null, status: null, limit: 20, cursor: 'bad-cursor' },
+      [TEXT_SEED],
+    )
+    expect(result.binds).not.toContain('entry-123')
+  })
+
+  it('countSql wraps each seed count in a SUM', () => {
+    const result = buildFtsQuery(
+      { q: 'test', schemaSlug: null, status: null, limit: 10, cursor: null },
+      [TEXT_SEED, SECOND_SEED],
+    )
+    expect(result.countSql).toContain('SUM')
+    expect(result.countSql).toContain('fts_articoli')
+    expect(result.countSql).toContain('fts_team')
+  })
+
+  it('count binds do not include the limit+1 sentinel', () => {
+    const result = buildFtsQuery(
+      { q: 'hello', schemaSlug: null, status: null, limit: 5, cursor: null },
+      [TEXT_SEED],
+    )
+    expect(result.countBinds).not.toContain(6) // limit + 1 must not appear in count binds
+  })
+
+  it('single-character terms (length < 2) are filtered out', () => {
+    // 'a b c' — single-char terms discarded; result depends on remaining terms
+    expect(() =>
+      buildFtsQuery({ q: 'a b c', schemaSlug: null, status: null, limit: 20, cursor: null }, [TEXT_SEED]),
+    ).toThrow('EMPTY_QUERY')
+  })
+
+  it('numeric terms are quoted without prefix expansion', () => {
+    const result = buildFtsQuery(
+      { q: '2024', schemaSlug: null, status: null, limit: 20, cursor: null },
+      [TEXT_SEED],
+    )
+    expect(result.binds[0]).toContain('"2024"')
+  })
+})
+
+// ─── mapFtsRow ───────────────────────────────────────────────────────────────
+
+describe('mapFtsRow', () => {
+  it('maps all FtsRow fields to SearchResultItem', () => {
+    const row = {
+      entry_id: 'e1', schema_slug: 'articoli', slug: 'my-post',
+      status: 'published', title: 'My Post', excerpt: 'A snippet', rank: -1,
+    }
+    const result = mapFtsRow(row)
+    expect(result.id).toBe('e1')
+    expect(result.schema_slug).toBe('articoli')
+    expect(result.slug).toBe('my-post')
+    expect(result.status).toBe('published')
+    expect(result.title).toBe('My Post')
+    expect(result.excerpt).toBe('A snippet')
+    expect(result.data).toEqual({})
+  })
+
+  it('strips HTML tags from excerpt but preserves <mark> and </mark>', () => {
+    const row = {
+      entry_id: 'e1', schema_slug: 'a', slug: null, status: 'draft',
+      title: null, excerpt: '<p>A <mark>word</mark> here</p>', rank: 0,
+    }
+    expect(mapFtsRow(row).excerpt).toBe('A <mark>word</mark> here')
+  })
+
+  it('collapses multiple whitespace characters in excerpt', () => {
+    const row = {
+      entry_id: 'e1', schema_slug: 'a', slug: null, status: 'draft',
+      title: null, excerpt: '<p>  lots   of  space  </p>', rank: 0,
+    }
+    expect(mapFtsRow(row).excerpt).toBe('lots of space')
+  })
+
+  it('returns empty string for null title', () => {
+    const row = {
+      entry_id: 'e1', schema_slug: 'a', slug: null, status: 'draft',
+      title: null, excerpt: '', rank: 0,
+    }
+    expect(mapFtsRow(row).title).toBe('')
+  })
+})