@beechcms/api 0.4.0-preview.9 → 0.4.1

package/src/public/api-key-middleware.ts

@@ -1,53 +1,53 @@
-import type { Context, Next } from 'hono'
-import { PUBLIC_ERRORS } from './public-errors'
-import { publicProblem } from './problem-details'
-
-type PublicBindings = {
-  PUBLIC_READ_API_KEY?: string
-  PUBLIC_WRITE_API_KEY?: string
-}
-
-function isReadMethod(method: string): boolean {
-  return method === 'GET' || method === 'HEAD' || method === 'OPTIONS'
-}
-
-function getConfiguredKey(env: PublicBindings, method: string): string | undefined {
-  if (isReadMethod(method)) {
-    return env.PUBLIC_READ_API_KEY
-  }
-  return env.PUBLIC_WRITE_API_KEY
-}
-
-/**
- * API key auth middleware for Public API routes.
- * Uses X-API-Key header only.
- */
-export function apiKeyMiddleware() {
-  return async (c: Context, next: Next): Promise<Response | void> => {
-    const env = c.env as PublicBindings
-    const configuredKey = getConfiguredKey(env, c.req.method)
-
-    if (!configuredKey) {
-      return publicProblem(c, {
-        type: 'public-api-not-configured',
-        title: PUBLIC_ERRORS.API_KEY_FORBIDDEN.error,
-        status: 403,
-        detail: PUBLIC_ERRORS.API_KEY_FORBIDDEN.message,
-      })
-    }
-
-    const providedKey = c.req.header('X-API-Key')
-
-    if (!providedKey || providedKey !== configuredKey) {
-      return publicProblem(c, {
-        type: 'public-api-key-unauthorized',
-        title: PUBLIC_ERRORS.API_KEY_UNAUTHORIZED.error,
-        status: 401,
-        detail: PUBLIC_ERRORS.API_KEY_UNAUTHORIZED.message,
-      })
-    }
-
-    await next()
-  }
-}
-
+import type { Context, Next } from 'hono'
+import { PUBLIC_ERRORS } from './public-errors'
+import { publicProblem } from './problem-details'
+
+type PublicBindings = {
+  PUBLIC_READ_API_KEY?: string
+  PUBLIC_WRITE_API_KEY?: string
+}
+
+function isReadMethod(method: string): boolean {
+  return method === 'GET' || method === 'HEAD' || method === 'OPTIONS'
+}
+
+function getConfiguredKey(env: PublicBindings, method: string): string | undefined {
+  if (isReadMethod(method)) {
+    return env.PUBLIC_READ_API_KEY
+  }
+  return env.PUBLIC_WRITE_API_KEY
+}
+
+/**
+ * API key auth middleware for Public API routes.
+ * Uses X-API-Key header only.
+ */
+export function apiKeyMiddleware() {
+  return async (c: Context, next: Next): Promise<Response | void> => {
+    const env = c.env as PublicBindings
+    const configuredKey = getConfiguredKey(env, c.req.method)
+
+    if (!configuredKey) {
+      return publicProblem(c, {
+        type: 'public-api-not-configured',
+        title: PUBLIC_ERRORS.API_KEY_FORBIDDEN.error,
+        status: 403,
+        detail: PUBLIC_ERRORS.API_KEY_FORBIDDEN.message,
+      })
+    }
+
+    const providedKey = c.req.header('X-API-Key')
+
+    if (!providedKey || providedKey !== configuredKey) {
+      return publicProblem(c, {
+        type: 'public-api-key-unauthorized',
+        title: PUBLIC_ERRORS.API_KEY_UNAUTHORIZED.error,
+        status: 401,
+        detail: PUBLIC_ERRORS.API_KEY_UNAUTHORIZED.message,
+      })
+    }
+
+    await next()
+  }
+}
+

package/src/public/index.ts

@@ -1,12 +1,12 @@
-export { apiKeyMiddleware } from './api-key-middleware'
-export { publicRateLimitMiddleware } from './rate-limit-middleware'
-export { publicRoutes } from './public-routes'
-export { PUBLIC_ERRORS } from './public-errors'
-export { sanitizePublicPayload } from './sanitize'
-export { generateEntrySlug, slugify } from './slug-utils'
-export { buildPublicListMeta, buildPublicSingleMeta } from './response-builder'
-export { parseLatestCount, parsePublicPagination } from './query-builder'
-export { publicReadHandler } from './public-read'
-export { publicAddHandler } from './public-add'
-export { publicEditHandler } from './public-edit'
-
+export { apiKeyMiddleware } from './api-key-middleware'
+export { publicRateLimitMiddleware } from './rate-limit-middleware'
+export { publicRoutes } from './public-routes'
+export { PUBLIC_ERRORS } from './public-errors'
+export { sanitizePublicPayload } from './sanitize'
+export { generateEntrySlug, slugify } from './slug-utils'
+export { buildPublicListMeta, buildPublicSingleMeta } from './response-builder'
+export { parseLatestCount, parsePublicPagination } from './query-builder'
+export { publicReadHandler } from './public-read'
+export { publicAddHandler } from './public-add'
+export { publicEditHandler } from './public-edit'
+

