@manablox/workflows 0.2.0

package/src/service.ts

@@ -0,0 +1,167 @@
+import {
+  type Manablox,
+  ManabloxError,
+  WORKFLOW_CONDITION_OPERATOR_LABELS,
+  WORKFLOW_CONDITION_OPERATORS,
+  WORKFLOW_EVENT_LABELS,
+  WORKFLOW_EVENTS,
+  WORKFLOW_STEP_LABELS,
+  WORKFLOW_STEP_TYPES,
+} from '@manablox/core';
+import type { PushSubscriptionRow, Repositories, WorkflowRow, WorkflowRunRow } from '@manablox/db';
+import { requireInSpace } from '@manablox/services';
+import type { WorkflowEngine } from './engine.js';
+import { validateWorkflow, type WorkflowInput } from './validate.js';
+
+export type { WorkflowInput, WorkflowRow, WorkflowRunRow };
+
+/** What the editor needs to draw the palette, served rather than duplicated there. */
+export interface WorkflowCatalog {
+  events: Array<{ id: string; label: string; description: string }>;
+  stepTypes: Array<{ id: string; label: string; description: string; available: boolean }>;
+  operators: Array<{ id: string; label: string }>;
+  /** Whether the instance can send mail / push at all; the editor warns when it cannot. */
+  mail: boolean;
+  push: boolean;
+  /** The VAPID public key a browser subscribes with, when push is configured. */
+  pushPublicKey: string | null;
+  adminUrl: string;
+}
+
+/**
+ * Workflows: the rules — a trigger that exists, steps with somewhere to go, a run that
+ * belongs to the space it is asked for in — with the engine doing the running.
+ */
+export class WorkflowService {
+  constructor(
+    private readonly manablox: Manablox,
+    private readonly repos: Repositories,
+    private readonly engine: WorkflowEngine,
+  ) {}
+
+  catalog(): WorkflowCatalog {
+    const mail = Boolean(this.manablox.config.mail.smtpUrl);
+    const push = Boolean(
+      this.manablox.config.push.vapidPublicKey && this.manablox.config.push.vapidPrivateKey,
+    );
+    return {
+      events: WORKFLOW_EVENTS.map((id) => ({ id, ...WORKFLOW_EVENT_LABELS[id] })),
+      stepTypes: WORKFLOW_STEP_TYPES.map((id) => ({
+        id,
+        ...WORKFLOW_STEP_LABELS[id],
+        available: id === 'email' ? mail : id === 'push' ? push : true,
+      })),
+      operators: WORKFLOW_CONDITION_OPERATORS.map((id) => ({
+        id,
+        label: WORKFLOW_CONDITION_OPERATOR_LABELS[id],
+      })),
+      mail,
+      push,
+      pushPublicKey: push ? (this.manablox.config.push.vapidPublicKey ?? null) : null,
+      adminUrl: this.engine.adminUrl,
+    };
+  }
+
+  list(spaceId: string): Promise<WorkflowRow[]> {
+    return this.repos.workflows.listBySpace(spaceId);
+  }
+
+  get(spaceId: string, id: string): Promise<WorkflowRow> {
+    return this.find(spaceId, id);
+  }
+
+  async create(spaceId: string, input: WorkflowInput): Promise<WorkflowRow> {
+    const valid = validateWorkflow(input, this.validationEnvironment());
+    return this.repos.workflows.create({ spaceId, ...valid });
+  }
+
+  async update(spaceId: string, id: string, input: WorkflowInput): Promise<WorkflowRow> {
+    await this.find(spaceId, id);
+    const valid = validateWorkflow(input, this.validationEnvironment());
+    return this.repos.workflows.update(id, valid);
+  }
+
+  /** The on/off switch, kept apart from a full save so the list can flip it. */
+  async setEnabled(spaceId: string, id: string, enabled: boolean): Promise<WorkflowRow> {
+    await this.find(spaceId, id);
+    return this.repos.workflows.update(id, { enabled });
+  }
+
+  async delete(spaceId: string, id: string): Promise<void> {
+    await this.find(spaceId, id);
+    await this.repos.workflows.delete(id);
+  }
+
+  async runs(spaceId: string, id: string, limit = 50): Promise<WorkflowRunRow[]> {
+    await this.find(spaceId, id);
+    return this.repos.workflows.listRuns(id, limit);
+  }
+
+  async run(spaceId: string, id: string): Promise<WorkflowRunRow> {
+    return requireInSpace(
+      await this.repos.workflows.findRun(id),
+      spaceId,
+      'workflow.run.notFound',
+      {
+        id,
+      },
+    );
+  }
+
+  /**
+   * Runs a workflow now, against a document of the space when one is named. An
+   * event-triggered workflow needs one — its steps read `content` — while a scheduled
+   * workflow may run against its own selection.
+   */
+  async runNow(spaceId: string, id: string, contentId: string | null): Promise<WorkflowRunRow> {
+    const workflow = await this.find(spaceId, id);
+    let document = null;
+    if (contentId) {
+      document = requireInSpace(
+        await this.repos.content.findById(contentId),
+        spaceId,
+        'content.notFound',
+        { id: contentId },
+      );
+    } else if (workflow.trigger.kind === 'event') {
+      throw ManabloxError.badRequest('workflow.run.documentRequired');
+    }
+    return this.engine.runManually(workflow, document);
+  }
+
+  // --- push subscriptions --------------------------------------------------------
+
+  subscriptions(userId: string): Promise<PushSubscriptionRow[]> {
+    return this.repos.workflows.subscriptionsOf(userId);
+  }
+
+  async subscribe(
+    userId: string,
+    subscription: { endpoint: string; keys: { p256dh: string; auth: string } },
+    userAgent: string | null,
+  ): Promise<PushSubscriptionRow> {
+    if (!this.catalog().push) throw ManabloxError.badRequest('workflow.push.notConfigured');
+    if (!/^https:\/\//.test(subscription.endpoint)) {
+      throw ManabloxError.badRequest('workflow.push.subscriptionInvalid');
+    }
+    return this.repos.workflows.subscribe({ userId, ...subscription, userAgent });
+  }
+
+  unsubscribe(userId: string, endpoint: string): Promise<void> {
+    return this.repos.workflows.unsubscribe(userId, endpoint);
+  }
+
+  // -------------------------------------------------------------------------------
+
+  private async find(spaceId: string, id: string): Promise<WorkflowRow> {
+    return requireInSpace(await this.repos.workflows.findById(id), spaceId, 'workflow.notFound', {
+      id,
+    });
+  }
+
+  private validationEnvironment() {
+    return {
+      typeExists: (typeId: string) => this.manablox.contentTypes.tryGet(typeId) !== undefined,
+    };
+  }
+}

