Workflows

A workflow lets Litestore follow up on something days after it happened, for example by emailing a shopper a day after they abandon a cart. Read this page when you need to add a delayed or repeated follow-up to an event.

A workflow pairs a domain event with an async function. The function receives the event payload and a durable step object.

All of the workflow code is in modules/email/automations.ts. It contains a type, a builder and a WORKFLOWS array with three entries. The domain-event handler in jobs/domain-events.ts runs every entry that matches the event.

Litestore has no separate workflow engine. You write the order of steps and the delays as plain code that calls Inngest's own step.sleep and step.run. A follow-up that spans several days therefore needs no state machine, no scheduler table and no job to reconcile them.

Step object

The type has only two methods on purpose. A workflow can pause, and it can run a side effect whose result is remembered. It can do nothing else:

type WorkflowStep = {
  /** Suspend for a duration ("3d", "2h") — the reaction resumes later, durably. */
  sleep: (id: string, duration: string) => Promise<void>
  /** Run + memoise a side effect so it fires exactly once across resumes. */
  run: <T>(id: string, fn: () => Promise<T>) => Promise<T>
}

type Workflow = {
  event: DomainEventType
  name: string
  run: (payload: unknown, step: WorkflowStep) => Promise<void>
}

Where you define a workflow, the workflow() builder gives the payload the type of its event. It then stores the result as a plain Workflow. Workflows are type-safe while you write them, and the array can still hold workflows for different events. workflowsFor(event) is the only code that reads the array.

Runtime

Every domain-event function runs its workflows at the very end, after it has cleared caches, sent webhooks and run the handler body:

for (const flow of workflowsFor(eventType)) {
  await flow.run(stripPayloadMeta(payload), {
    sleep: (id, duration) => step.sleep(`${flow.name}:${id}`, duration),
    run: <T>(id: string, fn: () => Promise<T>) =>
      step.run(`${flow.name}:${id}`, fn) as Promise<T>,
  })
}

Litestore prefixes each step id with the workflow's name. Two workflows on the same event therefore can never use the same step id. If no workflow matches an event, nothing runs.

Built-in workflows

Shared behavior

Each delay is a typed constant in platform/config/email-automations.ts, not an admin setting. To change one, edit the constant and redeploy. A value of zero or less turns that step off. If SIGNUP_NUDGE_DAYS is 0, the nudge never goes out. If REVIEW_REMINDER_DAYS is 0, the customer gets the review request but no reminder.

All three send classification: "marketing" email through queueEmail. The unsubscribe check and the List-Unsubscribe headers in jobs/email.send.ts therefore apply to them.

All three look up the customer's email address at the moment of sending, through customerContact. It returns null when the customer has no email on file.

The workflows check things again because hours or days have passed while they slept. The cart, order or coupon may have changed since the workflow started waiting.

jobs/referral.reward.ts works differently. The payment webhook works out the wake-up date from REFERRAL_REWARD_HOLD_DAYS when the event is sent and puts it in the event payload, so a run that is already waiting keeps the date it started with.

Durable waits and polling crons

Both durable waits and polling crons run work later. The abandoned-cart flow uses both, which makes the difference easy to see.

Crons

Crons exist to detect conditions. No event is sent when a cart goes quiet, when a Stripe webhook never arrives, or when a shipment misses its estimated date. Nobody is there to send it.

So cron.abandoned-carts.ts checks for idle carts every 30 minutes and emits cart.abandoned for each. From then on, the recovery-drip workflow takes over with real durable waits. The cron detects the cart, and the workflow follows up.

cron detects an idle cart
    ↓
emits cart.abandoned
    ↓
recovery-drip sleeps, re-checks, sends

Event-triggered functions

jobs/ has four more functions that are neither crons nor domain-event handlers. Each one listens for its own event name, and Litestore registers each on its own in app/api/inngest/route.ts.

Mechanisms

A workflow follows one specific item forward in time. A cron goes looking for items that nobody announced.

Related