package/src/public/problem-details.ts

@@ -1,42 +1,48 @@
-import type { Context } from 'hono'
-
-export interface PublicProblemDetailItem {
-  field: string
-  expected: string
-  received: string
-  message: string
-}
-
-type PublicProblemInput = {
-  type: string
-  title: string
-  status: 400 | 401 | 403 | 404 | 405 | 409 | 422 | 429 | 500 | 501
-  detail: string
-  errors?: PublicProblemDetailItem[]
-}
-
-function normalizeProblemType(type: string): string {
-  if (type.startsWith('http://') || type.startsWith('https://')) {
-    return type
-  }
-  return `https://beechcms.dev/problems/${type}`
-}
-
-/**
- * Restituisce errori API in formato Problem Details (RFC 9457).
- */
-export function publicProblem(c: Context, input: PublicProblemInput): Response {
-  const body: Record<string, unknown> = {
-    type: normalizeProblemType(input.type),
-    title: input.title,
-    status: input.status,
-    detail: input.detail,
-    instance: c.req.path,
-  }
-  if (input.errors && input.errors.length > 0) {
-    body.errors = input.errors
-  }
-  return c.json(body, input.status, {
-    'Content-Type': 'application/problem+json',
-  })
-}
+import type { Context } from 'hono'
+
+export interface PublicProblemDetailItem {
+  field: string
+  expected: string
+  received: string
+  message: string
+}
+
+type PublicProblemInput = {
+  type: string
+  title: string
+  status: 400 | 401 | 403 | 404 | 405 | 409 | 422 | 429 | 500 | 501
+  detail: string
+  errors?: PublicProblemDetailItem[]
+}
+
+/**
+ * TODO: UPDATE DOMAIN ONCE REGISTERED
+ * Currently uses 'beechcms.dev' as a placeholder. 
+ * When a real domain is registered for BeechCMS, update the URL below 
+ * to point to the official API error documentation (RFC 9457).
+ */
+function normalizeProblemType(type: string): string {
+  if (type.startsWith('http://') || type.startsWith('https://')) {
+    return type
+  }
+  return `https://beechcms.dev/problems/${type}`
+}
+
+/**
+ * Restituisce errori API in formato Problem Details (RFC 9457).
+ */
+export function publicProblem(c: Context, input: PublicProblemInput): Response {
+  const body: Record<string, unknown> = {
+    type: normalizeProblemType(input.type),
+    title: input.title,
+    status: input.status,
+    detail: input.detail,
+    instance: c.req.path,
+  }
+  if (input.errors && input.errors.length > 0) {
+    body.errors = input.errors
+  }
+  return c.json(body, input.status, {
+    'Content-Type': 'application/problem+json',
+  })
+}

package/src/public/public-add.ts