package/src/steps.ts

@@ -0,0 +1,256 @@
+import { createHmac } from 'node:crypto';
+import {
+  isEmailAddress,
+  ManabloxError,
+  type WorkflowEmailStep,
+  type WorkflowHttpStep,
+  type WorkflowPushStep,
+  type WorkflowRunContext,
+  type WorkflowStep,
+} from '@manablox/core';
+import type { Repositories } from '@manablox/db';
+import { evaluateCondition } from './conditions.js';
+import type { Mailer } from './mail.js';
+import type { Pusher } from './push.js';
+import { render, renderJson } from './template.js';
+
+/** The outside world as the steps see it; tests swap every part of it. */
+export interface StepEnvironment {
+  repos: Repositories;
+  mailer: Mailer | null;
+  pusher: Pusher | null;
+  fetch: typeof fetch;
+  /** Where the admin lives, for links in mails and notifications. */
+  adminUrl: string;
+}
+
+export type StepOutcome =
+  | { kind: 'ok'; message: string | null; detail: Record<string, unknown> | null }
+  | { kind: 'stop'; message: string }
+  | { kind: 'wait'; minutes: number };
+
+/** Runs one step against a context. Throws when the step fails; the runner logs it. */
+export async function executeStep(
+  step: WorkflowStep,
+  context: WorkflowRunContext,
+  env: StepEnvironment,
+): Promise<StepOutcome> {
+  switch (step.type) {
+    case 'email':
+      return sendEmail(step, context, env);
+    case 'http':
+      return callHttp(step, context, env);
+    case 'push':
+      return sendPush(step, context, env);
+    case 'condition':
+      return evaluateCondition(step, context)
+        ? { kind: 'ok', message: 'Conditions met', detail: null }
+        : { kind: 'stop', message: 'Conditions not met' };
+    case 'delay':
+      return { kind: 'wait', minutes: step.minutes };
+    case 'branch':
+      // The runner walks a fork itself; it never lands here.
+      return evaluateCondition(step, context)
+        ? { kind: 'ok', message: 'Rules hold', detail: { branch: 'then' } }
+        : { kind: 'ok', message: 'Rules do not hold', detail: { branch: 'else' } };
+  }
+}
+
+// --- email --------------------------------------------------------------------
+
+async function sendEmail(
+  step: WorkflowEmailStep,
+  context: WorkflowRunContext,
+  env: StepEnvironment,
+): Promise<StepOutcome> {
+  if (!env.mailer) throw new ManabloxError('workflow.mail.notConfigured');
+
+  const recipients = new Set<string>();
+  for (const template of step.to) {
+    for (const address of render(template, context).split(/[,\s;]+/)) {
+      if (address && isEmailAddress(address)) recipients.add(address.toLowerCase());
+    }
+  }
+  if (step.toRoles.length) {
+    const members = await env.repos.users.membersOf(context.space.id);
+    for (const member of members) {
+      if (step.toRoles.includes(member.role) && member.user.email) {
+        recipients.add(member.user.email.toLowerCase());
+      }
+    }
+  }
+  if (recipients.size === 0) throw new Error('No recipient address resolved');
+
+  const subject = render(step.subject, context);
+  const body = render(step.body, context);
+  const to = [...recipients];
+  const sent = await env.mailer.send({
+    to,
+    subject,
+    text: step.html ? stripTags(body) : body,
+    ...(step.html ? { html: body } : {}),
+  });
+  return {
+    kind: 'ok',
+    message: `Sent to ${to.join(', ')}`,
+    detail: { to, subject, messageId: sent.id },
+  };
+}
+
+function stripTags(html: string): string {
+  return html
+    .replace(/<style[\s\S]*?<\/style>/gi, '')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<\/p>/gi, '\n\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .trim();
+}
+
+// --- http ---------------------------------------------------------------------
+
+async function callHttp(
+  step: WorkflowHttpStep,
+  context: WorkflowRunContext,
+  env: StepEnvironment,
+): Promise<StepOutcome> {
+  const url = render(step.url, context);
+  const headers = new Headers();
+  for (const header of step.headers) headers.set(header.name, render(header.value, context));
+
+  let body: string | undefined;
+  if (step.method !== 'GET' && step.body.mode !== 'none') {
+    if (step.body.mode === 'event') {
+      body = JSON.stringify(context);
+      if (!headers.has('content-type')) headers.set('content-type', 'application/json');
+    } else {
+      const template = step.body.template;
+      // A template that is itself JSON is rendered as JSON, so placeholders keep types.
+      body = looksLikeJson(template) ? renderJson(template, context) : render(template, context);
+      if (!headers.has('content-type')) {
+        headers.set('content-type', looksLikeJson(template) ? 'application/json' : 'text/plain');
+      }
+    }
+  }
+
+  headers.set('x-manablox-event', context.event);
+  headers.set('x-manablox-workflow', context.workflow.id);
+  if (step.secret && body !== undefined) {
+    headers.set(
+      'x-manablox-signature',
+      `sha256=${createHmac('sha256', step.secret).update(body).digest('hex')}`,
+    );
+  }
+
+  const started = Date.now();
+  let response: Response;
+  try {
+    response = await env.fetch(url, {
+      method: step.method,
+      headers,
+      ...(body !== undefined ? { body } : {}),
+      signal: AbortSignal.timeout(step.timeoutMs),
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`${step.method} ${url} failed: ${reason}`);
+  }
+
+  const snippet = (await response.text().catch(() => '')).slice(0, 500);
+  const detail = {
+    url,
+    method: step.method,
+    status: response.status,
+    ms: Date.now() - started,
+    response: snippet,
+  };
+  if (!response.ok) {
+    const error = new Error(`${step.method} ${url} answered HTTP ${response.status}`);
+    (error as Error & { detail?: Record<string, unknown> }).detail = detail;
+    throw error;
+  }
+  return { kind: 'ok', message: `HTTP ${response.status}`, detail };
+}
+
+function looksLikeJson(template: string): boolean {
+  const trimmed = template.trim();
+  if (
+    !(trimmed.startsWith('{') && trimmed.endsWith('}')) &&
+    !(trimmed.startsWith('[') && trimmed.endsWith(']'))
+  ) {
+    return false;
+  }
+  try {
+    JSON.parse(trimmed);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// --- push ---------------------------------------------------------------------
+
+async function sendPush(
+  step: WorkflowPushStep,
+  context: WorkflowRunContext,
+  env: StepEnvironment,
+): Promise<StepOutcome> {
+  if (!env.pusher) throw new ManabloxError('workflow.push.notConfigured');
+
+  const userIds = new Set(step.userIds);
+  if (step.roles.length || userIds.size === 0) {
+    const members = await env.repos.users.membersOf(context.space.id);
+    for (const member of members) {
+      if (step.roles.length === 0 || step.roles.includes(member.role)) userIds.add(member.userId);
+    }
+  }
+
+  const subscriptions = await env.repos.workflows.subscriptionsFor([...userIds]);
+  if (subscriptions.length === 0) {
+    return {
+      kind: 'ok',
+      message: 'Nobody among the recipients has enabled notifications',
+      detail: { recipients: userIds.size, devices: 0 },
+    };
+  }
+
+  const renderedUrl = render(step.url, context).trim();
+  const url = renderedUrl
+    ? /^https?:\/\//i.test(renderedUrl)
+      ? renderedUrl
+      : `${env.adminUrl.replace(/\/$/, '')}/${renderedUrl.replace(/^\//, '')}`
+    : context.url;
+  const payload = { title: render(step.title, context), body: render(step.body, context), url };
+
+  let sent = 0;
+  let gone = 0;
+  const failures: string[] = [];
+  for (const subscription of subscriptions) {
+    try {
+      const result = await env.pusher.send(
+        { endpoint: subscription.endpoint, keys: subscription.keys },
+        payload,
+      );
+      if (result === 'gone') {
+        gone++;
+        await env.repos.workflows.dropSubscription(subscription.id);
+      } else {
+        sent++;
+        await env.repos.workflows.markSubscriptionUsed(subscription.id);
+      }
+    } catch (error) {
+      failures.push(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  const detail = { recipients: userIds.size, devices: subscriptions.length, sent, gone, failures };
+  if (sent === 0 && failures.length) {
+    const error = new Error(`Every push failed: ${failures[0]}`);
+    (error as Error & { detail?: Record<string, unknown> }).detail = detail;
+    throw error;
+  }
+  return { kind: 'ok', message: `Sent to ${sent} device${sent === 1 ? '' : 's'}`, detail };
+}

package/src/template.ts

@@ -0,0 +1,65 @@
+/**
+ * The placeholder syntax templates use: `{{ content.title }}`, `{{ content.fields.body }}`,
+ * `{{ actor.email }}`. A path resolves into the run context; an object or array comes out
+ * as JSON, anything missing as an empty string. Deliberately no logic — a workflow that
+ * needs a branch has a condition step for it.
+ */
+
+const PLACEHOLDER = /\{\{\s*([a-zA-Z0-9_.[\]-]+)\s*\}\}/g;
+
+export function resolvePath(root: unknown, path: string): unknown {
+  let current: unknown = root;
+  for (const segment of path.replace(/\[(\d+)\]/g, '.$1').split('.')) {
+    if (segment === '') continue;
+    if (current === null || current === undefined) return undefined;
+    if (typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+export function stringify(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (value instanceof Date) return value.toISOString();
+  return JSON.stringify(value);
+}
+
+export function render(template: string, context: unknown): string {
+  return template.replace(PLACEHOLDER, (_match, path: string) =>
+    stringify(resolvePath(context, path)),
+  );
+}
+
+/**
+ * Renders inside a JSON document: a placeholder that stands alone in a string is
+ * replaced by the value itself (`"count": "{{ documents.length }}"` becomes a number,
+ * `"doc": "{{ content }}"` an object); one embedded in text renders as text.
+ */
+export function renderJson(template: string, context: unknown): string {
+  const parsed: unknown = JSON.parse(template);
+  const walk = (value: unknown): unknown => {
+    if (typeof value === 'string') {
+      const alone = /^\{\{\s*([a-zA-Z0-9_.[\]-]+)\s*\}\}$/.exec(value);
+      if (alone) {
+        const resolved = resolvePath(context, alone[1] as string);
+        return resolved === undefined ? null : resolved;
+      }
+      return render(value, context);
+    }
+    if (Array.isArray(value)) return value.map(walk);
+    if (value && typeof value === 'object') {
+      return Object.fromEntries(
+        Object.entries(value as Record<string, unknown>).map(([key, entry]) => [key, walk(entry)]),
+      );
+    }
+    return value;
+  };
+  return JSON.stringify(walk(parsed));
+}
+
+/** Every placeholder a template names, for the editor's hints and for validation. */
+export function placeholders(template: string): string[] {
+  return [...template.matchAll(PLACEHOLDER)].map((match) => match[1] as string);
+}