@beechcms/api 0.4.0 → 0.4.2

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

@@ -0,0 +1,146 @@
+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 }
+}

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

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

package/src/features/automations/automation-runner.ts

@@ -0,0 +1,81 @@
+import type {
+  IAutomationRunner,
+  IAutomationRepository,
+  AutomationEventPayload,
+  ContentRepository,
+  Seed,
+  IIdGenerator,
+} from '@beechcms/core'
+import { resolvePath } from './automation-runner.utils'
+import { resolveAutomationContext, type ResolvedContext } from './context-resolver'
+import type { ParsedKey } from './template-grammar'
+import { executeAction } from './action-executors'
+import { evaluateWhen } from './when-evaluator'
+import { resolveVarAccess } from './var-access-resolver'
+
+export interface AutomationRunnerDeps {
+  automationRepository: IAutomationRepository
+  contentRepository: ContentRepository
+  getSeed: (slug: string) => Seed | null
+  idGenerator: IIdGenerator
+  env: Record<string, string | undefined>
+}
+
+function withVariables(base: ResolvedContext, variables: Record<string, unknown>): ResolvedContext {
+  return {
+    triggerEntry: base.triggerEntry,
+    lookup(parsed: ParsedKey, onMissing?: (field: string) => void): unknown {
+      if (parsed.kind === 'simple') {
+        const varVal = resolvePath(variables, parsed.path)
+        if (varVal !== undefined) return varVal
+      } else if (parsed.kind === 'var_access') {
+        return resolveVarAccess(parsed, variables, onMissing)
+      }
+      return base.lookup(parsed, onMissing)
+    },
+  }
+}
+
+export class AutomationRunner implements IAutomationRunner {
+  constructor(private readonly deps: AutomationRunnerDeps) {}
+
+  async run(payload: AutomationEventPayload): Promise<void> {
+    const { seedSlug, event, entry } = payload
+    const seed = this.deps.getSeed(seedSlug)
+    if (!seed) return
+
+    const automations = await this.deps.automationRepository.findActive(seedSlug, event)
+
+    for (const automation of automations) {
+      const resolved = await resolveAutomationContext(automation, entry, [entry])
+
+      // Evaluate conditions with the resolved context (this + batch scopes available).
+      // Variables from set_variable actions are not yet available here; use inline refs
+      // like {{customers:byid({{this.id}}):field}} for cross-seed conditions in v1.
+      if (!evaluateWhen(automation.trigger_conditions, resolved)) continue
+
+      const variables: Record<string, unknown> = {}
+
+      for (const action of automation.actions) {
+        try {
+          await executeAction(action, {
+            entry,
+            env: this.deps.env,
+            repository: this.deps.contentRepository,
+            getSeed: this.deps.getSeed,
+            seed,
+            idGenerator: this.deps.idGenerator,
+            context: withVariables(resolved, variables),
+            variables,
+          })
+        } catch (error) {
+          console.error('[automations] action failed', {
+            automationId: automation.id,
+            actionType: action.type,
+            error,
+          })
+        }
+      }
+    }
+  }
+}

package/src/features/automations/automation-runner.utils.ts

@@ -0,0 +1,43 @@
+import type { ResolvedContext } from './context-resolver'
+import { parseTemplateKey } from './template-grammar'
+
+export function interpolate(
+  template: string,
+  context: ResolvedContext,
+  defaultValue = '',
+  onMissing?: (field: string) => void,
+): string {
+  if (!template) return ''
+
+  const replacer = (_: string, key: string) => {
+    const trimmedKey = key.trim()
+    const parsed = parseTemplateKey(trimmedKey)
+    if (!parsed) {
+      if (onMissing) onMissing(trimmedKey)
+      return defaultValue
+    }
+    const val = context.lookup(parsed, onMissing)
+    if (val == null || val === '') {
+      return defaultValue
+    }
+    return String(val)
+  }
+
+  return template.replace(/\{\{\s*([^{}]+?)\s*\}\}/g, replacer)
+}
+
+export function resolvePath(obj: Record<string, unknown>, path: string): unknown {
+  if (path in obj && obj[path] !== undefined) {
+    return obj[path]
+  }
+  const parts = path.split('.')
+  let current: unknown = obj
+  for (const part of parts) {
+    if (current && typeof current === 'object') {
+      current = (current as Record<string, unknown>)[part]
+    } else {
+      return undefined
+    }
+  }
+  return current
+}

