@manablox/workflows 0.2.0

package/src/validate.ts

@@ -0,0 +1,267 @@
+import { randomUUID } from 'node:crypto';
+import {
+  type ErrorDetail,
+  isEmailAddress,
+  ManabloxError,
+  WORKFLOW_CONDITION_OPERATORS,
+  WORKFLOW_EVENTS,
+  WORKFLOW_STEP_TYPES,
+  type WorkflowStep,
+  type WorkflowTrigger,
+} from '@manablox/core';
+import { isValidCron, isValidTimezone } from './cron.js';
+
+/** What the editor hands over: a workflow as typed, before it is trusted. */
+export interface WorkflowInput {
+  name: string;
+  description?: string | null | undefined;
+  enabled?: boolean | undefined;
+  trigger: WorkflowTrigger;
+  steps: WorkflowStep[];
+}
+
+export interface ValidatedWorkflow {
+  name: string;
+  description: string | null;
+  enabled: boolean;
+  trigger: WorkflowTrigger;
+  steps: WorkflowStep[];
+}
+
+export interface ValidationEnvironment {
+  /** Whether a content type id names a type of this space (or a code-defined one). */
+  typeExists: (typeId: string) => boolean;
+}
+
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const MAX_DELAY_MINUTES = 60 * 24 * 30;
+
+/**
+ * Checks everything the shape alone cannot: an event that exists, a cron that parses, a
+ * step with somewhere to send to. Every problem is reported at once, each with the path
+ * of the field it concerns, so the editor can mark them all in one round.
+ */
+export function validateWorkflow(
+  input: WorkflowInput,
+  env: ValidationEnvironment,
+): ValidatedWorkflow {
+  const problems: ErrorDetail[] = [];
+  const add = (
+    key: ErrorDetail['key'],
+    path: (string | number)[],
+    params?: Record<string, unknown>,
+  ) => problems.push({ key, path, ...(params ? { params } : {}) });
+
+  const name = input.name.trim();
+  if (!name) add('workflow.name.required', ['name']);
+
+  const trigger = validateTrigger(input.trigger, env, add);
+  const steps = validateSteps(input.steps, ['steps'], add);
+  if (steps.length === 0) add('workflow.steps.required', ['steps']);
+
+  if (problems.length) throw ManabloxError.validation(problems, 'workflow.validation.failed');
+
+  return {
+    name,
+    description: input.description?.trim() || null,
+    enabled: input.enabled ?? false,
+    trigger,
+    steps,
+  };
+}
+
+type Add = (
+  key: ErrorDetail['key'],
+  path: (string | number)[],
+  params?: Record<string, unknown>,
+) => void;
+
+function validateTrigger(
+  trigger: WorkflowTrigger,
+  env: ValidationEnvironment,
+  add: Add,
+): WorkflowTrigger {
+  if (trigger.kind === 'schedule') {
+    if (!isValidCron(trigger.cron)) add('workflow.trigger.cronInvalid', ['trigger', 'cron']);
+    if (!isValidTimezone(trigger.timezone)) {
+      add('workflow.trigger.timezoneInvalid', ['trigger', 'timezone']);
+    }
+    for (const [index, typeId] of (trigger.selection?.typeIds ?? []).entries()) {
+      if (!env.typeExists(typeId)) {
+        add('workflow.trigger.typeNotFound', ['trigger', 'selection', 'typeIds', index], {
+          typeId,
+        });
+      }
+    }
+    return {
+      kind: 'schedule',
+      cron: trigger.cron.trim(),
+      timezone: trigger.timezone,
+      selection: trigger.selection
+        ? {
+            typeIds: trigger.selection.typeIds,
+            status: trigger.selection.status,
+            changedWithinHours: trigger.selection.changedWithinHours ?? null,
+            locale: trigger.selection.locale || null,
+          }
+        : null,
+      perDocument: Boolean(trigger.perDocument && trigger.selection),
+    };
+  }
+
+  const events = [...new Set(trigger.events)];
+  if (events.length === 0) add('workflow.trigger.eventsRequired', ['trigger', 'events']);
+  for (const [index, event] of events.entries()) {
+    if (!(WORKFLOW_EVENTS as readonly string[]).includes(event)) {
+      add('workflow.trigger.eventUnknown', ['trigger', 'events', index], { event });
+    }
+  }
+  for (const [index, typeId] of trigger.typeIds.entries()) {
+    if (!env.typeExists(typeId)) {
+      add('workflow.trigger.typeNotFound', ['trigger', 'typeIds', index], { typeId });
+    }
+  }
+  return { kind: 'event', events, typeIds: trigger.typeIds, locales: trigger.locales ?? [] };
+}
+
+/** Checks every step of a chain, recursing into the two sides of a fork. */
+function validateSteps(
+  steps: WorkflowStep[],
+  prefix: (string | number)[],
+  add: Add,
+): WorkflowStep[] {
+  return steps.map((step, index) => validateStep(step, [...prefix, index], add));
+}
+
+function validateRules(
+  step: {
+    match: 'all' | 'any';
+    rules: WorkflowStep extends infer S ? (S extends { rules: infer R } ? R : never) : never;
+  },
+  at: (...rest: (string | number)[]) => (string | number)[],
+  add: Add,
+) {
+  if (step.rules.length === 0) add('workflow.step.condition.rulesRequired', at('rules'));
+  for (const [i, rule] of step.rules.entries()) {
+    if (!rule.field.trim()) add('workflow.step.condition.fieldRequired', at('rules', i, 'field'));
+    if (!(WORKFLOW_CONDITION_OPERATORS as readonly string[]).includes(rule.operator)) {
+      add('workflow.step.typeUnknown', at('rules', i, 'operator'), { type: rule.operator });
+    }
+  }
+  return {
+    match: step.match === 'any' ? ('any' as const) : ('all' as const),
+    rules: step.rules.map((rule) => ({
+      field: rule.field.trim(),
+      operator: rule.operator,
+      value: rule.value ?? '',
+    })),
+  };
+}
+
+function validateStep(step: WorkflowStep, path: (string | number)[], add: Add): WorkflowStep {
+  const at = (...rest: (string | number)[]) => [...path, ...rest];
+  const base = {
+    id: step.id || randomUUID(),
+    name: (step.name ?? '').trim(),
+    enabled: step.enabled ?? true,
+    continueOnError: step.continueOnError ?? false,
+  };
+
+  if (!(WORKFLOW_STEP_TYPES as readonly string[]).includes(step.type)) {
+    add('workflow.step.typeUnknown', at('type'), { type: (step as { type: string }).type });
+    return step;
+  }
+
+  switch (step.type) {
+    case 'email': {
+      const to = step.to.map((address) => address.trim()).filter(Boolean);
+      const toRoles = step.toRoles.map((role) => role.trim()).filter(Boolean);
+      if (to.length === 0 && toRoles.length === 0) {
+        add('workflow.step.email.recipientRequired', at('to'));
+      }
+      for (const [i, address] of to.entries()) {
+        // A template such as `{{ actor.email }}` is checked when it is rendered.
+        if (!address.includes('{{') && !isEmailAddress(address)) {
+          add('workflow.step.email.recipientInvalid', at('to', i), { address });
+        }
+      }
+      if (!step.subject.trim()) add('workflow.step.email.subjectRequired', at('subject'));
+      return {
+        ...base,
+        type: 'email',
+        to,
+        toRoles,
+        subject: step.subject.trim(),
+        body: step.body ?? '',
+        html: Boolean(step.html),
+      };
+    }
+    case 'http': {
+      const url = step.url.trim();
+      if (!url.includes('{{') && !isHttpUrl(url)) add('workflow.step.http.urlInvalid', at('url'));
+      if (url.includes('{{') && !/^https?:\/\//i.test(url)) {
+        add('workflow.step.http.urlInvalid', at('url'));
+      }
+      const headers = step.headers
+        .map((header) => ({ name: header.name.trim(), value: header.value }))
+        .filter((header) => header.name || header.value.trim());
+      for (const [i, header] of headers.entries()) {
+        if (!HEADER_NAME.test(header.name)) {
+          add('workflow.step.http.headerNameInvalid', at('headers', i, 'name'), {
+            name: header.name,
+          });
+        }
+      }
+      return {
+        ...base,
+        type: 'http',
+        method: step.method,
+        url,
+        headers,
+        body: { mode: step.body?.mode ?? 'event', template: step.body?.template ?? '' },
+        secret: step.secret?.trim() || null,
+        timeoutMs: clamp(step.timeoutMs ?? 10_000, 1_000, 120_000),
+      };
+    }
+    case 'push': {
+      if (!step.title.trim()) add('workflow.step.push.titleRequired', at('title'));
+      return {
+        ...base,
+        type: 'push',
+        roles: step.roles.map((role) => role.trim()).filter(Boolean),
+        userIds: step.userIds.filter(Boolean),
+        title: step.title.trim(),
+        body: step.body ?? '',
+        url: step.url?.trim() ?? '',
+      };
+    }
+    case 'condition':
+      return { ...base, type: 'condition', ...validateRules(step, at, add) };
+    case 'branch':
+      return {
+        ...base,
+        type: 'branch',
+        ...validateRules(step, at, add),
+        then: validateSteps(step.then ?? [], at('then'), add),
+        else: validateSteps(step.else ?? [], at('else'), add),
+      };
+    case 'delay': {
+      const minutes = Number(step.minutes);
+      if (!Number.isFinite(minutes) || minutes < 1 || minutes > MAX_DELAY_MINUTES) {
+        add('workflow.step.delay.minutesInvalid', at('minutes'), { max: MAX_DELAY_MINUTES });
+      }
+      return { ...base, type: 'delay', minutes: Math.round(minutes) };
+    }
+  }
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));

