/** * Sequence-execution engine. * * Two entry points: * - `startSequenceRun()` — called by the trigger worker. Materialises * an EmailSequenceRun row + a pending Step-0 delivery + schedules * the first step. * - `advanceSequenceRun()` — called by the step-runner after a step * completes. Materialises the next step's delivery row + schedules * it; flips the run to `completed` when no more steps remain. * * Storage + queue are injected so the engine stays testable. */ import type { SequenceDefinition, SequenceStep, SequenceTriggerContext } from "./types.js"; import { parseSequenceSteps } from "./types.js"; import { evaluateAllConditions } from "./conditions.js"; export type SequenceRunStatus = "pending" | "running" | "completed" | "cancelled" | "unsubscribed" | "failed"; export type StepDeliveryStatus = "pending" | "sent" | "skipped" | "bounced" | "failed"; export interface SequenceRunRow { readonly id: string; readonly sequenceId: string; readonly leadId: string | null; readonly tenantId: string | null; readonly triggerEventId: string | null; readonly status: SequenceRunStatus; readonly startedAt: Date; readonly completedAt: Date | null; readonly stepStateJson: Readonly> | null; } export interface StepDeliveryRow { readonly id: string; readonly runId: string; readonly stepIndex: number; readonly status: StepDeliveryStatus; readonly scheduledAt: Date; } /** * Storage surface required by the engine. Implementations wrap Prisma * (in the worker) or in-memory fakes (in tests). */ export interface SequenceEngineStore { createRun(input: { sequenceId: string; leadId: string | null; tenantId: string | null; triggerEventId: string | null; }): Promise; /** Idempotent — returns the existing run if `(sequenceId,triggerEventId)` already exists. */ findRunByTrigger(sequenceId: string, triggerEventId: string): Promise; updateRunStatus(runId: string, status: SequenceRunStatus, completedAt?: Date | null): Promise; createDelivery(input: { runId: string; stepIndex: number; scheduledAt: Date }): Promise; } /** * Queue surface — `scheduleStep` enqueues a delayed job that wakes up * at `runAt` and invokes the step-runner. */ export interface SequenceEngineQueue { scheduleStep(args: { runId: string; stepIndex: number; runAt: Date }): Promise; } export interface SequenceEngineLogger { info?: (record: Record, message?: string) => void; warn?: (record: Record, message?: string) => void; error: (record: Record, message?: string) => void; } export interface SequenceEngineDeps { readonly store: SequenceEngineStore; readonly queue: SequenceEngineQueue; readonly logger?: SequenceEngineLogger; readonly now?: () => Date; } export interface StartSequenceRunArgs { readonly sequence: SequenceDefinition; readonly trigger: SequenceTriggerContext; } export interface StartSequenceRunResult { readonly run: SequenceRunRow; readonly firstDelivery: StepDeliveryRow | null; readonly scheduled: boolean; /** True when an existing run was returned instead of inserting a duplicate. */ readonly alreadyExisted: boolean; } /** * Resolve the steps array, applying sequence-level enable + condition * gating before producing the first delivery row. */ export async function startSequenceRun( args: StartSequenceRunArgs, deps: SequenceEngineDeps ): Promise { const { sequence, trigger } = args; if (!sequence.isEnabled) { return emptyResult(); } if (!evaluateAllConditions(trigger.payload, sequence.conditions)) { deps.logger?.info?.( { op: "sequence.skipped.sequence_conditions", sequenceId: sequence.id }, "sequence-level conditions not met" ); return emptyResult(); } const steps = parseSequenceSteps(sequence.steps as unknown); if (steps.length === 0) { return emptyResult(); } if (trigger.triggerEventId) { const existing = await deps.store.findRunByTrigger(sequence.id, trigger.triggerEventId); if (existing) { return { run: existing, firstDelivery: null, scheduled: false, alreadyExisted: true }; } } const run = await deps.store.createRun({ sequenceId: sequence.id, leadId: trigger.leadId ?? null, tenantId: trigger.tenantId ?? null, triggerEventId: trigger.triggerEventId ?? null, }); const firstStep = steps[0]!; const now = (deps.now ?? (() => new Date()))(); const scheduledAt = new Date(now.getTime() + firstStep.delayHours * 60 * 60 * 1000); const delivery = await deps.store.createDelivery({ runId: run.id, stepIndex: firstStep.stepIndex, scheduledAt, }); await deps.queue.scheduleStep({ runId: run.id, stepIndex: firstStep.stepIndex, runAt: scheduledAt }); deps.logger?.info?.( { op: "sequence.run.started", sequenceId: sequence.id, runId: run.id, stepIndex: firstStep.stepIndex }, "sequence run started" ); return { run, firstDelivery: delivery, scheduled: true, alreadyExisted: false }; } function emptyResult(): StartSequenceRunResult { const placeholder: SequenceRunRow = { id: "", sequenceId: "", leadId: null, tenantId: null, triggerEventId: null, status: "cancelled", startedAt: new Date(0), completedAt: null, stepStateJson: null, }; return { run: placeholder, firstDelivery: null, scheduled: false, alreadyExisted: false }; } export interface AdvanceArgs { readonly run: SequenceRunRow; readonly steps: readonly SequenceStep[]; readonly previousStepIndex: number; } export interface AdvanceResult { readonly nextDelivery: StepDeliveryRow | null; readonly scheduledAt: Date | null; readonly completed: boolean; } /** * After a step finishes (sent, skipped or bounced) move to the next. * Marks the run completed when no further step exists. */ export async function advanceSequenceRun(args: AdvanceArgs, deps: SequenceEngineDeps): Promise { const { run, steps, previousStepIndex } = args; const sorted = [...steps].sort((a, b) => a.stepIndex - b.stepIndex); const nextIdx = sorted.findIndex((s) => s.stepIndex > previousStepIndex); if (nextIdx === -1) { await deps.store.updateRunStatus(run.id, "completed", (deps.now ?? (() => new Date()))()); deps.logger?.info?.({ op: "sequence.run.completed", runId: run.id }, "sequence run completed"); return { nextDelivery: null, scheduledAt: null, completed: true }; } const nextStep = sorted[nextIdx]!; const now = (deps.now ?? (() => new Date()))(); const scheduledAt = new Date(now.getTime() + nextStep.delayHours * 60 * 60 * 1000); const delivery = await deps.store.createDelivery({ runId: run.id, stepIndex: nextStep.stepIndex, scheduledAt, }); await deps.queue.scheduleStep({ runId: run.id, stepIndex: nextStep.stepIndex, runAt: scheduledAt }); return { nextDelivery: delivery, scheduledAt, completed: false }; }