@beechcms/api 0.4.3 → 0.6.0-preview.1

package/src/features/automations/__tests__/template-grammar.test.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.
+
 import { describe, it, expect } from 'vitest'
 import { parseTemplateKey } from '../template-grammar'
 import type { ParsedKey, VarStep, InlineCondition } from '../template-grammar'

package/src/features/automations/__tests__/webhook.executor.test.ts

@@ -0,0 +1,142 @@
+// 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 { executeWebhook } from '../action-executors/webhook.executor'
+import type { ResolvedContext } from '../context-resolver'
+
+function makeContext(entry: Record<string, unknown> = {}, event = 'create'): ResolvedContext {
+  return {
+    triggerEntry: entry,
+    lookup(parsed) {
+      if (parsed.kind === 'simple') {
+        const key = parsed.path.startsWith('this.') ? parsed.path.slice(5) : parsed.path
+        if (key === 'trigger_event') return event
+        return entry[key] ?? null
+      }
+      return null
+    },
+  }
+}
+
+const baseContext = makeContext({ id: 'entry-1', title: 'Hello' })
+
+const baseAction = {
+  type: 'webhook' as const,
+  url: 'https://example.com/hook',
+  body_template: '{"static":true}',
+}
+
+function makeOkResponse(status = 200): Response {
+  return { ok: true, status } as unknown as Response
+}
+
+function makeErrorResponse(status: number): Response {
+  return { ok: false, status } as unknown as Response
+}
+
+beforeEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('executeWebhook', () => {
+  it('signs request when WEBHOOK_SECRET is set', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(makeOkResponse())
+
+    await executeWebhook(baseAction, baseContext, { WEBHOOK_SECRET: 'test-secret' })
+
+    expect(fetchSpy).toHaveBeenCalledOnce()
+    const [, init] = fetchSpy.mock.calls[0]
+    const headers = init?.headers as Record<string, string>
+    expect(headers['X-BeechCMS-Signature']).toMatch(/^sha256=[0-9a-f]{64}$/)
+  })
+
+  it('omits signature header and warns once when WEBHOOK_SECRET is absent', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(makeOkResponse())
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+    await executeWebhook(baseAction, baseContext, {})
+    await executeWebhook(baseAction, baseContext, {})
+
+    const [, init] = fetchSpy.mock.calls[0]
+    const headers = init?.headers as Record<string, string>
+    expect(headers['X-BeechCMS-Signature']).toBeUndefined()
+    expect(warnSpy).toHaveBeenCalledOnce()
+    expect(warnSpy.mock.calls[0][0]).toContain('WEBHOOK_SECRET')
+  })
+
+  it('overwrites user-supplied X-BeechCMS-Signature header with computed value', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(makeOkResponse())
+
+    const action = {
+      ...baseAction,
+      headers: { 'X-BeechCMS-Signature': 'sha256=user-supplied-value' },
+    }
+
+    await executeWebhook(action, baseContext, { WEBHOOK_SECRET: 'test-secret' })
+
+    const [, init] = fetchSpy.mock.calls[0]
+    const headers = init?.headers as Record<string, string>
+    expect(headers['X-BeechCMS-Signature']).toMatch(/^sha256=[0-9a-f]{64}$/)
+    expect(headers['X-BeechCMS-Signature']).not.toBe('sha256=user-supplied-value')
+  })
+
+  it('throws with status code when endpoint responds with 500', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(makeErrorResponse(500))
+
+    await expect(executeWebhook(baseAction, baseContext, {}))
+      .rejects.toThrow('500')
+  })
+
+  it('interpolates body_template placeholders before sending', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(makeOkResponse())
+
+    const action = { ...baseAction, body_template: '{"event":"{{trigger_event}}","id":"{{id}}"}' }
+    const ctx = makeContext({ id: 'abc-123' }, 'update')
+
+    await executeWebhook(action, ctx, {})
+
+    const [, init] = fetchSpy.mock.calls[0]
+    const body = init?.body as string
+    expect(body).toContain('abc-123')
+    expect(body).toContain('update')
+  })
+
+  it('recalculates HMAC and matches X-BeechCMS-Signature header', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(makeOkResponse())
+    const secret = 'verify-secret'
+
+    await executeWebhook(baseAction, baseContext, { WEBHOOK_SECRET: secret })
+
+    const [, init] = fetchSpy.mock.calls[0]
+    const headers = init?.headers as Record<string, string>
+    const sentBody = init?.body as string
+    const sentSig = headers['X-BeechCMS-Signature']
+
+    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(sentBody))
+    const expected = 'sha256=' + Array.from(new Uint8Array(sig))
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('')
+
+    expect(sentSig).toBe(expected)
+  })
+
+  it('throws timeout error when fetch takes longer than 8 seconds', async () => {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(() => {
+      const err = new DOMException('The operation was aborted.', 'TimeoutError')
+      return Promise.reject(err)
+    })
+
+    await expect(executeWebhook(baseAction, baseContext, {}))
+      .rejects.toThrow('timed out after 8000ms')
+  })
+})