package/src/features/automations/automations.handler.ts

@@ -0,0 +1,193 @@
+/// <reference types="@cloudflare/workers-types" />
+import { Hono } from 'hono'
+import type { Env, Variables } from '../../types'
+import { publicProblem } from '../../public/problem-details'
+import {
+  createAutomationSchema,
+  updateAutomationSchema,
+  toggleAutomationSchema,
+} from './automations.schema'
+
+const automationsApp = new Hono<{ Bindings: Env; Variables: Variables }>()
+
+/**
+ * GET /automations?seed=<slug>
+ * Returns every automation declared for the given seed, newest first.
+ */
+automationsApp.get('/', async (context) => {
+  const seedSlug = context.req.query('seed')
+  if (!seedSlug) {
+    return publicProblem(context, {
+      type: 'missing-seed',
+      status: 400,
+      title: 'Bad Request',
+      detail: 'Query param `seed` is required',
+    })
+  }
+  const repository = context.get('automationRepository')
+  const automations = await repository.list(seedSlug)
+  return context.json(automations)
+})
+
+/**
+ * POST /automations
+ * Creates a new automation. Body validated by `createAutomationSchema`.
+ */
+automationsApp.post('/', async (context) => {
+  let body: unknown
+  try {
+    body = await context.req.json()
+  } catch {
+    return publicProblem(context, {
+      type: 'invalid-json',
+      status: 400,
+      title: 'Bad Request',
+      detail: 'Request body is not valid JSON',
+    })
+  }
+
+  const parsed = createAutomationSchema.safeParse(body)
+  if (!parsed.success) {
+    return publicProblem(context, {
+      type: 'automation-validation-failed',
+      status: 400,
+      title: 'Bad Request',
+      detail: parsed.error.message,
+    })
+  }
+
+  const repository = context.get('automationRepository')
+  const id = await repository.create({
+    seed_slug: parsed.data.seed_slug,
+    name: parsed.data.name,
+    triggers: parsed.data.triggers,
+    trigger_conditions: parsed.data.trigger_conditions ?? null,
+    actions: parsed.data.actions,
+  })
+  return context.json({ id }, 201)
+})
+
+/**
+ * GET /automations/:id
+ */
+automationsApp.get('/:id', async (context) => {
+  const id = context.req.param('id')
+  const automation = await context.get('automationRepository').findById(id)
+  if (!automation) {
+    return publicProblem(context, {
+      type: 'automation-not-found',
+      status: 404,
+      title: 'Not Found',
+      detail: `Automation ${id} does not exist`,
+    })
+  }
+  return context.json(automation)
+})
+
+/**
+ * PUT /automations/:id
+ * Full update — partial bodies allowed; cron expression validation
+ * is enforced by the triggers array schema.
+ */
+automationsApp.put('/:id', async (context) => {
+  const id = context.req.param('id')
+  const repository = context.get('automationRepository')
+  const existing = await repository.findById(id)
+  if (!existing) {
+    return publicProblem(context, {
+      type: 'automation-not-found',
+      status: 404,
+      title: 'Not Found',
+      detail: `Automation ${id} does not exist`,
+    })
+  }
+
+  let body: unknown
+  try {
+    body = await context.req.json()
+  } catch {
+    return publicProblem(context, {
+      type: 'invalid-json',
+      status: 400,
+      title: 'Bad Request',
+      detail: 'Request body is not valid JSON',
+    })
+  }
+
+  const parsed = updateAutomationSchema.safeParse(body)
+  if (!parsed.success) {
+    return publicProblem(context, {
+      type: 'automation-validation-failed',
+      status: 400,
+      title: 'Bad Request',
+      detail: parsed.error.message,
+    })
+  }
+
+  await repository.update(id, parsed.data)
+  return context.body(null, 204)
+})
+
+/**
+ * PATCH /automations/:id/toggle
+ * Atomic single-field flip — does not require sending the full body.
+ */
+automationsApp.patch('/:id/toggle', async (context) => {
+  const id = context.req.param('id')
+  const repository = context.get('automationRepository')
+  const existing = await repository.findById(id)
+  if (!existing) {
+    return publicProblem(context, {
+      type: 'automation-not-found',
+      status: 404,
+      title: 'Not Found',
+      detail: `Automation ${id} does not exist`,
+    })
+  }
+
+  let body: unknown
+  try {
+    body = await context.req.json()
+  } catch {
+    return publicProblem(context, {
+      type: 'invalid-json',
+      status: 400,
+      title: 'Bad Request',
+      detail: 'Request body is not valid JSON',
+    })
+  }
+
+  const parsed = toggleAutomationSchema.safeParse(body)
+  if (!parsed.success) {
+    return publicProblem(context, {
+      type: 'automation-validation-failed',
+      status: 400,
+      title: 'Bad Request',
+      detail: parsed.error.message,
+    })
+  }
+
+  await repository.toggle(id, parsed.data.enabled)
+  return context.body(null, 204)
+})
+
+/**
+ * DELETE /automations/:id
+ */
+automationsApp.delete('/:id', async (context) => {
+  const id = context.req.param('id')
+  const repository = context.get('automationRepository')
+  const existing = await repository.findById(id)
+  if (!existing) {
+    return publicProblem(context, {
+      type: 'automation-not-found',
+      status: 404,
+      title: 'Not Found',
+      detail: `Automation ${id} does not exist`,
+    })
+  }
+  await repository.delete(id)
+  return context.body(null, 204)
+})
+
+export { automationsApp }

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

