@beechcms/api 0.4.1 → 0.4.2

package/src/features/automations/context-resolver.ts

@@ -0,0 +1,148 @@
+import type { Automation } from '@beechcms/core'
+import type { AutomationContextSelector, ParsedKey } from './template-grammar'
+import { resolvePath } from './automation-runner.utils'
+
+export interface ResolvedContext {
+  lookup(key: ParsedKey, onMissing?: (field: string) => void): unknown
+  triggerEntry: Record<string, unknown> | null
+}
+
+const MAX_PLUCK = 100
+const AGGREGATE_OPS = new Set(['count', 'sum', 'avg', 'min', 'max', 'pluck'])
+
+function applyAggregate(
+  op: string,
+  field: string | null,
+  rows: Array<Record<string, unknown>>,
+  onMissing?: (f: string) => void,
+): unknown {
+  switch (op) {
+    case 'count':
+      return rows.length
+
+    case 'sum': {
+      if (!field) { if (onMissing) onMissing('sum:field'); return 0 }
+      return rows.reduce((acc, r) => {
+        const v = Number(r[field])
+        if (Number.isNaN(v)) { if (onMissing) onMissing(`sum:${field}:NaN`); return acc }
+        return acc + v
+      }, 0)
+    }
+
+    case 'avg': {
+      if (!field || rows.length === 0) { if (onMissing && !field) onMissing('avg:field'); return 0 }
+      const total = rows.reduce((acc, r) => {
+        const v = Number(r[field])
+        if (Number.isNaN(v)) { if (onMissing) onMissing(`avg:${field}:NaN`); return acc }
+        return acc + v
+      }, 0)
+      return rows.length > 0 ? total / rows.length : 0
+    }
+
+    case 'min': {
+      if (!field || rows.length === 0) { if (onMissing && !field) onMissing('min:field'); return null }
+      return rows.reduce<number | null>((acc, r) => {
+        const v = Number(r[field])
+        if (Number.isNaN(v)) return acc
+        return acc === null || v < acc ? v : acc
+      }, null)
+    }
+
+    case 'max': {
+      if (!field || rows.length === 0) { if (onMissing && !field) onMissing('max:field'); return null }
+      return rows.reduce<number | null>((acc, r) => {
+        const v = Number(r[field])
+        if (Number.isNaN(v)) return acc
+        return acc === null || v > acc ? v : acc
+      }, null)
+    }
+
+    case 'pluck': {
+      if (!field) { if (onMissing) onMissing('pluck:field'); return '' }
+      const values = rows.slice(0, MAX_PLUCK).map((r) => String(r[field] ?? ''))
+      const truncated = rows.length > MAX_PLUCK
+      return values.join(', ') + (truncated ? ' …' : '')
+    }
+
+    default:
+      return undefined
+  }
+}
+
+export async function resolveAutomationContext(
+  _automation: Automation,
+  triggerEntry: Record<string, unknown> | null,
+  batchEntries: Array<Record<string, unknown>>,
+): Promise<ResolvedContext> {
+  function lookup(parsed: ParsedKey, onMissing?: (field: string) => void): unknown {
+    if (parsed.kind === 'simple') {
+      if (parsed.path.startsWith('this.')) {
+        const field = parsed.path.slice(5)
+        const val = resolvePath(triggerEntry ?? {}, field)
+        if (val === undefined && onMissing) onMissing(parsed.path)
+        return val
+      }
+      const val = resolvePath(triggerEntry ?? {}, parsed.path)
+      if (val === undefined && onMissing) onMissing(parsed.path)
+      return val
+    }
+
+    if (parsed.kind !== 'scoped') {
+      if (onMissing) onMissing(parsed.kind === 'var_access' ? parsed.name : 'unknown')
+      return undefined
+    }
+
+    const { scope, selector: _selector, op, field } = parsed
+
+    if (scope === 'this') {
+      if (op !== 'field' || !field) { if (onMissing) onMissing(`this.${field}`); return undefined }
+      const val = resolvePath(triggerEntry ?? {}, field)
+      if (val === undefined && onMissing) onMissing(`this.${field}`)
+      return val
+    }
+
+    if (scope === 'batch') {
+      if (op === 'field') {
+        if (!field) { if (onMissing) onMissing('batch.field'); return undefined }
+        const val = resolvePath(batchEntries[0] ?? {}, field)
+        if (val === undefined && onMissing) onMissing(`batch.${field}`)
+        return val
+      }
+      return applyAggregate(op, field, batchEntries, onMissing)
+    }
+
+    if (onMissing) onMissing(scope)
+    return undefined
+  }
+
+  return { lookup, triggerEntry }
+}
+
+export function deriveEntryContext(
+  base: ResolvedContext,
+  entry: Record<string, unknown>,
+): ResolvedContext {
+  return {
+    lookup(parsed: ParsedKey, onMissing?: (field: string) => void): unknown {
+      if (parsed.kind === 'simple') {
+        if (parsed.path.startsWith('this.')) {
+          const field = parsed.path.slice(5)
+          const val = resolvePath(entry, field)
+          if (val === undefined && onMissing) onMissing(parsed.path)
+          return val
+        }
+        const val = resolvePath(entry, parsed.path)
+        if (val === undefined && onMissing) onMissing(parsed.path)
+        return val
+      }
+      if (parsed.kind === 'scoped' && parsed.scope === 'this') {
+        if (parsed.op !== 'field' || !parsed.field) { if (onMissing) onMissing('this.field'); return undefined }
+        const val = resolvePath(entry, parsed.field)
+        if (val === undefined && onMissing) onMissing(`this.${parsed.field}`)
+        return val
+      }
+      return base.lookup(parsed, onMissing)
+    },
+    triggerEntry: entry,
+  }
+}

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

