@manablox/workflows 0.2.0

package/test/engine.test.ts

@@ -0,0 +1,555 @@
+import type { Manablox, WorkflowEvent, WorkflowStep, WorkflowTrigger } from '@manablox/core';
+import type { Repositories } from '@manablox/db';
+import { builtinFieldTypes } from '@manablox/fields';
+import type { ContentService } from '@manablox/services';
+import { createServiceContext } from '@manablox/services/testing';
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { WorkflowEngine } from '../src/engine.js';
+import type { MailMessage } from '../src/mail.js';
+import { WorkflowService } from '../src/service.js';
+
+let manablox: Manablox;
+let repos: Repositories;
+let content: ContentService;
+let engine: WorkflowEngine;
+let service: WorkflowService;
+let spaceId: string;
+let pageType: string;
+let noteType: string;
+let close: () => Promise<void>;
+
+const mails: MailMessage[] = [];
+const calls: Array<{ url: string; init: RequestInit }> = [];
+let clock = new Date('2026-09-06T14:29:30.000Z');
+let fetchStatus = 200;
+
+const step = <T extends WorkflowStep['type']>(
+  type: T,
+  extra: Omit<Extract<WorkflowStep, { type: T }>, keyof WorkflowStep | 'type'> &
+    Partial<WorkflowStep>,
+): WorkflowStep =>
+  ({ id: '', name: '', enabled: true, continueOnError: false, type, ...extra }) as WorkflowStep;
+
+const email = (extra: Partial<Extract<WorkflowStep, { type: 'email' }>> = {}) =>
+  step('email', {
+    to: ['ops@example.com'],
+    toRoles: [],
+    subject: '{{ event }}: {{ content.title }}',
+    body: 'By {{ actor.email }}',
+    html: false,
+    ...extra,
+  });
+
+const onEvents = (events: WorkflowEvent[], typeIds: string[] = []): WorkflowTrigger => ({
+  kind: 'event',
+  events,
+  typeIds,
+  locales: [],
+});
+
+async function workflow(
+  name: string,
+  trigger: WorkflowTrigger,
+  steps: WorkflowStep[],
+  enabled = true,
+) {
+  return service.create(spaceId, { name, trigger, steps, enabled });
+}
+
+async function page(title: string, fields: Record<string, unknown> = {}, typeId = pageType) {
+  return content.create({
+    spaceId,
+    typeId,
+    locale: 'en',
+    title,
+    slug: title.toLowerCase().replace(/\s+/g, '-'),
+    fields,
+  });
+}
+
+beforeAll(async () => {
+  const ctx = await createServiceContext('workflows', {
+    fieldTypes: builtinFieldTypes,
+    contentTypes: [
+      { name: 'page', fields: [{ name: 'category', type: 'string' }] },
+      { name: 'note', fields: [] },
+    ],
+    config: { server: { adminUrl: 'https://admin.test' } },
+  });
+  manablox = ctx.manablox;
+  repos = ctx.repos;
+  content = ctx.content;
+
+  engine = new WorkflowEngine(manablox, repos, {
+    mailer: {
+      async send(message) {
+        mails.push(message);
+        return { id: 'msg-1' };
+      },
+    },
+    pusher: null,
+    fetch: (async (url: string | URL | Request, init?: RequestInit) => {
+      calls.push({ url: String(url), init: init ?? {} });
+      return new Response(JSON.stringify({ ok: fetchStatus < 400 }), { status: fetchStatus });
+    }) as typeof fetch,
+    now: () => clock,
+  });
+  engine.attach();
+  service = new WorkflowService(manablox, repos, engine);
+
+  // The engine reads the space's URL for the links it hands to steps.
+  await repos.spaces.update(ctx.spaceId, { url: 'https://site.test' });
+  spaceId = ctx.spaceId;
+  pageType = ctx.ids.page as string;
+  noteType = ctx.ids.note as string;
+
+  close = ctx.close;
+});
+
+afterAll(async () => {
+  await close?.();
+});
+
+beforeEach(async () => {
+  mails.length = 0;
+  calls.length = 0;
+  fetchStatus = 200;
+  for (const row of await repos.workflows.listBySpace(spaceId))
+    await repos.workflows.delete(row.id);
+});
+
+describe('event workflows', () => {
+  it('runs an email step when a matching document is saved', async () => {
+    const wf = await workflow('Notify', onEvents(['content.saved'], [pageType]), [email()]);
+    const user = await repos.users.create({
+      name: 'Ann',
+      email: 'ann@example.com',
+      role: 'editor',
+      passwordHash: 'x',
+    });
+
+    const row = await content.create(
+      { spaceId, typeId: pageType, locale: 'en', title: 'Launch', slug: 'launch', fields: {} },
+      { userId: user.id, roles: ['owner'] },
+    );
+    await engine.idle();
+
+    expect(mails).toHaveLength(1);
+    expect(mails[0]).toMatchObject({
+      to: ['ops@example.com'],
+      subject: 'content.created: Launch',
+      text: 'By ann@example.com',
+    });
+
+    const [run] = await service.runs(spaceId, wf.id);
+    expect(run?.status).toBe('succeeded');
+    expect(run?.trigger).toBe('content.created');
+    expect(run?.context.content).toMatchObject({ id: row.id, title: 'Launch' });
+    expect(run?.context.url).toBe(`https://admin.test/content/${row.id}`);
+    expect(run?.log.map((entry) => entry.status)).toEqual(['ok']);
+  });
+
+  it('ignores other types, other events and disabled workflows', async () => {
+    await workflow('Pages only', onEvents(['content.saved'], [pageType]), [email()]);
+    await workflow('Publish only', onEvents(['content.published']), [email()]);
+    await workflow('Off', onEvents(['content.saved']), [email()], false);
+
+    await page('A note', {}, noteType);
+    await engine.idle();
+    expect(mails).toHaveLength(0);
+  });
+
+  it('carries the previous row on update so conditions can see what changed', async () => {
+    const wf = await workflow('Category changed', onEvents(['content.updated']), [
+      step('condition', {
+        match: 'all',
+        rules: [{ field: 'content.fields.category', operator: 'changed', value: '' }],
+      }),
+      email({ subject: 'now {{ content.fields.category }}, was {{ previous.fields.category }}' }),
+    ]);
+    const row = await page('Cat', { category: 'news' });
+    await engine.idle();
+
+    await content.update(row.id, {
+      spaceId,
+      typeId: pageType,
+      locale: 'en',
+      title: 'Cat',
+      slug: 'cat',
+      fields: { category: 'news' },
+    });
+    await engine.idle();
+    expect(mails).toHaveLength(0);
+    let runs = await service.runs(spaceId, wf.id);
+    expect(runs[0]?.status).toBe('skipped');
+    expect(runs[0]?.log[0]).toMatchObject({ type: 'condition', status: 'stopped' });
+
+    await content.update(row.id, {
+      spaceId,
+      typeId: pageType,
+      locale: 'en',
+      title: 'Cat',
+      slug: 'cat',
+      fields: { category: 'sport' },
+    });
+    await engine.idle();
+    expect(mails.map((mail) => mail.subject)).toEqual(['now sport, was news']);
+    runs = await service.runs(spaceId, wf.id);
+    expect(runs[0]?.status).toBe('succeeded');
+  });
+
+  it('calls an API with the signed event body and records the response', async () => {
+    const wf = await workflow('Sync', onEvents(['content.deleted']), [
+      step('http', {
+        method: 'POST',
+        url: 'https://hooks.test/{{ event }}',
+        headers: [{ name: 'x-token', value: 'abc' }],
+        body: { mode: 'event', template: '' },
+        secret: 's3cret',
+        timeoutMs: 5000,
+      }),
+    ]);
+    const row = await page('Gone');
+    await engine.idle();
+    await content.delete(row.id);
+    await engine.idle();
+
+    expect(calls).toHaveLength(1);
+    const call = calls[0]!;
+    expect(call.url).toBe('https://hooks.test/content.deleted');
+    const headers = new Headers(call.init.headers);
+    expect(headers.get('x-token')).toBe('abc');
+    expect(headers.get('content-type')).toBe('application/json');
+    expect(headers.get('x-manablox-signature')).toMatch(/^sha256=[0-9a-f]{64}$/);
+    const body = JSON.parse(String(call.init.body));
+    expect(body.content).toMatchObject({ id: row.id, title: 'Gone' });
+    expect(body.event).toBe('content.deleted');
+
+    const [run] = await service.runs(spaceId, wf.id);
+    expect(run?.log[0]).toMatchObject({ type: 'http', status: 'ok', detail: { status: 200 } });
+  });
+
+  it('renders a custom JSON body with typed placeholders', async () => {
+    await workflow('Custom', onEvents(['content.created']), [
+      step('http', {
+        method: 'PUT',
+        url: 'https://hooks.test/x',
+        headers: [],
+        body: {
+          mode: 'custom',
+          template:
+            '{"title":"{{ content.title }}","doc":"{{ content }}","v":"{{ content.version }}"}',
+        },
+        secret: null,
+        timeoutMs: 5000,
+      }),
+    ]);
+    const row = await page('Typed');
+    await engine.idle();
+    const body = JSON.parse(String(calls[0]?.init.body));
+    expect(body.title).toBe('Typed');
+    expect(body.doc.id).toBe(row.id);
+    expect(body.v).toBe(1);
+  });
+
+  it('marks the run failed on an error and continues past one flagged continueOnError', async () => {
+    fetchStatus = 503;
+    const wf = await workflow('Fragile', onEvents(['content.created']), [
+      step('http', {
+        method: 'POST',
+        url: 'https://down.test',
+        headers: [],
+        body: { mode: 'none', template: '' },
+        secret: null,
+        timeoutMs: 5000,
+        continueOnError: true,
+      }),
+      step('http', {
+        method: 'POST',
+        url: 'https://down.test',
+        headers: [],
+        body: { mode: 'none', template: '' },
+        secret: null,
+        timeoutMs: 5000,
+      }),
+      email(),
+    ]);
+    await page('Breaks');
+    await engine.idle();
+
+    const [run] = await service.runs(spaceId, wf.id);
+    expect(run?.status).toBe('failed');
+    expect(run?.log.map((entry) => entry.status)).toEqual(['failed', 'failed']);
+    expect(run?.error).toContain('HTTP 503');
+    expect(mails).toHaveLength(0);
+  });
+
+  it('reports a missing mailer in the run rather than throwing at the save', async () => {
+    const bare = new WorkflowEngine(manablox, repos, { now: () => clock });
+    const wf = await workflow('No mail', onEvents(['content.created']), [email()]);
+    const run = await new WorkflowService(manablox, repos, bare).runNow(
+      spaceId,
+      wf.id,
+      (await page('Plain')).id,
+    );
+    expect(run.status).toBe('failed');
+    expect(run.error).toBe('workflow.mail.notConfigured');
+  });
+
+  it('sends to members by role and skips a step that is switched off', async () => {
+    const editor = await repos.users.create({
+      name: 'Ed',
+      email: 'ed@example.com',
+      role: 'editor',
+      passwordHash: 'x',
+    });
+    const viewer = await repos.users.create({
+      name: 'Vi',
+      email: 'vi@example.com',
+      role: 'editor',
+      passwordHash: 'x',
+    });
+    await repos.users.grant(editor.id, spaceId, 'editor');
+    await repos.users.grant(viewer.id, spaceId, 'viewer');
+
+    const wf = await workflow('Roles', onEvents(['content.created']), [
+      email({ to: [], toRoles: ['editor'] }),
+      email({ enabled: false }),
+    ]);
+    await page('Roles');
+    await engine.idle();
+
+    expect(mails).toHaveLength(1);
+    expect(mails[0]?.to).toEqual(['ed@example.com']);
+    const [run] = await service.runs(spaceId, wf.id);
+    expect(run?.log.map((entry) => entry.status)).toEqual(['ok', 'skipped']);
+  });
+});
+
+describe('forks', () => {
+  const fork = (then: WorkflowStep[], otherwise: WorkflowStep[]): WorkflowStep =>
+    step('branch', {
+      match: 'all',
+      rules: [{ field: 'content.fields.category', operator: 'equals', value: 'news' }],
+      then,
+      else: otherwise,
+    });
+
+  it('takes the yes side when the rules hold, the no side otherwise, then carries on', async () => {
+    const wf = await workflow('Fork', onEvents(['content.created']), [
+      fork([email({ subject: 'yes' })], [email({ subject: 'no' })]),
+      email({ subject: 'after' }),
+    ]);
+    await page('News', { category: 'news' });
+    await engine.idle();
+    expect(mails.map((mail) => mail.subject)).toEqual(['yes', 'after']);
+
+    mails.length = 0;
+    await page('Sport', { category: 'sport' });
+    await engine.idle();
+    expect(mails.map((mail) => mail.subject)).toEqual(['no', 'after']);
+
+    const [run] = await service.runs(spaceId, wf.id);
+    expect(run?.status).toBe('succeeded');
+    expect(run?.log.map((entry) => [entry.type, entry.status])).toEqual([
+      ['branch', 'ok'],
+      ['email', 'ok'],
+      ['email', 'ok'],
+    ]);
+    expect(run?.log[0]?.detail).toEqual({ branch: 'else' });
+  });
+
+  it('resumes inside a side after a delay, without re-deciding the fork', async () => {
+    const wf = await workflow('Fork wait', onEvents(['content.created']), [
+      fork([step('delay', { minutes: 5 }), email({ subject: 'yes, later' })], []),
+      email({ subject: 'after' }),
+    ]);
+    const row = await page('Delayed news', { category: 'news' });
+    await engine.idle();
+    let [run] = await service.runs(spaceId, wf.id);
+    expect(run?.status).toBe('waiting');
+    expect(run?.cursor).toEqual([0, 'then', 1]);
+    expect(mails).toHaveLength(0);
+
+    // The document changes its mind meanwhile; the fork stays decided.
+    await content.update(row.id, {
+      spaceId,
+      typeId: pageType,
+      locale: 'en',
+      title: 'Delayed news',
+      slug: 'delayed-news',
+      fields: { category: 'sport' },
+    });
+    clock = new Date('2026-09-06T14:40:00.000Z');
+    await engine.tick(clock);
+    await engine.idle();
+    expect(mails.map((mail) => mail.subject)).toEqual(['yes, later', 'after']);
+    [run] = await service.runs(spaceId, wf.id);
+    expect(run?.status).toBe('succeeded');
+    clock = new Date('2026-09-06T14:29:30.000Z');
+  });
+
+  it('stops or fails inside a side like anywhere else', async () => {
+    fetchStatus = 500;
+    const wf = await workflow('Fork fail', onEvents(['content.created']), [
+      fork(
+        [
+          step('http', {
+            method: 'POST',
+            url: 'https://down.test',
+            headers: [],
+            body: { mode: 'none', template: '' },
+            secret: null,
+            timeoutMs: 5000,
+          }),
+        ],
+        [],
+      ),
+      email({ subject: 'never' }),
+    ]);
+    await page('Fails', { category: 'news' });
+    await engine.idle();
+    const [run] = await service.runs(spaceId, wf.id);
+    expect(run?.status).toBe('failed');
+    expect(run?.cursor).toEqual([0, 'then', 0]);
+    expect(mails).toHaveLength(0);
+  });
+
+  it('validates the steps inside both sides with their paths', async () => {
+    await expect(
+      workflow('Bad fork', onEvents(['content.created']), [
+        fork([email({ subject: '' })], [step('delay', { minutes: 0 })]),
+      ]),
+    ).rejects.toMatchObject({
+      details: [
+        { key: 'workflow.step.email.subjectRequired', path: ['steps', 0, 'then', 0, 'subject'] },
+        { key: 'workflow.step.delay.minutesInvalid', path: ['steps', 0, 'else', 0, 'minutes'] },
+      ],
+    });
+  });
+});
+
+describe('delays', () => {
+  it('pauses the run and resumes it from the tick once the time has come', async () => {
+    const wf = await workflow('Later', onEvents(['content.created']), [
+      step('delay', { minutes: 5 }),
+      email({ subject: 'after the wait' }),
+    ]);
+    await page('Patience');
+    await engine.idle();
+
+    let [run] = await service.runs(spaceId, wf.id);
+    expect(run?.status).toBe('waiting');
+    expect(run?.cursor).toEqual([1]);
+    expect(run?.resumeAt?.toISOString()).toBe('2026-09-06T14:34:30.000Z');
+    expect(mails).toHaveLength(0);
+
+    await engine.tick(new Date('2026-09-06T14:33:00.000Z'));
+    await engine.idle();
+    expect(mails).toHaveLength(0);
+
+    clock = new Date('2026-09-06T14:35:00.000Z');
+    await engine.tick(clock);
+    await engine.idle();
+    expect(mails.map((mail) => mail.subject)).toEqual(['after the wait']);
+    [run] = await service.runs(spaceId, wf.id);
+    expect(run?.status).toBe('succeeded');
+    expect(run?.log.map((entry) => entry.status)).toEqual(['waiting', 'ok']);
+    clock = new Date('2026-09-06T14:29:30.000Z');
+  });
+});
+
+describe('scheduled workflows', () => {
+  it('starts at the cron minute, once, with the selected documents', async () => {
+    await page('Fresh one', { category: 'x' });
+    await page('Fresh two', { category: 'y' });
+    await engine.idle();
+
+    const wf = await workflow(
+      'Digest',
+      {
+        kind: 'schedule',
+        cron: '30 14 * * *',
+        timezone: 'UTC',
+        selection: { typeIds: [pageType], status: 'any', changedWithinHours: 24, locale: null },
+        perDocument: false,
+      },
+      [email({ subject: '{{ documents.length }} documents' })],
+    );
+
+    await engine.tick(new Date('2026-09-06T14:29:59.000Z'));
+    await engine.idle();
+    expect(mails).toHaveLength(0);
+
+    await engine.tick(new Date('2026-09-06T14:30:05.000Z'));
+    await engine.tick(new Date('2026-09-06T14:30:45.000Z'));
+    await engine.idle();
+    expect(mails).toHaveLength(1);
+    expect(Number(mails[0]?.subject.split(' ')[0])).toBeGreaterThanOrEqual(2);
+
+    const runs = await service.runs(spaceId, wf.id);
+    expect(runs).toHaveLength(1);
+    expect(runs[0]?.trigger).toBe('schedule');
+    expect(runs[0]?.context.documents.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('runs once per document when asked', async () => {
+    const wf = await workflow(
+      'Each',
+      {
+        kind: 'schedule',
+        cron: '0 9 * * 1',
+        timezone: 'Europe/Vienna',
+        selection: { typeIds: [noteType], status: 'draft', changedWithinHours: null, locale: 'en' },
+        perDocument: true,
+      },
+      [email({ subject: 'about {{ content.title }}' })],
+    );
+    await page('Note A', {}, noteType);
+    await page('Note B', {}, noteType);
+    await engine.idle();
+
+    // Monday 7 September 2026, 09:00 Vienna summer time = 07:00 UTC.
+    await engine.tick(new Date('2026-09-07T07:00:10.000Z'));
+    await engine.idle();
+
+    expect(mails.map((mail) => mail.subject).sort()).toEqual([
+      'about A note',
+      'about Note A',
+      'about Note B',
+    ]);
+    expect((await service.runs(spaceId, wf.id)).every((run) => run.status === 'succeeded')).toBe(
+      true,
+    );
+  });
+
+  it('can be run by hand, and an event workflow needs a document for that', async () => {
+    const scheduled = await workflow(
+      'Manual',
+      { kind: 'schedule', cron: '0 0 * * *', timezone: 'UTC', selection: null, perDocument: false },
+      [email({ subject: 'manual {{ event }}' })],
+    );
+    const run = await service.runNow(spaceId, scheduled.id, null);
+    expect(run.status).toBe('succeeded');
+    expect(run.trigger).toBe('manual');
+    expect(mails[0]?.subject).toBe('manual manual');
+
+    const evented = await workflow('Needs doc', onEvents(['content.created']), [email()]);
+    await expect(service.runNow(spaceId, evented.id, null)).rejects.toMatchObject({
+      key: 'workflow.run.documentRequired',
+    });
+  });
+});
+
+describe('service rules', () => {
+  it('rejects a workflow from another space and validates on save', async () => {
+    const other = await repos.spaces.create({ name: 'O', machineName: 'o', url: 'https://o.test' });
+    const wf = await workflow('Mine', onEvents(['content.created']), [email()]);
+    await expect(service.get(other.id, wf.id)).rejects.toMatchObject({ key: 'workflow.notFound' });
+    await expect(
+      service.update(spaceId, wf.id, { name: '', trigger: wf.trigger, steps: [] }),
+    ).rejects.toMatchObject({ key: 'workflow.validation.failed' });
+    const flipped = await service.setEnabled(spaceId, wf.id, false);
+    expect(flipped.enabled).toBe(false);
+  });
+});

package/test/template.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { placeholders, render, renderJson, resolvePath } from '../src/template.js';
+
+const context = {
+  event: 'content.updated',
+  content: { title: 'Hello', fields: { tags: ['a', 'b'], count: 3, meta: { ok: true } } },
+  actor: null,
+  documents: [{ title: 'One' }, { title: 'Two' }],
+};
+
+describe('render', () => {
+  it('substitutes paths, with objects as JSON and gaps as empty', () => {
+    expect(render('{{ content.title }}!', context)).toBe('Hello!');
+    expect(render('{{content.fields.count}}', context)).toBe('3');
+    expect(render('{{ content.fields.tags }}', context)).toBe('["a","b"]');
+    expect(render('{{ content.fields.tags[1] }}', context)).toBe('b');
+    expect(render('{{ actor.email }}', context)).toBe('');
+    expect(render('{{ nothing.here }}', context)).toBe('');
+    expect(render('{{ documents.length }}', context)).toBe('2');
+  });
+
+  it('lists placeholders', () => {
+    expect(placeholders('{{ a.b }} and {{c}}')).toEqual(['a.b', 'c']);
+  });
+
+  it('resolves array indices', () => {
+    expect(resolvePath(context, 'documents.0.title')).toBe('One');
+  });
+});
+
+describe('renderJson', () => {
+  it('keeps types for a placeholder that stands alone', () => {
+    const out = JSON.parse(
+      renderJson(
+        '{"title":"{{ content.title }}","n":"{{ content.fields.count }}","tags":"{{ content.fields.tags }}","text":"n={{ content.fields.count }}","missing":"{{ nope }}"}',
+        context,
+      ),
+    );
+    expect(out).toEqual({ title: 'Hello', n: 3, tags: ['a', 'b'], text: 'n=3', missing: null });
+  });
+});