package/test/conditions.test.ts

@@ -0,0 +1,80 @@
+import type { WorkflowConditionStep, WorkflowRunContext } from '@manablox/core';
+import { describe, expect, it } from 'vitest';
+import { evaluateCondition, evaluateRule } from '../src/conditions.js';
+
+const base: WorkflowRunContext = {
+  event: 'content.updated',
+  workflow: { id: 'w', name: 'W' },
+  space: { id: 's', name: 'S', machineName: 's', url: '' },
+  content: { status: 'published', title: 'Launch', fields: { tags: ['news'], score: 7, note: '' } },
+  previous: { status: 'draft', title: 'Launch', fields: { tags: ['news'], score: 5, note: '' } },
+  documents: [],
+  actor: { id: 'u', name: 'Ann', email: 'ann@example.com' },
+  url: null,
+  at: '2026-09-06T00:00:00.000Z',
+};
+
+const rule = (
+  field: string,
+  operator: WorkflowConditionStep['rules'][number]['operator'],
+  value = '',
+) => evaluateRule({ field, operator, value }, base);
+
+describe('evaluateRule', () => {
+  it('compares loosely across types', () => {
+    expect(rule('content.status', 'equals', 'published')).toBe(true);
+    expect(rule('content.fields.score', 'equals', '7')).toBe(true);
+    expect(rule('content.status', 'notEquals', 'draft')).toBe(true);
+    expect(rule('content.fields.tags', 'contains', 'news')).toBe(true);
+    expect(rule('content.title', 'contains', 'LAUNCH')).toBe(true);
+    expect(rule('content.title', 'startsWith', 'la')).toBe(true);
+    expect(rule('content.fields.note', 'isEmpty')).toBe(true);
+    expect(rule('content.fields.tags', 'isNotEmpty')).toBe(true);
+    expect(rule('content.fields.score', 'greaterThan', '6')).toBe(true);
+    expect(rule('content.fields.score', 'lessThan', '6')).toBe(false);
+    expect(rule('content.missing', 'isEmpty')).toBe(true);
+  });
+
+  it('reads the previous row for "changed"', () => {
+    expect(rule('content.status', 'changed')).toBe(true);
+    expect(rule('content.title', 'changed')).toBe(false);
+    expect(rule('content.fields.score', 'changed')).toBe(true);
+    expect(rule('content.fields.tags', 'changed')).toBe(false);
+  });
+
+  it('treats everything as changed without a previous row', () => {
+    expect(
+      evaluateRule(
+        { field: 'content.title', operator: 'changed', value: '' },
+        { ...base, previous: null },
+      ),
+    ).toBe(true);
+  });
+
+  it('renders the expected side as a template', () => {
+    expect(rule('actor.email', 'equals', '{{ actor.email }}')).toBe(true);
+  });
+});
+
+describe('evaluateCondition', () => {
+  const step = (
+    match: 'all' | 'any',
+    ...rules: WorkflowConditionStep['rules']
+  ): WorkflowConditionStep => ({
+    id: 'c',
+    name: '',
+    enabled: true,
+    continueOnError: false,
+    type: 'condition',
+    match,
+    rules,
+  });
+
+  it('combines rules', () => {
+    const yes = { field: 'content.status', operator: 'equals', value: 'published' } as const;
+    const no = { field: 'content.status', operator: 'equals', value: 'draft' } as const;
+    expect(evaluateCondition(step('all', yes, no), base)).toBe(false);
+    expect(evaluateCondition(step('any', yes, no), base)).toBe(true);
+    expect(evaluateCondition(step('all'), base)).toBe(true);
+  });
+});

