@beechcms/api 0.5.0 → 0.6.0-preview.2

package/src/features/automations/action-executors/edit-field.executor.ts

@@ -1,22 +1,26 @@
-import type { AutomationAction, ContentRepository, Seed } from '@beechcms/core'
-import type { ResolvedContext } from '../context-resolver'
-import { interpolate } from '../automation-runner.utils'
-
-type EditFieldAction = Extract<AutomationAction, { type: 'edit_field' }>
-
-export async function executeEditField(
-  action: EditFieldAction,
-  entry: Record<string, unknown>,
-  context: ResolvedContext,
-  repository: ContentRepository,
-  seed: Seed,
-): Promise<void> {
-  const id = entry.id
-  if (typeof id !== 'string') {
-    throw new Error('edit_field: entry.id missing')
-  }
-  const resolved = typeof action.value === 'string'
-    ? interpolate(action.value, context)
-    : action.value
-  await repository.update(seed, id, { [action.field]: resolved })
-}
+// 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 type { AutomationAction, ContentRepository, Seed } from '@beechcms/core'
+import type { ResolvedContext } from '../context-resolver'
+import { interpolate } from '../automation-runner.utils'
+
+type EditFieldAction = Extract<AutomationAction, { type: 'edit_field' }>
+
+export async function executeEditField(
+  action: EditFieldAction,
+  entry: Record<string, unknown>,
+  context: ResolvedContext,
+  repository: ContentRepository,
+  seed: Seed,
+): Promise<void> {
+  const id = entry.id
+  if (typeof id !== 'string') {
+    throw new Error('edit_field: entry.id missing')
+  }
+  const resolved = typeof action.value === 'string'
+    ? interpolate(action.value, context)
+    : action.value
+  await repository.update(seed, id, { [action.field]: resolved })
+}

package/src/features/automations/action-executors/index.ts

@@ -1,33 +1,37 @@
-import type { AutomationAction, ContentRepository, Seed, IIdGenerator } from '@beechcms/core'
-import type { ResolvedContext } from '../context-resolver'
-import { executeWebhook }      from './webhook.executor'
-import { executeSendMail }     from './send-mail.executor'
-import { executeEditField }    from './edit-field.executor'
-import { executeCreateEntry }  from './create-entry.executor'
-import { executeSetVariable }  from './set-variable.executor'
-
-export interface ActionContext {
-  entry: Record<string, unknown>
-  env: Record<string, string | undefined>
-  repository: ContentRepository
-  getSeed: (slug: string) => Seed | null
-  seed: Seed
-  idGenerator: IIdGenerator
-  context: ResolvedContext
-  variables: Record<string, unknown>
-  // TODO Sprint 8: context will also power evaluateWhen() for per-action when-guards
-}
-
-export async function executeAction(action: AutomationAction, ctx: ActionContext): Promise<void> {
-  switch (action.type) {
-    case 'set_variable':  return executeSetVariable(action, ctx)
-    case 'webhook':       return executeWebhook(action, ctx.context)
-    case 'send_mail':     return executeSendMail(action, ctx.context, ctx.env)
-    case 'edit_field':    return executeEditField(action, ctx.entry, ctx.context, ctx.repository, ctx.seed)
-    case 'create_entry':  return executeCreateEntry(action, ctx.entry, ctx.repository, ctx.getSeed, ctx.idGenerator)
-    default: {
-      const _exhaustive: never = action
-      throw new Error(`unknown action type: ${(action as { type: string }).type}`)
-    }
-  }
-}
+// 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 type { AutomationAction, ContentRepository, Seed, IIdGenerator } from '@beechcms/core'
+import type { ResolvedContext } from '../context-resolver'
+import { executeWebhook }      from './webhook.executor'
+import { executeSendMail }     from './send-mail.executor'
+import { executeEditField }    from './edit-field.executor'
+import { executeCreateEntry }  from './create-entry.executor'
+import { executeSetVariable }  from './set-variable.executor'
+
+export interface ActionContext {
+  entry: Record<string, unknown>
+  env: Record<string, string | undefined>
+  repository: ContentRepository
+  getSeed: (slug: string) => Seed | null
+  seed: Seed
+  idGenerator: IIdGenerator
+  context: ResolvedContext
+  variables: Record<string, unknown>
+  // TODO Sprint 8: context will also power evaluateWhen() for per-action when-guards
+}
+
+export async function executeAction(action: AutomationAction, ctx: ActionContext): Promise<void> {
+  switch (action.type) {
+    case 'set_variable':  return executeSetVariable(action, ctx)
+    case 'webhook':       return executeWebhook(action, ctx.context, ctx.env)
+    case 'send_mail':     return executeSendMail(action, ctx.context, ctx.env)
+    case 'edit_field':    return executeEditField(action, ctx.entry, ctx.context, ctx.repository, ctx.seed)
+    case 'create_entry':  return executeCreateEntry(action, ctx.entry, ctx.repository, ctx.getSeed, ctx.idGenerator)
+    default: {
+      const _exhaustive: never = action
+      throw new Error(`unknown action type: ${(action as { type: string }).type}`)
+    }
+  }
+}

