@manablox/workflows 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,301 @@
+import { ContentRecord, Logger, MailConfig, Manablox, PushConfig, WorkflowConditionRule, WorkflowConditionStep, WorkflowEvent, WorkflowEventTrigger, WorkflowRunContext, WorkflowStep, WorkflowTrigger } from "@manablox/core";
+import { ContentRow, PushSubscriptionRow, Repositories, WorkflowRow, WorkflowRow as WorkflowRow$1, WorkflowRunRow, WorkflowRunRow as WorkflowRunRow$1 } from "@manablox/db";
+//#region src/conditions.d.ts
+export declare function evaluateRule(rule: WorkflowConditionRule, context: WorkflowRunContext): boolean;
+/** Whether the run may continue past this step. */
+export declare function evaluateCondition(step: Pick<WorkflowConditionStep, 'match' | 'rules'>, context: WorkflowRunContext): boolean;
+//#endregion
+//#region src/cron.d.ts
+/**
+ * Five-field cron — `minute hour day-of-month month day-of-week` — matched against a
+ * wall-clock in a named timezone. Only matching is needed: the scheduler wakes every
+ * minute and asks "is now a match?", so there is no next-run arithmetic to get wrong.
+ */
+export interface CronSpec {
+  minute: Set<number>;
+  hour: Set<number>;
+  dayOfMonth: Set<number>;
+  month: Set<number>;
+  dayOfWeek: Set<number>;
+  /** `*` in the day-of-month field; decides how the two day fields combine. */
+  anyDayOfMonth: boolean;
+  anyDayOfWeek: boolean;
+}
+export declare function parseCron(expression: string): CronSpec | null;
+export declare function isValidCron(expression: string): boolean;
+export declare function isValidTimezone(timezone: string): boolean;
+export interface WallClock {
+  minute: number;
+  hour: number;
+  dayOfMonth: number;
+  month: number;
+  dayOfWeek: number;
+}
+/** The wall-clock reading of an instant in a timezone. */
+export declare function wallClock(date: Date, timezone: string): WallClock;
+/**
+ * Whether the minute containing `date` matches. As in Vixie cron, when both day fields
+ * are restricted a match on either is enough.
+ */
+export declare function cronMatches(spec: CronSpec, date: Date, timezone: string): boolean;
+/** The start of the minute an instant falls in — the unit the scheduler claims. */
+export declare function floorToMinute(date: Date): Date;
+//#endregion
+//#region src/mail.d.ts
+export interface MailMessage {
+  to: string[];
+  subject: string;
+  text: string;
+  html?: string | undefined;
+}
+/** What the email step needs from the outside world; the tests hand in a recorder. */
+export interface Mailer {
+  send(message: MailMessage): Promise<{
+    id: string | null;
+  }>;
+}
+/**
+ * A mailer over the configured SMTP URL, or `null` when there is none — the step then
+ * fails with `workflow.mail.notConfigured`, which the run log shows verbatim.
+ */
+export declare function createMailer(config: MailConfig, logger: Logger): Mailer | null;
+//#endregion
+//#region src/push.d.ts
+export interface PushTarget {
+  endpoint: string;
+  keys: {
+    p256dh: string;
+    auth: string;
+  };
+}
+/** What a notification carries; the admin's service worker reads exactly this. */
+export interface PushPayload {
+  title: string;
+  body: string;
+  url: string | null;
+}
+/** What the push step needs from the outside world; the tests hand in a recorder. */
+export interface Pusher {
+  /** `gone` means the push service no longer knows the subscription and the row should go. */
+  send(target: PushTarget, payload: PushPayload): Promise<'sent' | 'gone'>;
+  publicKey: string;
+}
+export declare function isPushConfigured(config: PushConfig): boolean;
+/**
+ * A Web Push sender over the configured VAPID keys, or `null` when there are none. The
+ * keys are made once per installation with `pnpm --filter @manablox/api push:keys`.
+ */
+export declare function createPusher(config: PushConfig, logger: Logger): Pusher | null;
+/** A fresh VAPID key pair, for the CLI that prints them. */
+export declare function generatePushKeys(): {
+  publicKey: string;
+  privateKey: string;
+};
+//#endregion
+//#region src/engine.d.ts
+export interface WorkflowEngineOptions {
+  mailer?: Mailer | null | undefined;
+  pusher?: Pusher | null | undefined;
+  fetch?: typeof fetch | undefined;
+  /** Where the admin lives, for links in mails and notifications. */
+  adminUrl?: string | undefined;
+  /**
+   * Hands a queued run to a worker. The default runs it in this process, off the
+   * request; a host with a queue passes `(runId) => jobs.enqueue('workflow:run', …)`.
+   */
+  dispatch?: ((runId: string) => Promise<void>) | undefined;
+  /** How often the scheduler looks at the clock. Every 20 s catches each minute once. */
+  tickMs?: number | undefined;
+  now?: (() => Date) | undefined;
+}
+/**
+ * Runs workflows: listens for content events, keeps the clock for scheduled ones, and
+ * executes a run's steps one after another, pausing at a delay and picking it up again.
+ *
+ * A run is a row from the moment it is queued, so nothing is lost if the process goes
+ * away mid-way: the next tick finds `waiting` runs whose time has come, and a worker
+ * claims a run before touching it so two never execute the same one.
+ */
+export declare class WorkflowEngine {
+  private readonly manablox;
+  private readonly repos;
+  private readonly env;
+  private readonly dispatch;
+  private readonly now;
+  private readonly tickMs;
+  private readonly pending;
+  private timer;
+  private ticking;
+  constructor(manablox: Manablox, repos: Repositories, options?: WorkflowEngineOptions);
+  get adminUrl(): string;
+  /** Registers the content hooks. Call once, at boot. */
+  attach(): void;
+  /** Starts the clock for scheduled workflows and paused runs. */
+  start(): void;
+  stop(): Promise<void>;
+  /** Resolves once every run started in this process has finished. For tests and shutdown. */
+  idle(): Promise<void>;
+  private onContentEvent;
+  /**
+   * One look at the clock: start every scheduled workflow whose cron names this minute,
+   * and resume every paused run whose time has come. Safe to call from several
+   * processes — each claim is an atomic update.
+   */
+  tick(now?: Date): Promise<void>;
+  private startScheduled;
+  /** A run started by hand from the editor, executed inline so the caller sees the log. */
+  runManually(workflow: WorkflowRow$1, document: ContentRow | null): Promise<WorkflowRunRow$1>;
+  private enqueue;
+  private background;
+  /** Executes a queued or paused run from where it stands. The worker entry point. */
+  run(runId: string): Promise<void>;
+  /**
+   * Walks one chain — the top level, or a side of a fork — from `resume` when the run is
+   * being picked up inside it. A fork's chosen side is walked recursively; the position
+   * saved at a delay is the full path, so a resume finds its way back down.
+   */
+  private runChain;
+  private finish;
+  private spaceInfo;
+  private actorInfo;
+  private documentUrl;
+}
+/** Whether an event trigger wants this event for this document. */
+export declare function matchesEvent(trigger: WorkflowRow$1['trigger'], event: WorkflowEvent, row: Pick<ContentRecord, 'typeId' | 'locale'>): trigger is WorkflowEventTrigger;
+/** A row as a template sees it: plain JSON, without the search machinery. */
+export declare function serialise(row: ContentRecord | ContentRow): Record<string, unknown>;
+//#endregion
+//#region src/validate.d.ts
+/** 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;
+}
+/**
+ * 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 declare function validateWorkflow(input: WorkflowInput, env: ValidationEnvironment): ValidatedWorkflow;
+//#endregion
+//#region src/service.d.ts
+/** 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 declare class WorkflowService {
+  private readonly manablox;
+  private readonly repos;
+  private readonly engine;
+  constructor(manablox: Manablox, repos: Repositories, engine: WorkflowEngine);
+  catalog(): WorkflowCatalog;
+  list(spaceId: string): Promise<WorkflowRow[]>;
+  get(spaceId: string, id: string): Promise<WorkflowRow>;
+  create(spaceId: string, input: WorkflowInput): Promise<WorkflowRow>;
+  update(spaceId: string, id: string, input: WorkflowInput): Promise<WorkflowRow>;
+  /** The on/off switch, kept apart from a full save so the list can flip it. */
+  setEnabled(spaceId: string, id: string, enabled: boolean): Promise<WorkflowRow>;
+  delete(spaceId: string, id: string): Promise<void>;
+  runs(spaceId: string, id: string, limit?: number): Promise<WorkflowRunRow[]>;
+  run(spaceId: string, id: string): Promise<WorkflowRunRow>;
+  /**
+   * 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.
+   */
+  runNow(spaceId: string, id: string, contentId: string | null): Promise<WorkflowRunRow>;
+  subscriptions(userId: string): Promise<PushSubscriptionRow[]>;
+  subscribe(userId: string, subscription: {
+    endpoint: string;
+    keys: {
+      p256dh: string;
+      auth: string;
+    };
+  }, userAgent: string | null): Promise<PushSubscriptionRow>;
+  unsubscribe(userId: string, endpoint: string): Promise<void>;
+  private find;
+  private validationEnvironment;
+}
+//#endregion
+//#region src/steps.d.ts
+/** 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 declare function executeStep(step: WorkflowStep, context: WorkflowRunContext, env: StepEnvironment): Promise<StepOutcome>;
+//#endregion
+//#region src/template.d.ts
+/**
+ * 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.
+ */
+export declare function resolvePath(root: unknown, path: string): unknown;
+export declare function stringify(value: unknown): string;
+export declare function render(template: string, context: unknown): string;
+/**
+ * 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 declare function renderJson(template: string, context: unknown): string;
+/** Every placeholder a template names, for the editor's hints and for validation. */
+export declare function placeholders(template: string): string[];
+//#endregion
+export type { WorkflowRow, WorkflowRunRow };