@@ -0,0 +1,136 @@
+import type {
+  Automation,
+  ContentRepository,
+  FilterGroup,
+  IAutomationRepository,
+  IIdGenerator,
+  Seed,
+} from '@beechcms/core'
+import { cronMatches } from './cron-runner.utils'
+import { executeAction } from './action-executors'
+import { resolveAutomationContext, deriveEntryContext } from './context-resolver'
+import { extractPushdownFilters } from './when-pushdown'
+import { evaluateWhen } from './when-evaluator'
+
+export interface CronRunnerDeps {
+  automationRepository: IAutomationRepository
+  contentRepository: ContentRepository
+  getSeed: (slug: string) => Seed | null
+  env: Record<string, string | undefined>
+  idGenerator: IIdGenerator
+}
+
+// These actions mutate individual entries and must run once per entry.
+// All other actions (send_mail, webhook) run once per automation with a batch context.
+const PER_ENTRY_ACTIONS = new Set(['edit_field', 'create_entry'])
+
+export async function runCronAutomations(
+  deps: CronRunnerDeps,
+  scheduledTime: number,
+): Promise<void> {
+  console.log(`[cron] Starting runCronAutomations at scheduledTime: ${new Date(scheduledTime).toISOString()}`)
+
+  let automations: Automation[]
+  try {
+    automations = await deps.automationRepository.findActive('*', 'cron')
+  } catch (err) {
+    console.error('[cron] Failed to fetch automations — is migration 0029_automations.sql applied?', err)
+    return
+  }
+
+  console.log(`[cron] Found ${automations.length} active cron automation(s)`)
+
+  for (const automation of automations) {
+    const cronTrigger = automation.triggers.find((t) => t.event === 'cron')
+    if (!cronMatches(cronTrigger?.cron ?? null, scheduledTime)) {
+      console.log(`[cron] Skipping "${automation.name}": cron expression "${cronTrigger?.cron}" does not match.`)
+      continue
+    }
+
+    const seed = deps.getSeed(automation.seed_slug)
+    if (!seed) {
+      console.warn('[cron] unknown seed', { automationId: automation.id, seedSlug: automation.seed_slug })
+      continue
+    }
+
+    let entries: Array<Record<string, unknown>> = []
+    try {
+      entries = await fetchMatchingEntries(deps.contentRepository, seed, automation)
+      console.log(`[cron] Fetched ${entries.length} matching entries for automation "${automation.name}"`)
+    } catch (err) {
+      console.error('[cron] fetch entries failed', { automationId: automation.id, err })
+      continue
+    }
+
+    if (entries.length === 0) continue
+
+    // Build the base ResolvedContext once per automation (shared seed-query cache).
+    // triggerEntry = first entry; batchEntries = full SQL-filtered list.
+    const batchResolved = await resolveAutomationContext(
+      automation,
+      entries[0] ?? null,
+      entries,
+    )
+
+    const variables: Record<string, unknown> = {}
+    const baseCtx = {
+      env: deps.env,
+      repository: deps.contentRepository,
+      getSeed: deps.getSeed,
+      seed,
+      idGenerator: deps.idGenerator,
+      variables,
+    }
+
+    for (const action of automation.actions) {
+      if (PER_ENTRY_ACTIONS.has(action.type)) {
+        for (const entry of entries) {
+          // Per-entry: derive a lightweight context whose `this` is the current entry.
+          // Seed-query cache is reused from batchResolved.
+          const entryResolved = deriveEntryContext(batchResolved, entry)
+          // In-memory per-entry condition check (Task 13)
+          if (!evaluateWhen(automation.trigger_conditions, entryResolved)) continue
+          try {
+            await executeAction(action, { ...baseCtx, entry, context: entryResolved })
+          } catch (err) {
+            console.error('[cron] entry action failed', {
+              automationId: automation.id,
+              entryId: entry['id'],
+              actionType: action.type,
+              err,
+            })
+          }
+        }
+      } else {
+        // Batch actions run once per automation with the shared batch context.
+        try {
+          await executeAction(action, { ...baseCtx, entry: entries[0] ?? {}, context: batchResolved })
+        } catch (err) {
+          console.error('[cron] batch action failed', {
+            automationId: automation.id,
+            actionType: action.type,
+            err,
+          })
+        }
+      }
+    }
+  }
+}
+
+async function fetchMatchingEntries(
+  repository: ContentRepository,
+  seed: Seed,
+  automation: Automation,
+): Promise<Array<Record<string, unknown>>> {
+  // Task 12: push down only safe predicates to SQL (this.<field> = literal, AND group only).
+  // OR branches, cross-seed refs, and gte/lte/etc. ops are evaluated in-memory by evaluateWhen().
+  const filters: FilterGroup[] = automation.trigger_conditions
+    ? extractPushdownFilters(automation.trigger_conditions, seed)
+    : []
+  const result = await repository.findMany(seed, {
+    filters,
+    status: null,
+    pagination: { limit: 1000, offset: 0 },
+  })
+  return result.items
+}

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