package/src/features/automations/action-executors/send-mail.executor.ts

@@ -1,42 +1,53 @@
-import type { AutomationAction } from '@beechcms/core'
-import type { ResolvedContext } from '../context-resolver'
-import { sendAutomationMail } from '../../email'
-import { interpolate } from '../automation-runner.utils'
-
-type SendMailAction = Extract<AutomationAction, { type: 'send_mail' }>
-
-export async function executeSendMail(
-  action: SendMailAction,
-  context: ResolvedContext,
-  env: Record<string, string | undefined>,
-): Promise<void> {
-  const missingFields: string[] = []
-  const logMissing = (field: string) => missingFields.push(field)
-
-  const to = interpolate(action.to, context, '[missing]', logMissing)
-  const subject = interpolate(action.subject_template, context, '[missing]', logMissing)
-  const body = interpolate(action.body_template, context, '[missing]', logMissing)
-
-  if (missingFields.length > 0) {
-    console.warn('[automations:send_mail] placeholders evaluated to default value due to missing concrete data:', missingFields)
-  }
-
-  const apiKey = env.EMAIL_API_KEY ?? env.RESEND_API_KEY
-  if (!apiKey) {
-    console.error('[automations:send_mail] Execution skipped: Email API key is missing from the environment configuration.')
-    return
-  }
-
-  try {
-    await sendAutomationMail({
-      to,
-      subject,
-      body,
-      apiKey,
-      from: env.EMAIL_FROM,
-    })
-  } catch (error) {
-    console.error('[automations:send_mail] failed to send automation email via provider:', error)
-    throw error
-  }
-}
+// 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 type { AutomationAction } from '@beechcms/core'
+import type { ResolvedContext } from '../context-resolver'
+import { sendAutomationMail } from '../../email'
+import { interpolate } from '../automation-runner.utils'
+
+type SendMailAction = Extract<AutomationAction, { type: 'send_mail' }>
+
+export async function executeSendMail(
+  action: SendMailAction,
+  context: ResolvedContext,
+  env: Record<string, string | undefined>,
+): Promise<void> {
+  const missingFields: string[] = []
+  const logMissing = (field: string) => missingFields.push(field)
+
+  const to = interpolate(action.to, context, '[missing]', logMissing)
+  const subject = interpolate(action.subject_template, context, '[missing]', logMissing)
+  const body = interpolate(action.body_template, context, '[missing]', logMissing)
+
+  if (missingFields.length > 0) {
+    console.warn('[automations:send_mail] placeholders evaluated to default value due to missing concrete data:', missingFields)
+  }
+
+  const useSmtp = env.EMAIL_PROVIDER === 'smtp'
+  const apiKey = env.EMAIL_API_KEY ?? env.RESEND_API_KEY
+  if (!useSmtp && !apiKey) {
+    console.error('[automations:send_mail] Execution skipped: Email API key is missing from the environment configuration.')
+    return
+  }
+
+  const smtpBaseUrl = env.SMTP_HOST
+    ? `http://${env.SMTP_HOST}:${env.SMTP_PORT ?? '8025'}`
+    : undefined
+
+  try {
+    await sendAutomationMail({
+      to,
+      subject,
+      body,
+      apiKey: apiKey ?? '',
+      from: env.EMAIL_FROM,
+      provider: env.EMAIL_PROVIDER as 'smtp' | 'resend' | undefined,
+      smtpBaseUrl,
+    })
+  } catch (error) {
+    console.error('[automations:send_mail] failed to send automation email via provider:', error)
+    throw error
+  }
+}