package/src/features/automations/__tests__/when-evaluator.test.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.
+
 import { describe, it, expect } from 'vitest'
 import type { WhenNode } from '@beechcms/core'
 import { evaluateWhen } from '../when-evaluator'

package/src/features/automations/__tests__/when-pushdown.test.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.
+
 import { describe, it, expect } from 'vitest'
 import type { WhenNode, Seed } from '@beechcms/core'
 import { extractPushdownFilters } from '../when-pushdown'
@@ -11,7 +15,7 @@ function makeSeed(aliases: string[] = []): Seed {
     slug: 'orders',
     label: 'Orders',
     displayNameAlias: aliases[0] ?? 'id',
-    branches: aliases.map((alias) => ({ alias, label: alias, type: 'text' as const })),
+    branches: aliases.map((alias, i) => ({ id: `br_0${i + 1}`, alias, label: alias, type: 'text' as const })),
   }
 }
 

package/src/features/automations/action-executors/create-entry.executor.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.
+
 import type { AutomationAction, ContentRepository, Seed, IIdGenerator } from '@beechcms/core'
 
 type CreateEntryAction = Extract<AutomationAction, { type: 'create_entry' }>

package/src/features/automations/action-executors/edit-field.executor.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.
+
 import type { AutomationAction, ContentRepository, Seed } from '@beechcms/core'
 import type { ResolvedContext } from '../context-resolver'
 import { interpolate } from '../automation-runner.utils'

package/src/features/automations/action-executors/index.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.
+
 import type { AutomationAction, ContentRepository, Seed, IIdGenerator } from '@beechcms/core'
 import type { ResolvedContext } from '../context-resolver'
 import { executeWebhook }      from './webhook.executor'