@@ -0,0 +1,40 @@
+export function cronMatches(expression: string | null, scheduledTime: number): boolean {
+  if (!expression) return false
+  const parts = expression.trim().split(/\s+/)
+  if (parts.length !== 5) return false
+
+  const d = new Date(scheduledTime)
+  const actual = [
+    d.getUTCMinutes(),
+    d.getUTCHours(),
+    d.getUTCDate(),
+    d.getUTCMonth() + 1,
+    d.getUTCDay(),
+  ] as const
+
+  return parts.every((field, i) => matchField(field, actual[i]))
+}
+
+function matchField(field: string, value: number): boolean {
+  if (field === '*') return true
+  if (field.includes(',')) {
+    return field.split(',').some((part) => matchField(part, value))
+  }
+  if (field.includes('/')) {
+    const [rangePart, stepPart] = field.split('/')
+    const step = Number(stepPart)
+    if (!Number.isFinite(step) || step <= 0) return false
+    if (rangePart === '*') return value % step === 0
+    if (rangePart.includes('-')) {
+      const [lo, hi] = rangePart.split('-').map(Number)
+      return value >= lo && value <= hi && (value - lo) % step === 0
+    }
+    return false
+  }
+  if (field.includes('-')) {
+    const [lo, hi] = field.split('-').map(Number)
+    return Number.isFinite(lo) && Number.isFinite(hi) && value >= lo && value <= hi
+  }
+  const n = Number(field)
+  return Number.isFinite(n) && n === value
+}