package/src/features/automations/action-executors/set-variable.executor.ts

@@ -1,146 +1,159 @@
-import type { AutomationAction, ContentRepository, Seed } from '@beechcms/core'
-import type { ResolvedContext } from '../context-resolver'
-import { conditionToFilterGroup } from '../filter-translation'
-import { interpolate } from '../automation-runner.utils'
-
-type SetVariableAction = Extract<AutomationAction, { type: 'set_variable' }>
-
-export async function executeSetVariable(
-  action: SetVariableAction,
-  ctx: {
-    entry: Record<string, unknown>
-    variables: Record<string, unknown>
-    repository: ContentRepository
-    getSeed: (slug: string) => Seed | null
-    seed: Seed
-    context: ResolvedContext
-  },
-): Promise<void> {
-  const seedSlug = action.seed_slug ?? ctx.seed.slug
-  const targetSeed = ctx.getSeed(seedSlug)
-  if (!targetSeed) {
-    console.warn(`[set_variable] seed "${seedSlug}" not found; "${action.name}" → null`)
-    ctx.variables[action.name] = null
-    return
-  }
-
-  if (action.fixed_id !== undefined) {
-    const resolvedId = interpolate(action.fixed_id, ctx.context)
-    const { items } = await ctx.repository.findMany(targetSeed, {
-      filters: [{ column: 'id', type: 'system', conditions: [{ op: 'eq', value: resolvedId }] }],
-      status: null,
-      pagination: { limit: 1, offset: 0 },
-    })
-    const item = items[0] ?? null
-    if (!item) console.warn(`[set_variable] "${action.name}": id "${resolvedId}" not found`)
-    if (action.column) {
-      ctx.variables[action.name] = item ? { _value: item[action.column] } : null
-    } else {
-      ctx.variables[action.name] = item
-    }
-    return
-  }
-
-  const resolvedFilters = (action.filters ?? []).map((f) => {
-    const value = typeof f.value === 'string' ? interpolate(f.value, ctx.context) : f.value
-    return conditionToFilterGroup({ ...f, value }, targetSeed)
-  })
-
-  const orderDir: 'ASC' | 'DESC' = action.order === 'asc' ? 'ASC' : 'DESC'
-  const { items } = await ctx.repository.findMany(targetSeed, {
-    filters: resolvedFilters,
-    status: null,
-    pagination: { limit: 1000, offset: 0 },
-    orderBy: action.order_by ? { column: action.order_by, dir: orderDir } : undefined,
-  })
-
-  ctx.variables[action.name] = materializeCollection(targetSeed, items, action.column ?? null)
-}
-
-export function materializeCollection(
-  seed: Seed,
-  items: Array<Record<string, unknown>>,
-  pinned: string | null,
-): Record<string, unknown> {
-  const firstone = items.length > 0
-    ? items.reduce((best, r) => (Number(r['created_at']) < Number(best['created_at']) ? r : best), items[0])
-    : null
-  const lastone = items.length > 0
-    ? items.reduce((best, r) => (Number(r['created_at']) > Number(best['created_at']) ? r : best), items[0])
-    : null
-
-  let out: Record<string, unknown>
-
-  if (pinned === null) {
-    out = calculateGeneralStats(seed, items)
-    out.firstone = firstone
-    out.lastone = lastone
-  } else {
-    out = calculatePinnedStats(items, pinned)
-    out.firstone = firstone
-    out.lastone = lastone
-  }
-
-  Object.defineProperty(out, '_items', { value: items, enumerable: false })
-  return out
-}
-
-function formatPluckValues(items: Array<Record<string, unknown>>, key: string): string {
-  const vals = items.slice(0, 100).map((r) => String(r[key] ?? ''))
-  return vals.join(', ') + (items.length > 100 ? ' …' : '')
-}
-
-function calculatePinnedStats(items: Array<Record<string, unknown>>, pinned: string): Record<string, unknown> {
-  const nonNull = items.filter((r) => r[pinned] != null)
-  const nums = nonNull.map((r) => Number(r[pinned]))
-  const validNums = nums.filter((n) => !Number.isNaN(n))
-  const total = validNums.reduce((a, n) => a + n, 0)
-  const pluck = formatPluckValues(items, pinned)
-
-  return {
-    count: nonNull.length,
-    sum: validNums.length > 0 ? total : 0,
-    avg: validNums.length > 0 ? total / validNums.length : 0,
-    min: validNums.length > 0 ? Math.min(...validNums) : 0,
-    max: validNums.length > 0 ? Math.max(...validNums) : 0,
-    pluck,
-  }
-}
-
-function extractValidNumbers(items: Array<Record<string, unknown>>, key: string): number[] {
-  return items
-    .map((r) => {
-      const v = r[key]
-      const n = Number(v)
-      if (!Number.isNaN(n)) return n
-      if (typeof v === 'string') {
-        const d = Date.parse(v)
-        return Number.isNaN(d) ? Number.NaN : d / 1000
-      }
-      return Number.NaN
-    })
-    .filter((n) => !Number.isNaN(n))
-}
-
-function calculateGeneralStats(seed: Seed, items: Array<Record<string, unknown>>): Record<string, unknown> {
-  const sum: Record<string, number> = {}
-  const avg: Record<string, number> = {}
-  const min: Record<string, number> = {}
-  const max: Record<string, number> = {}
-  const pluck: Record<string, string> = {}
-
-  for (const branch of seed.branches) {
-    if (branch.type === 'number' || branch.type === 'date') {
-      const nums = extractValidNumbers(items, branch.alias)
-      const total = nums.reduce((a, n) => a + n, 0)
-      sum[branch.alias] = total
-      avg[branch.alias] = items.length > 0 ? total / items.length : 0
-      min[branch.alias] = nums.length > 0 ? Math.min(...nums) : 0
-      max[branch.alias] = nums.length > 0 ? Math.max(...nums) : 0
-    } else {
-      pluck[branch.alias] = formatPluckValues(items, branch.alias)
-    }
-  }
-
-  return { count: items.length, sum, avg, min, max, pluck }
-}
+// 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 type { AutomationAction, ContentRepository, Seed } from '@beechcms/core'
+import type { ResolvedContext } from '../context-resolver'
+import { conditionToFilterGroup } from '../filter-translation'
+import { interpolate } from '../automation-runner.utils'
+
+type SetVariableAction = Extract<AutomationAction, { type: 'set_variable' }>
+
+export async function executeSetVariable(
+  action: SetVariableAction,
+  ctx: {
+    entry: Record<string, unknown>
+    variables: Record<string, unknown>
+    repository: ContentRepository
+    getSeed: (slug: string) => Seed | null
+    seed: Seed
+    context: ResolvedContext
+  },
+): Promise<void> {
+  const seedSlug = action.seed_slug ?? ctx.seed.slug
+  const targetSeed = ctx.getSeed(seedSlug)
+  if (!targetSeed) {
+    console.warn(`[set_variable] seed "${seedSlug}" not found; "${action.name}" → null`)
+    ctx.variables[action.name] = null
+    return
+  }
+
+  // ── legacy read normalisation ─────────────────────────────────────────────
+  let effectiveFixedId = action.fixed_id
+  if (effectiveFixedId === undefined && action.load_type === 'fruit') {
+    const idFilter = (action.filters ?? []).find(
+      (f) => f.field === 'id' && f.op === 'eq' && typeof f.value === 'string',
+    )
+    if (idFilter) effectiveFixedId = String(idFilter.value)
+  }
+
+  if (effectiveFixedId !== undefined) {
+    const resolvedId = interpolate(effectiveFixedId, ctx.context)
+    const { items } = await ctx.repository.findMany(targetSeed, {
+      filters: [{ column: 'id', type: 'system', conditions: [{ op: 'eq', value: resolvedId }] }],
+      status: null,
+      pagination: { limit: 1, offset: 0 },
+    })
+    const item = items[0] ?? null
+    if (!item) console.warn(`[set_variable] "${action.name}": id "${resolvedId}" not found`)
+    if (action.column) {
+      ctx.variables[action.name] = item ? { _value: item[action.column] } : null
+    } else {
+      ctx.variables[action.name] = item
+    }
+    return
+  }
+
+  const resolvedFilters = (action.filters ?? []).map((f) => {
+    const value = typeof f.value === 'string' ? interpolate(f.value, ctx.context) : f.value
+    return conditionToFilterGroup({ ...f, value }, targetSeed)
+  })
+
+  const orderDir: 'ASC' | 'DESC' = action.order === 'asc' ? 'ASC' : 'DESC'
+  const { items } = await ctx.repository.findMany(targetSeed, {
+    filters: resolvedFilters,
+    status: null,
+    pagination: { limit: 1000, offset: 0 },
+    orderBy: action.order_by ? { column: action.order_by, dir: orderDir } : undefined,
+  })
+
+  ctx.variables[action.name] = materializeCollection(targetSeed, items, action.column ?? null)
+}
+
+export function materializeCollection(
+  seed: Seed,
+  items: Array<Record<string, unknown>>,
+  pinned: string | null,
+): Record<string, unknown> {
+  const firstone = items.length > 0
+    ? items.reduce((best, r) => (Number(r['created_at']) < Number(best['created_at']) ? r : best), items[0])
+    : null
+  const lastone = items.length > 0
+    ? items.reduce((best, r) => (Number(r['created_at']) > Number(best['created_at']) ? r : best), items[0])
+    : null
+
+  let out: Record<string, unknown>
+
+  if (pinned === null) {
+    out = calculateGeneralStats(seed, items)
+    out.firstone = firstone
+    out.lastone = lastone
+  } else {
+    out = calculatePinnedStats(items, pinned)
+    out.firstone = firstone
+    out.lastone = lastone
+  }
+
+  Object.defineProperty(out, '_items', { value: items, enumerable: false })
+  return out
+}
+
+function formatPluckValues(items: Array<Record<string, unknown>>, key: string): string {
+  const vals = items.slice(0, 100).map((r) => String(r[key] ?? ''))
+  return vals.join(', ') + (items.length > 100 ? ' …' : '')
+}
+
+function calculatePinnedStats(items: Array<Record<string, unknown>>, pinned: string): Record<string, unknown> {
+  const nonNull = items.filter((r) => r[pinned] != null)
+  const nums = nonNull.map((r) => Number(r[pinned]))
+  const validNums = nums.filter((n) => !Number.isNaN(n))
+  const total = validNums.reduce((a, n) => a + n, 0)
+  const pluck = formatPluckValues(items, pinned)
+
+  return {
+    count: nonNull.length,
+    sum: validNums.length > 0 ? total : 0,
+    avg: validNums.length > 0 ? total / validNums.length : 0,
+    min: validNums.length > 0 ? Math.min(...validNums) : 0,
+    max: validNums.length > 0 ? Math.max(...validNums) : 0,
+    pluck,
+  }
+}
+
+function extractValidNumbers(items: Array<Record<string, unknown>>, key: string): number[] {
+  return items
+    .map((r) => {
+      const v = r[key]
+      const n = Number(v)
+      if (!Number.isNaN(n)) return n
+      if (typeof v === 'string') {
+        const d = Date.parse(v)
+        return Number.isNaN(d) ? Number.NaN : d / 1000
+      }
+      return Number.NaN
+    })
+    .filter((n) => !Number.isNaN(n))
+}
+
+function calculateGeneralStats(seed: Seed, items: Array<Record<string, unknown>>): Record<string, unknown> {
+  const sum: Record<string, number> = {}
+  const avg: Record<string, number> = {}
+  const min: Record<string, number> = {}
+  const max: Record<string, number> = {}
+  const pluck: Record<string, string> = {}
+
+  for (const branch of seed.branches) {
+    if (branch.type === 'number' || branch.type === 'date') {
+      const nums = extractValidNumbers(items, branch.alias)
+      const total = nums.reduce((a, n) => a + n, 0)
+      sum[branch.alias] = total
+      avg[branch.alias] = items.length > 0 ? total / items.length : 0
+      min[branch.alias] = nums.length > 0 ? Math.min(...nums) : 0
+      max[branch.alias] = nums.length > 0 ? Math.max(...nums) : 0
+    } else {
+      pluck[branch.alias] = formatPluckValues(items, branch.alias)
+    }
+  }
+
+  return { count: items.length, sum, avg, min, max, pluck }
+}