@@ -21,7 +25,7 @@ export interface ActionContext {
 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 '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)

package/src/features/automations/action-executors/send-mail.executor.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.
+
 import type { AutomationAction } from '@beechcms/core'
 import type { ResolvedContext } from '../context-resolver'
 import { sendAutomationMail } from '../../email'
@@ -21,19 +25,26 @@ export async function executeSendMail(
     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 (!apiKey) {
+  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: 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)

package/src/features/automations/action-executors/set-variable.executor.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.
+
 import type { AutomationAction, ContentRepository, Seed } from '@beechcms/core'
 import type { ResolvedContext } from '../context-resolver'
 import { conditionToFilterGroup } from '../filter-translation'
@@ -24,8 +28,17 @@ export async function executeSetVariable(
     return
   }
 
-  if (action.fixed_id !== undefined) {
-    const resolvedId = interpolate(action.fixed_id, ctx.context)
+  // ── 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,

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

@@ -1,25 +1,67 @@
+// 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 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}`)
+  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
   }
 }

package/src/features/automations/automation-runner.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.
+
 import type {
   IAutomationRunner,
   IAutomationRepository,

package/src/features/automations/automation-runner.utils.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.
+
 import type { ResolvedContext } from './context-resolver'
 import { parseTemplateKey } from './template-grammar'
 

package/src/features/automations/automations.handler.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.
+
 /// <reference types="@cloudflare/workers-types" />
 import { Hono } from 'hono'
 import type { Env, Variables } from '../../types'

package/src/features/automations/automations.schema.ts

@@ -1,6 +1,11 @@
+// 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.
+
 // Mirror: apps/dashboard/src/features/automations/schema/automation.schema.ts — keep structurally identical.
 import { z } from 'zod'
 import type { WhenNode } from '@beechcms/core'
+import { isPrivateHost } from '@beechcms/core'
 import { AUTOMATION_RESERVED_WORDS } from './template-grammar'
 
 // ---------------------------------------------------------------------------
@@ -71,14 +76,26 @@ const setVariableActionSchema = z.object({
   filters: z.array(setVariableFilterSchema).default([]),
   order_by: z.string().optional(),
   order: z.enum(['asc', 'desc']).optional(),
+  load_type: z.enum(['fruit', 'branch']).optional(),  // accepted but ignored at runtime
 })
 
 const webhookActionSchema = z.object({
   type: z.literal('webhook'),
-  url: z.string().url(),
+  url: z
+    .string()
+    .url()
+    .refine((u) => {
+      try { return new URL(u).protocol === 'https:' } catch { return false }
+    }, { message: 'automations.editor.errors.webhookHttpsRequired' })
+    .refine((u) => {
+      try { return !isPrivateHost(new URL(u).hostname) } catch { return false }
+    }, { message: 'automations.editor.errors.webhookPrivateHostBlocked' }),
   method: z.enum(['POST', 'GET', 'PUT']).optional(),
   headers: z.record(z.string(), z.string()).optional(),
-  body_template: z.string().optional(),
+  body_template: z.preprocess(
+    (v) => (v == null ? '' : v),
+    z.string().min(1, 'automations.editor.errors.bodyRequired'),
+  ),
 })
 
 const sendMailActionSchema = z.object({

package/src/features/automations/context-resolver.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.
+
 import type { Automation } from '@beechcms/core'
 import type { AutomationContextSelector, ParsedKey } from './template-grammar'
 import { resolvePath } from './automation-runner.utils'

package/src/features/automations/cron-runner.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.
+
 import type {
   Automation,
   ContentRepository,

package/src/features/automations/cron-runner.utils.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 function cronMatches(expression: string | null, scheduledTime: number): boolean {
   if (!expression) return false
   const parts = expression.trim().split(/\s+/)

package/src/features/automations/filter-translation.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.
+
 /**
  * Shared helper: converts a TriggerCondition into a FilterGroup accepted by
  * ContentRepository.findMany. Used by cron-runner and context-resolver.

package/src/features/automations/index.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 { AutomationRunner } from './automation-runner'
 export type { AutomationRunnerDeps } from './automation-runner'
 export { runCronAutomations } from './cron-runner'

package/src/features/automations/template-grammar.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.
+
 /**
  * Pure template-key parser for the automation template engine.
  *

package/src/features/automations/var-access-resolver.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.
+
 import type { Seed } from '@beechcms/core'
 import type { ParsedKey, InlineCondition } from './template-grammar'
 import { materializeCollection } from './action-executors/set-variable.executor'

package/src/features/automations/when-evaluator.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.
+
 import type { WhenNode, WhenPredicate, WhenGroup, WhenOperand } from '@beechcms/core'
 import type { ResolvedContext } from './context-resolver'
 import { parseTemplateKey } from './template-grammar'

package/src/features/automations/when-pushdown.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.
+
 import type { WhenNode, WhenPredicate, TriggerCondition, FilterGroup, Seed } from '@beechcms/core'
 import { conditionToFilterGroup } from './filter-translation'