package/src/features/automations/filter-translation.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared helper: converts a TriggerCondition into a FilterGroup accepted by
+ * ContentRepository.findMany. Used by cron-runner and context-resolver.
+ *
+ * TODO Sprint 8 (Task 12): when-pushdown.ts will call extractPushdownFilters
+ * to convert safe WhenNode predicates to FilterGroup[] for SQL pre-filtering.
+ */
+import type { BranchType, FilterGroup, FilterOperator, FilterType, Seed, TriggerCondition } from '@beechcms/core'
+
+const SYSTEM_COLUMNS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at'])
+
+function mapBranchTypeToFilterType(type: BranchType): FilterType {
+  switch (type) {
+    case 'number': return 'number'
+    case 'boolean': return 'boolean'
+    case 'date': return 'date'
+    case 'tags': return 'tags'
+    case 'json': return 'json'
+    default: return 'text'
+  }
+}
+
+function mapOp(op: TriggerCondition['op']): FilterOperator {
+  switch (op) {
+    case 'isempty': return 'is_empty'
+    case 'isnotempty': return 'is_not_empty'
+    default: return op
+  }
+}
+
+export function conditionToFilterGroup(c: TriggerCondition, seed: Seed): FilterGroup {
+  const branch = seed.branches.find((b) => b.alias === c.field)
+  const type: FilterType = branch
+    ? mapBranchTypeToFilterType(branch.type)
+    : SYSTEM_COLUMNS.has(c.field) ? 'system' : 'text'
+
+  return {
+    column: c.field,
+    type,
+    conditions: [{ op: mapOp(c.op), value: c.value as string | number | boolean | null }],
+  }
+}

package/src/features/automations/index.ts

@@ -0,0 +1,12 @@
+export { AutomationRunner } from './automation-runner'
+export type { AutomationRunnerDeps } from './automation-runner'
+export { runCronAutomations } from './cron-runner'
+export type { CronRunnerDeps } from './cron-runner'
+export { automationsApp } from './automations.handler'
+export {
+  createAutomationSchema,
+  updateAutomationSchema,
+  toggleAutomationSchema,
+  automationActionSchema,
+} from './automations.schema'
+export type { CreateAutomationBody, UpdateAutomationBody } from './automations.schema'

package/src/features/automations/template-grammar.ts