package/test/cron.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { cronMatches, floorToMinute, isValidTimezone, parseCron, wallClock } from '../src/cron.js';
+
+const at = (iso: string) => new Date(iso);
+
+describe('parseCron', () => {
+  it('accepts the common forms', () => {
+    expect(parseCron('* * * * *')).not.toBeNull();
+    expect(parseCron('0 8 * * 1-5')).not.toBeNull();
+    expect(parseCron('*/15 * * * *')).not.toBeNull();
+    expect(parseCron('0 0 1 jan,jul *')).not.toBeNull();
+    expect(parseCron('30 6 * * sun')).not.toBeNull();
+    expect(parseCron('5/10 * * * *')?.minute).toEqual(new Set([5, 15, 25, 35, 45, 55]));
+  });
+
+  it('rejects what it cannot read', () => {
+    expect(parseCron('')).toBeNull();
+    expect(parseCron('* * * *')).toBeNull();
+    expect(parseCron('60 * * * *')).toBeNull();
+    expect(parseCron('* 24 * * *')).toBeNull();
+    expect(parseCron('*/0 * * * *')).toBeNull();
+    expect(parseCron('a b c d e')).toBeNull();
+    expect(parseCron('5-3 * * * *')).toBeNull();
+  });
+
+  it('treats 7 as Sunday', () => {
+    expect(parseCron('0 0 * * 7')?.dayOfWeek).toEqual(new Set([0]));
+  });
+});
+
+describe('cronMatches', () => {
+  it('matches a plain minute', () => {
+    const spec = parseCron('30 14 * * *')!;
+    expect(cronMatches(spec, at('2026-09-06T14:30:00Z'), 'UTC')).toBe(true);
+    expect(cronMatches(spec, at('2026-09-06T14:31:00Z'), 'UTC')).toBe(false);
+  });
+
+  it('reads the wall-clock in the workflow timezone', () => {
+    const spec = parseCron('0 8 * * *')!;
+    // 08:00 in Vienna during summer time is 06:00 UTC.
+    expect(cronMatches(spec, at('2026-07-01T06:00:00Z'), 'Europe/Vienna')).toBe(true);
+    expect(cronMatches(spec, at('2026-07-01T08:00:00Z'), 'Europe/Vienna')).toBe(false);
+    expect(cronMatches(spec, at('2026-07-01T08:00:00Z'), 'UTC')).toBe(true);
+  });
+
+  it('crosses the date line correctly for weekdays', () => {
+    // Saturday 23:30 in Los Angeles is Sunday 06:30 UTC.
+    const clock = wallClock(at('2026-09-06T06:30:00Z'), 'America/Los_Angeles');
+    expect(clock).toMatchObject({ hour: 23, minute: 30, dayOfWeek: 6, dayOfMonth: 5 });
+  });
+
+  it('combines the day fields like Vixie cron', () => {
+    // Either the 1st of the month or a Monday.
+    const spec = parseCron('0 0 1 * 1')!;
+    expect(cronMatches(spec, at('2026-09-01T00:00:00Z'), 'UTC')).toBe(true); // Tuesday the 1st
+    expect(cronMatches(spec, at('2026-09-07T00:00:00Z'), 'UTC')).toBe(true); // Monday the 7th
+    expect(cronMatches(spec, at('2026-09-08T00:00:00Z'), 'UTC')).toBe(false);
+    // With `*` in day-of-month, only the weekday counts.
+    expect(cronMatches(parseCron('0 0 * * 1')!, at('2026-09-01T00:00:00Z'), 'UTC')).toBe(false);
+  });
+
+  it('handles midnight as hour 0', () => {
+    expect(cronMatches(parseCron('0 0 * * *')!, at('2026-09-06T00:00:00Z'), 'UTC')).toBe(true);
+  });
+});
+
+describe('helpers', () => {
+  it('validates timezones', () => {
+    expect(isValidTimezone('UTC')).toBe(true);
+    expect(isValidTimezone('Europe/Vienna')).toBe(true);
+    expect(isValidTimezone('Mars/Olympus')).toBe(false);
+  });
+
+  it('floors to the minute', () => {
+    expect(floorToMinute(at('2026-09-06T14:30:59.999Z')).toISOString()).toBe(
+      '2026-09-06T14:30:00.000Z',
+    );
+  });
+});