package/src/features/automations/action-executors/webhook.executor.ts

@@ -1,25 +1,67 @@
-import type { AutomationAction } from '@beechcms/core'
-import type { ResolvedContext } from '../context-resolver'
-import { interpolate } from '../automation-runner.utils'
-
-type WebhookAction = Extract<AutomationAction, { type: 'webhook' }>
-
-export async function executeWebhook(
-  action: WebhookAction,
-  context: ResolvedContext,
-): Promise<void> {
-  const entry = context.triggerEntry ?? {}
-  const body = action.body_template
-    ? interpolate(action.body_template, context)
-    : JSON.stringify(entry)
-
-  const response = await fetch(action.url, {
-    method: action.method ?? 'POST',
-    headers: { 'Content-Type': 'application/json', ...(action.headers ?? {}) },
-    body,
-  })
-
-  if (!response.ok) {
-    throw new Error(`Webhook ${action.url} responded ${response.status}`)
-  }
-}
+// 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 type { AutomationAction } from '@beechcms/core'
+import type { ResolvedContext } from '../context-resolver'
+import { interpolate } from '../automation-runner.utils'
+
+type WebhookAction = Extract<AutomationAction, { type: 'webhook' }>
+
+const WEBHOOK_TIMEOUT_MS = 8_000
+
+let warnedNoSecret = false
+
+async function signBody(body: string, secret: string): Promise<string> {
+  const encoder = new TextEncoder()
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  )
+  const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(body))
+  return 'sha256=' + Array.from(new Uint8Array(sig))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+}
+
+export async function executeWebhook(
+  action: WebhookAction,
+  context: ResolvedContext,
+  env: Record<string, string | undefined>,
+): Promise<void> {
+  const body = interpolate(action.body_template ?? '{}', context)
+
+  const secret = env.WEBHOOK_SECRET
+  let signatureHeader: Record<string, string> = {}
+  if (secret) {
+    signatureHeader = { 'X-BeechCMS-Signature': await signBody(body, secret) }
+  } else if (!warnedNoSecret) {
+    warnedNoSecret = true
+    console.warn('[webhook] WEBHOOK_SECRET not set — outgoing webhooks are unsigned')
+  }
+
+  try {
+    const response = await fetch(action.url, {
+      method: action.method ?? 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(action.headers ?? {}),
+        ...signatureHeader,
+      },
+      body,
+      signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
+    })
+
+    if (!response.ok) {
+      throw new Error(`Webhook ${action.url} responded ${response.status}`)
+    }
+  } catch (err) {
+    if (err instanceof Error && err.name === 'TimeoutError') {
+      throw new Error(`Webhook ${action.url} timed out after ${WEBHOOK_TIMEOUT_MS}ms`)
+    }
+    throw err
+  }
+}