@@ -1,183 +1,156 @@
-import { isValidContentStatus } from '@beechcms/core'
-import type { Seed } from '@beechcms/core'
-import type { Context } from 'hono'
-import { cleanStr } from '../shared/query-utils'
-import { buildInsertBindings } from '../shared/content-utils'
-import { checkPublicOperation } from './access-policy'
-import { publicProblem } from './problem-details'
-import { generateEntrySlug, slugify } from './slug-utils'
-import { sanitizePublicPayload } from './sanitize'
-import { createNotification } from '../shared/notification-service'
-
-type Bindings = {
-  DB: D1Database
-  PUBLIC_READ_API_KEY?: string
-  PUBLIC_WRITE_API_KEY?: string
-  PUBLIC_IDEMPOTENCY_TTL_SECONDS?: string
-  ENV?: string
-}
-
-type Variables = {
-  jwtPayload: { sub: string; email?: string }
-  getSeed: (slug: string) => Seed | null
-  seedRegistry: Record<string, Seed>
-}
-
-function errorMessage(c: Context<{ Bindings: Bindings; Variables: Variables }>, err: unknown): string {
-  if (c.env.ENV !== 'production' && err instanceof Error) return err.message
-  return 'An unexpected error occurred.'
-}
-
-function asRecord(value: unknown): Record<string, unknown> | null {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : null
-}
-
-function pickSlugFromBody(body: Record<string, unknown>, sanitizedData: Record<string, unknown>): string {
-  const explicitSlug = cleanStr(body.slug)
-  if (explicitSlug) return slugify(explicitSlug)
-  return generateEntrySlug({ title: sanitizedData.title, name: sanitizedData.name })
-}
-
-function parseIdempotencyKey(rawValue: string | undefined): string | null {
-  if (!rawValue) return null
-  const key = rawValue.trim()
-  if (!key || key.length > 128) return null
-  return key
-}
-
-function toHex(buffer: ArrayBuffer): string {
-  return [...new Uint8Array(buffer)].map((v) => v.toString(16).padStart(2, '0')).join('')
-}
-
-async function sha256Hex(input: string): Promise<string> {
-  const data = new TextEncoder().encode(input)
-  const digest = await crypto.subtle.digest('SHA-256', data)
-  return toHex(digest)
-}
-
-type StoredIdempotencyRecord = {
-  idempotency_key: string
-  request_fingerprint: string
-  response_status: number
-  response_body: string
-  expires_at: number
-}
-
-async function lookupIdempotency(db: D1Database, key: string): Promise<StoredIdempotencyRecord | null> {
-  return db.prepare(
-    `SELECT idempotency_key, request_fingerprint, response_status, response_body, expires_at
-     FROM public_idempotency_keys WHERE idempotency_key = ? LIMIT 1`
-  ).bind(key).first<StoredIdempotencyRecord>()
-}
-
-async function storeIdempotency(db: D1Database, input: {
-  key: string; fingerprint: string; responseStatus: number
-  responseBody: string; expiresAt: number; createdAt: number
-}): Promise<void> {
-  await db.prepare(
-    `INSERT INTO public_idempotency_keys (idempotency_key, request_fingerprint, response_status, response_body, created_at, expires_at)
-     VALUES (?, ?, ?, ?, ?, ?)
-     ON CONFLICT(idempotency_key) DO UPDATE SET
-       request_fingerprint = excluded.request_fingerprint,
-       response_status = excluded.response_status,
-       response_body = excluded.response_body,
-       created_at = excluded.created_at,
-       expires_at = excluded.expires_at`
-  ).bind(input.key, input.fingerprint, input.responseStatus, input.responseBody, input.createdAt, input.expiresAt).run()
-}
-
-export async function publicAddHandler(c: Context<{ Bindings: Bindings; Variables: Variables }>) {
-  const seedSlug = c.req.param('seed') ?? ''
-  const seed = c.get('getSeed')(seedSlug)
-  if (!seed) {
-    return publicProblem(c, { type: 'seed-not-found', title: 'Seed Not Found', status: 404, detail: `The content type '${seedSlug}' does not exist.` })
-  }
-  const access = checkPublicOperation(seed, 'add')
-  if (!access.ok) {
-    return publicProblem(c, { type: 'operation-not-allowed', title: access.error.error, status: 403, detail: access.error.message })
-  }
-
-  let body: Record<string, unknown>
-  try {
-    const parsed = await c.req.json<unknown>()
-    body = asRecord(parsed) ?? {}
-  } catch {
-    return publicProblem(c, { type: 'invalid-json-body', title: 'Bad Request', status: 400, detail: 'Invalid JSON body' })
-  }
-
-  const rawData = asRecord(body.data)
-  if (!rawData || Object.keys(rawData).length === 0) {
-    return publicProblem(c, { type: 'invalid-data-object', title: 'Bad Request', status: 400, detail: "Field 'data' is required and must be a non-empty object" })
-  }
-
-  const statusValue = body.status ?? 'draft'
-  if (!isValidContentStatus(statusValue)) {
-    return publicProblem(c, { type: 'invalid-status', title: 'Bad Request', status: 400, detail: 'Invalid status. Allowed values are: draft, review, published' })
-  }
-
-  const sanitized = sanitizePublicPayload(seed, rawData, {
-    operation: 'create', allowNull: false, requireAtLeastOneValidField: true, enforceRequiredFields: true,
-  })
-  if (!sanitized.ok) {
-    if (sanitized.status === 422) {
-      return publicProblem(c, { type: sanitized.code, title: 'Unprocessable Entity', status: 422, detail: sanitized.message })
-    }
-    return publicProblem(c, { type: sanitized.code, title: 'Bad Request', status: 400, detail: sanitized.message, errors: sanitized.details })
-  }
-
-  const idempotencyKey = parseIdempotencyKey(c.req.header('Idempotency-Key'))
-  const entrySlug = pickSlugFromBody(body, sanitized.data)
-  const finalSlug = entrySlug || crypto.randomUUID().slice(0, 8)
-  const table = `content_${seedSlug}`
-
-  try {
-    const { DB } = c.env
-    const now = Math.floor(Date.now() / 1000)
-    const fingerprintPayload = JSON.stringify({ seedSlug, statusValue, slug: cleanStr(body.slug) ?? null, data: sanitized.data })
-    const fingerprint = await sha256Hex(fingerprintPayload)
-    const idempotencyTtlSeconds = Math.max(60, Number.parseInt(c.env.PUBLIC_IDEMPOTENCY_TTL_SECONDS ?? '86400', 10) || 86400)
-
-    if (idempotencyKey) {
-      const existing = await lookupIdempotency(DB, idempotencyKey)
-      if (existing && existing.expires_at >= now) {
-        if (existing.request_fingerprint !== fingerprint) {
-          return publicProblem(c, { type: 'idempotency-key-conflict', title: 'Conflict', status: 409, detail: 'Idempotency-Key was already used with a different request payload.' })
-        }
-        let parsedBody: unknown = null
-        try { parsedBody = JSON.parse(existing.response_body) } catch { parsedBody = { success: true } }
-        return c.json(parsedBody, existing.response_status as 201)
-      }
-    }
-
-    const slugExisting = await DB.prepare(`SELECT id FROM ${table} WHERE slug = ? LIMIT 1`).bind(finalSlug).first<{ id: string }>()
-    if (slugExisting) {
-      return publicProblem(c, { type: 'slug-conflict', title: 'Conflict', status: 409, detail: `An entry with slug '${finalSlug}' already exists for content type '${seedSlug}'.` })
-    }
-
-    const id = crypto.randomUUID()
-    const { cols, placeholders, bindings } = buildInsertBindings(seed, sanitized.data)
-    const systemCols = ['id', 'slug', 'status', 'created_at', 'updated_at']
-    const systemVals = [id, finalSlug, statusValue, now, now]
-    const allCols = [...systemCols, ...cols].join(', ')
-    const allPlaceholders = [...systemVals.map(() => '?'), ...placeholders].join(', ')
-
-    await DB.prepare(`INSERT INTO ${table} (${allCols}) VALUES (${allPlaceholders})`).bind(...systemVals, ...bindings).run()
-
-    const responseBody = { success: true, id, slug: finalSlug }
-    if (idempotencyKey) {
-      await storeIdempotency(DB, { key: idempotencyKey, fingerprint, responseStatus: 201, responseBody: JSON.stringify(responseBody), createdAt: now, expiresAt: now + idempotencyTtlSeconds })
-    }
-
-    await createNotification(c, {
-      title: `${seed.label}: Nuovo inserimento`,
-      message: `Una nuova entry ("${sanitized.data.title || sanitized.data.name || finalSlug}") è stata aggiunta via API pubblica.`,
-      type: 'success',
-    })
-
-    return c.json(responseBody, 201)
-  } catch (err) {
-    return publicProblem(c, { type: 'internal-server-error', title: 'Internal Server Error', status: 500, detail: errorMessage(c, err) })
-  }
-}
+import { isValidContentStatus, SlugConflictError, sha256hex } 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 { generateEntrySlug, slugify } from './slug-utils'
+import { sanitizePublicPayload } from './sanitize'
+import { AppEnv } from '../types'
+
+function errorMessage(context: Context<AppEnv>, error: unknown): string {
+  if (context.env.ENV !== 'production' && error instanceof Error) return error.message
+  return 'An unexpected error occurred.'
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+function pickSlugFromBody(body: Record<string, unknown>, sanitizedData: Record<string, unknown>): string {
+  const explicitSlug = cleanStr(body.slug)
+  if (explicitSlug) return slugify(explicitSlug)
+  return generateEntrySlug({ title: sanitizedData.title, name: sanitizedData.name })
+}
+
+function parseIdempotencyKey(rawValue: string | undefined): string | null {
+  if (!rawValue) return null
+  const key = rawValue.trim()
+  if (!key || key.length > 128) return null
+  return key
+}
+
+
+export async function publicAddHandler(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: `The content type '${seedSlug}' does not exist.` 
+    })
+  }
+  
+  const access = checkPublicOperation(seed, 'add')
+  if (!access.ok) {
+    return publicProblem(context, { 
+      type: 'operation-not-allowed', 
+      title: access.error.error, 
+      status: 403, 
+      detail: access.error.message 
+    })
+  }
+
+  let body: Record<string, unknown>
+  try {
+    const parsed = await context.req.json<unknown>()
+    body = asRecord(parsed) ?? {}
+  } catch {
+    return publicProblem(context, { type: 'invalid-json-body', title: 'Bad Request', status: 400, detail: 'Invalid JSON body' })
+  }
+
+  const rawData = asRecord(body.data)
+  if (!rawData || Object.keys(rawData).length === 0) {
+    return publicProblem(context, { type: 'invalid-data-object', title: 'Bad Request', status: 400, detail: "Field 'data' is required and must be a non-empty object" })
+  }
+
+  const statusValue = body.status ?? 'draft'
+  if (!isValidContentStatus(statusValue)) {
+    return publicProblem(context, { type: 'invalid-status', title: 'Bad Request', status: 400, detail: 'Invalid status. Allowed values are: draft, review, published' })
+  }
+
+  const sanitized = sanitizePublicPayload(seed, rawData, {
+    operation: 'create', 
+    allowNull: false, 
+    requireAtLeastOneValidField: true, 
+    enforceRequiredFields: true,
+  })
+  
+  if (!sanitized.ok) {
+    if (sanitized.status === 422) {
+      return publicProblem(context, { type: sanitized.code, title: 'Unprocessable Entity', status: 422, detail: sanitized.message })
+    }
+    return publicProblem(context, { type: sanitized.code, title: 'Bad Request', status: 400, detail: sanitized.message, errors: sanitized.details })
+  }
+
+  const idempotencyKey = parseIdempotencyKey(context.req.header('Idempotency-Key'))
+  const entrySlug = pickSlugFromBody(body, sanitized.data)
+  const finalSlug = entrySlug || context.get('idGenerator').uuid().slice(0, 8)
+  const repository = context.get('repository')
+  const idempotencyRepository = context.get('idempotencyRepository')
+
+  try {
+    const now = Math.floor(Date.now() / 1000)
+    const fingerprintPayload = JSON.stringify({ seedSlug, statusValue, slug: cleanStr(body.slug) ?? null, data: sanitized.data })
+    const fingerprint = await sha256hex(fingerprintPayload)
+    const idempotencyTtlSeconds = Math.max(60, Number.parseInt(context.env.PUBLIC_IDEMPOTENCY_TTL_SECONDS ?? '86400', 10) || 86400)
+
+    if (idempotencyKey) {
+      const existing = await idempotencyRepository.lookup(idempotencyKey)
+      if (existing && existing.expiresAt >= now) {
+        if (existing.fingerprint !== fingerprint) {
+          return publicProblem(context, { type: 'idempotency-key-conflict', title: 'Conflict', status: 409, detail: 'Idempotency-Key was already used with a different request payload.' })
+        }
+        let parsedBody: unknown = null
+        try { parsedBody = JSON.parse(existing.responseBody) } catch { parsedBody = { success: true } }
+        return context.json(parsedBody, existing.responseStatus as 201)
+      }
+    }
+
+    const id = context.get('idGenerator').uuid()
+    
+    try {
+      await repository.create(seed, id, finalSlug, statusValue as any, sanitized.data)
+    } catch (error) {
+      if (error instanceof SlugConflictError) {
+        return publicProblem(context, { 
+          type: 'slug-conflict', 
+          title: 'Conflict', 
+          status: 409, 
+          detail: `An entry with slug '${finalSlug}' already exists for content type '${seedSlug}'.` 
+        })
+      }
+      throw error
+    }
+
+    const responseBody = { success: true, id, slug: finalSlug }
+    if (idempotencyKey) {
+      await idempotencyRepository.store({ 
+        key: idempotencyKey, 
+        fingerprint, 
+        responseStatus: 201, 
+        responseBody: JSON.stringify(responseBody), 
+        expiresAt: now + idempotencyTtlSeconds 
+      })
+    }
+
+    context.get('notificationService').notify({
+      title: `${seed.label}: New entry`,
+      message: `A new entry ("${sanitized.data.title || sanitized.data.name || finalSlug}") has been added via the public API.`,
+      type: 'success',
+    })
+
+    return context.json(responseBody, 201)
+  } catch (error) {
+    console.error('Public add error:', error)
+    return publicProblem(context, { 
+      type: 'internal-server-error', 
+      title: 'Internal Server Error', 
+      status: 500, 
+      detail: errorMessage(context, error) 
+    })
+  }
+}