@@ -0,0 +1,160 @@
+// Mirror: apps/dashboard/src/features/automations/schema/automation.schema.ts — keep structurally identical.
+import { z } from 'zod'
+import type { WhenNode } from '@beechcms/core'
+import { AUTOMATION_RESERVED_WORDS } from './template-grammar'
+
+// ---------------------------------------------------------------------------
+// Trigger conditions — recursive WhenNode schema (Task 14)
+// ---------------------------------------------------------------------------
+
+const whenOperandSchema = z.union([
+  z.object({ kind: z.literal('literal'), value: z.unknown() }),
+  z.object({ kind: z.literal('ref'), key: z.string().min(1) }),
+])
+
+const whenPredicateSchema = z.object({
+  kind: z.literal('predicate'),
+  left: whenOperandSchema,
+  op: z.enum(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'contains', 'startswith', 'endswith', 'in', 'notin', 'isempty', 'isnotempty', 'matches']),
+  right: whenOperandSchema.optional(),
+})
+
+const whenNodeSchema: z.ZodType<WhenNode> = z.lazy(() =>
+  z.union([
+    whenPredicateSchema,
+    z.object({
+      kind: z.literal('group'),
+      op: z.enum(['AND', 'OR']),
+      children: z.array(whenNodeSchema).min(1),
+      negate: z.boolean().optional(),
+    }).refine(
+      (g) => depthOf(g) <= 10,
+      { message: 'WhenNode nesting exceeds maximum depth of 10' },
+    ),
+  ]),
+)
+
+function depthOf(node: unknown, d = 0): number {
+  if (d > 10) return d
+  if (typeof node !== 'object' || !node) return d
+  const n = node as Record<string, unknown>
+  if (n['kind'] === 'group' && Array.isArray(n['children'])) {
+    return Math.max(...(n['children'] as unknown[]).map((c) => depthOf(c, d + 1)))
+  }
+  return d
+}
+
+const triggerConditionsSchema = whenNodeSchema.nullable().optional()
+
+const setVariableFilterSchema = z.object({
+  field: z.string().min(1),
+  op: z.enum(['eq', 'neq', 'contains', 'gt', 'lt', 'isempty', 'isnotempty']),
+  value: z.unknown(),
+})
+
+// ---------------------------------------------------------------------------
+// Action schemas
+// ---------------------------------------------------------------------------
+
+const setVariableActionSchema = z.object({
+  type: z.literal('set_variable'),
+  name: z
+    .string()
+    .min(1)
+    .regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/)
+    .refine((v) => !AUTOMATION_RESERVED_WORDS.has(v), {
+      message: 'automations.editor.errors.variableNameReserved',
+    }),
+  seed_slug: z.string().min(1).optional(),
+  fixed_id: z.string().min(1).optional(),
+  column: z.string().min(1).optional(),
+  filters: z.array(setVariableFilterSchema).default([]),
+  order_by: z.string().optional(),
+  order: z.enum(['asc', 'desc']).optional(),
+})
+
+const webhookActionSchema = z.object({
+  type: z.literal('webhook'),
+  url: z.string().url(),
+  method: z.enum(['POST', 'GET', 'PUT']).optional(),
+  headers: z.record(z.string(), z.string()).optional(),
+  body_template: z.string().optional(),
+})
+
+const sendMailActionSchema = z.object({
+  type: z.literal('send_mail'),
+  to: z.string().email(),
+  subject_template: z.string().min(1),
+  body_template: z.string().min(1),
+})
+
+const editFieldActionSchema = z.object({
+  type: z.literal('edit_field'),
+  field: z.string().min(1),
+  value: z.unknown(),
+})
+
+const createEntryActionSchema = z.object({
+  type: z.literal('create_entry'),
+  seed_slug: z.string().min(1),
+  field_map: z.record(z.string(), z.string()),
+})
+
+export const automationActionSchema = z.discriminatedUnion('type', [
+  setVariableActionSchema,
+  webhookActionSchema,
+  sendMailActionSchema,
+  editFieldActionSchema,
+  createEntryActionSchema,
+])
+
+// ---------------------------------------------------------------------------
+// Triggers schema
+// ---------------------------------------------------------------------------
+
+const automationTriggerSchema = z.object({
+  event: z.enum(['create', 'update', 'delete', 'cron']),
+  cron: z.string().nullable().optional(),
+})
+
+const triggersSchema = z
+  .array(automationTriggerSchema)
+  .min(1, 'At least one trigger is required')
+  .refine(
+    (triggers) => triggers.filter((t) => t.event === 'cron').length <= 1,
+    { message: 'Only one cron trigger is allowed per automation' },
+  )
+  .refine(
+    (triggers) => {
+      const events = triggers.map((t) => t.event)
+      return new Set(events).size === events.length
+    },
+    { message: 'Duplicate trigger events are not allowed' },
+  )
+  .refine(
+    (triggers) => triggers.every((t) => t.event !== 'cron' || !!t.cron),
+    { message: 'cron expression is required for cron triggers', path: ['cron'] },
+  )
+
+// ---------------------------------------------------------------------------
+// Automation create/update schemas
+// ---------------------------------------------------------------------------
+
+const createAutomationBaseSchema = z.object({
+  seed_slug: z.string().min(1),
+  name: z.string().min(1).max(100),
+  triggers: triggersSchema,
+  trigger_conditions: triggerConditionsSchema,
+  actions: z.array(automationActionSchema).min(1, 'At least one action is required'),
+})
+
+export const createAutomationSchema = createAutomationBaseSchema
+
+export const updateAutomationSchema = createAutomationBaseSchema.partial()
+
+export const toggleAutomationSchema = z.object({
+  enabled: z.boolean(),
+})
+
+export type CreateAutomationBody = z.infer<typeof createAutomationSchema>
+export type UpdateAutomationBody = z.infer<typeof updateAutomationSchema>