@@ -0,0 +1,241 @@
+/**
+ * Pure template-key parser for the automation template engine.
+ *
+ * Grammar (Sprint 6):
+ *   simple:  {{title}}, {{author.name}}
+ *   scoped:  {{<scope>:<selector>:<field>}}
+ *
+ * Grammar (Sprint 7):
+ *   var_access: {{varname.firstone.campo}}, {{varname.count.(status=paid)}}
+ *               {{varname.array[id1,id2].count}}
+ *
+ * Scopes: this | batch | <seedSlug> | <contextKey>
+ * Selectors: lastone | firstone | all | byid(<id>) | where(<alias>=<value>)
+ * Fields: branch alias, system column, or aggregate (count/sum/avg/min/max/pluck)
+ *
+ * Sugar:
+ *   {{batch:count}}        → batch:all:count
+ *   {{<scope>:<field>}}    → <scope>:lastone:<field>  (default selector)
+ *
+ * TODO Sprint 8: extend ParsedKey to support WhenOperand refs once the
+ * recursive when-group evaluator (Tasks 10-16) is implemented.
+ */
+
+export { AUTOMATION_RESERVED_WORDS } from '@beechcms/core'
+
+// ---------------------------------------------------------------------------
+// Sprint 7 types: var_access parsed key
+// ---------------------------------------------------------------------------
+
+export type VarStep =
+  | { type: 'field'; name: string }
+  | { type: 'nav'; nav: 'firstone' | 'lastone' }
+  | { type: 'agg'; op: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'pluck'; field?: string }
+  | { type: 'array'; ids: string[] }
+
+export interface InlineCondition {
+  column: string
+  op: '=' | '!=' | '<' | '>' | '<=' | '>='
+  value: string
+}
+
+// ---------------------------------------------------------------------------
+
+export type AutomationContextSelector =
+  | { kind: 'lastone' }
+  | { kind: 'firstone' }
+  | { kind: 'all' }
+  | { kind: 'byid'; id: string }
+  | { kind: 'where'; alias: string; value: string }
+
+export type AggregateOp = 'count' | 'sum' | 'avg' | 'min' | 'max' | 'pluck'
+
+export type ParsedKey =
+  | { kind: 'simple'; path: string }
+  | {
+      kind: 'scoped'
+      scope: string
+      selector: AutomationContextSelector
+      op: 'field' | AggregateOp
+      field: string | null
+    }
+  | {
+      kind: 'var_access'
+      name: string
+      steps: VarStep[]
+      conditions: InlineCondition[]
+    }
+
+const SLUG_RE = /^[a-zA-Z0-9_-]+$/
+const AGGREGATE_OPS = new Set<string>(['count', 'sum', 'avg', 'min', 'max', 'pluck'])
+const NAV_OPS = new Set<string>(['firstone', 'lastone'])
+const INLINE_COND_RE = /^\(([\w]+)\s*(=|!=|<=|>=|<|>)\s*([^)]+)\)$/
+
+/**
+ * Split `raw` on `:` but treat content inside `(...)` as atomic.
+ */
+function splitKey(raw: string): string[] {
+  const tokens: string[] = []
+  let depth = 0
+  let current = ''
+
+  for (const ch of raw) {
+    if (ch === '(') {
+      depth++
+      current += ch
+    } else if (ch === ')') {
+      depth--
+      current += ch
+    } else if (ch === ':' && depth === 0) {
+      tokens.push(current)
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  if (current) tokens.push(current)
+  return tokens
+}
+
+/**
+ * Split `raw` on `.` treating `[...]` and `(...)` as atomic blocks.
+ */
+function splitDot(raw: string): string[] {
+  const tokens: string[] = []
+  let depth = 0
+  let current = ''
+
+  for (const ch of raw) {
+    if (ch === '[' || ch === '(') {
+      depth++
+      current += ch
+    } else if (ch === ']' || ch === ')') {
+      depth--
+      current += ch
+    } else if (ch === '.' && depth === 0) {
+      tokens.push(current)
+      current = ''
+    } else {
+      current += ch
+    }
+  }
+  if (current) tokens.push(current)
+  return tokens
+}
+
+function parseSelector(token: string): AutomationContextSelector | null {
+  if (token === 'lastone') return { kind: 'lastone' }
+  if (token === 'firstone') return { kind: 'firstone' }
+  if (token === 'all') return { kind: 'all' }
+
+  const byidMatch = token.match(/^byid\((.+)\)$/)
+  if (byidMatch) return { kind: 'byid', id: byidMatch[1] }
+
+  const whereMatch = token.match(/^where\(([^=]+)=(.+)\)$/)
+  if (whereMatch) return { kind: 'where', alias: whereMatch[1], value: whereMatch[2] }
+
+  return null
+}
+
+function isKnownScope(token: string): boolean {
+  return token === 'this' || token === 'batch' || SLUG_RE.test(token)
+}
+
+export function parseTemplateKey(raw: string): ParsedKey | null {
+  if (!raw) return null
+
+  const trimmed = raw.trim()
+
+  // Step 1: if contains `:` at depth 0 → existing scoped / sugar logic
+  const colonTokens = splitKey(trimmed)
+  if (colonTokens.length > 1) {
+    const [scopeToken, ...rest] = colonTokens
+    if (!isKnownScope(scopeToken)) return null
+
+    if (rest.length === 1) {
+      const fieldOrAggregate = rest[0]
+      if (AGGREGATE_OPS.has(fieldOrAggregate)) {
+        return { kind: 'scoped', scope: scopeToken, selector: { kind: 'all' }, op: fieldOrAggregate as AggregateOp, field: null }
+      }
+      return { kind: 'scoped', scope: scopeToken, selector: { kind: 'lastone' }, op: 'field', field: fieldOrAggregate }
+    }
+
+    const selectorToken = rest[0]
+    const selector = parseSelector(selectorToken)
+    if (!selector) return null
+
+    const fieldTokens = rest.slice(1)
+    if (fieldTokens.length === 0) return null
+
+    const opToken = fieldTokens[0]
+    if (AGGREGATE_OPS.has(opToken)) {
+      if (selector.kind !== 'all') return null
+      const subField = fieldTokens[1] ?? null
+      return { kind: 'scoped', scope: scopeToken, selector, op: opToken as AggregateOp, field: subField }
+    }
+
+    return { kind: 'scoped', scope: scopeToken, selector, op: 'field', field: opToken }
+  }
+
+  // Step 2: tokenise on `.` at depth 0
+  const dotTokens = splitDot(trimmed)
+
+  // Step 3: if no token contains `[` or `(`, return simple (fast path)
+  if (!dotTokens.some((t) => t.includes('[') || t.includes('('))) {
+    return { kind: 'simple', path: trimmed }
+  }
+
+  // Step 4: build var_access
+  const [nameToken, ...stepTokens] = dotTokens
+  const steps: VarStep[] = []
+  const conditions: InlineCondition[] = []
+
+  let i = 0
+  while (i < stepTokens.length) {
+    const token = stepTokens[i]
+
+    // Inline condition: (col op val)
+    const condMatch = token.match(INLINE_COND_RE)
+    if (condMatch) {
+      conditions.push({ column: condMatch[1], op: condMatch[2] as InlineCondition['op'], value: condMatch[3].trim() })
+      i++
+      continue
+    }
+
+    // Array selector: array[id1,id2,...]
+    const arrayMatch = token.match(/^array\[([^\]]*)\]$/)
+    if (arrayMatch) {
+      const ids = arrayMatch[1].split(',').map((s) => s.trim()).filter(Boolean)
+      steps.push({ type: 'array', ids })
+      i++
+      continue
+    }
+
+    // Nav: firstone / lastone
+    if (NAV_OPS.has(token)) {
+      steps.push({ type: 'nav', nav: token as 'firstone' | 'lastone' })
+      i++
+      continue
+    }
+
+    // Aggregate: count | sum | avg | min | max | pluck
+    if (AGGREGATE_OPS.has(token)) {
+      const nextToken = stepTokens[i + 1]
+      // Consume the next token as field if it's a plain identifier (no special chars)
+      if (nextToken && !nextToken.includes('[') && !nextToken.includes('(') && !AGGREGATE_OPS.has(nextToken) && !NAV_OPS.has(nextToken)) {
+        steps.push({ type: 'agg', op: token as VarStep & { type: 'agg' } extends { op: infer O } ? O : never, field: nextToken })
+        i += 2
+      } else {
+        steps.push({ type: 'agg', op: token as any })
+        i++
+      }
+      continue
+    }
+
+    // Plain field
+    steps.push({ type: 'field', name: token })
+    i++
+  }
+
+  return { kind: 'var_access', name: nameToken, steps, conditions }
+}