Journeys

// src/journeys/activation-welcome.ts
import { days, hours } from "@hogsend/core";
import { defineJourney, sendEmail } from "@hogsend/engine";
import { Events, Templates } from "./constants/index.js";

export const activationWelcome = defineJourney({
  meta: {
    id: "activation-welcome",
    name: "Activation — Welcome Series",
    enabled: true,
    trigger: { event: Events.USER_CREATED },
    entryLimit: "once",
    suppress: hours(12),
    exitOn: [{ event: Events.USER_DELETED }],
  },

  run: async (user, ctx) => {
    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.ACTIVATION_WELCOME,
      subject: "Welcome to Hogsend — let's get you set up",
      journeyName: user.journeyName,
    });

    await ctx.sleep({ duration: days(2), label: "post-welcome" });

    const { found: hasUsedFeature } = await ctx.history.hasEvent({
      userId: user.id,
      event: Events.FEATURE_USED,
    });

    if (hasUsedFeature) {
      await sendEmail({
        to: user.email,
        userId: user.id,
        journeyStateId: user.stateId,
        template: Templates.ACTIVATION_ADVANCED,
        subject: "Nice work — here's what to try next",
        journeyName: user.journeyName,
      });
    } else {
      await sendEmail({
        to: user.email,
        userId: user.id,
        journeyStateId: user.stateId,
        template: Templates.ACTIVATION_NUDGE,
        subject: "You haven't tried the key feature yet",
        journeyName: user.journeyName,
      });
    }
  },
});

import { defineJourney } from "@hogsend/engine";

export const myJourney = defineJourney({
  meta: { /* JourneyMeta */ },
  run: async (user, ctx) => { /* your logic */ },
});

interface JourneyMeta {
  id: string;
  name: string;
  description?: string;
  enabled: boolean;

  trigger: {
    event: string;
    where?: PropertyCondition[];
  };

  entryLimit: "once" | "once_per_period" | "unlimited";
  entryPeriod?: DurationObject;

  exitOn?: Array<{
    event: string;
    where?: PropertyCondition[];
  }>;

  suppress: DurationObject;
}

// User can re-enter churn recovery every 7 days
meta: {
  entryLimit: "once_per_period",
  entryPeriod: days(7),
  // ...
}

trigger: {
  event: Events.SUBSCRIPTION_CANCELLED,
  where: [
    {
      type: "property",
      property: "plan",
      operator: "eq",
      value: "pro",
    },
  ],
}

exitOn: [
  { event: Events.PAYMENT_SUCCEEDED },
  { event: Events.SUBSCRIPTION_CANCELLED },
  { event: Events.USER_DELETED },
],

run: async (user: JourneyUser, ctx: JourneyContext) => {
  // your journey logic
}

interface JourneyUser {
  id: string;
  email: string;
  properties: Record<string, string | number | boolean | null>;
  stateId: string;
  journeyId: string;
  journeyName: string;
}

sleep(opts: {
  duration: DurationObject;
  label?: string;
}): Promise<{ sleptAt: string; resumedAt: string }>

await ctx.sleep({ duration: days(2), label: "post-welcome" });
await ctx.sleep({ duration: hours(4), label: "cooldown" });
await ctx.sleep({ duration: minutes(30), label: "short-wait" });

sleepUntil(at: Date | string, opts?: {
  label?: string;
}): Promise<{ sleptAt: string; resumedAt: string }>

// Resume at a fixed deadline
await ctx.sleepUntil("2026-07-01T09:00:00Z", { label: "renewal-day" });

// Pair it with ctx.when (below) for timezone-aware scheduling
await ctx.sleepUntil(ctx.when.tomorrow().at("09:00"), { label: "morning-send" });

ctx.when.next(weekday).at("HH:mm")   // upcoming named weekday → Date
ctx.when.nextLocal("HH:mm")          // next HH:mm (today if still ahead, else tomorrow) → Date
ctx.when.tomorrow().at("HH:mm")      // tomorrow at HH:mm → Date
ctx.when.in(days(3)).at("HH:mm")     // 3 days out, at HH:mm that day → Date

// chainable refinements — each returns a new builder:
ctx.when.tz("Asia/Tokyo")            // override the resolved timezone
ctx.when.window("09:00", "17:00")    // override the send window for this chain
ctx.when.ifPast("now")               // "next" (default) rolls forward; "now" clamps to now

// Next Monday at 9am, in the user's timezone
await ctx.sleepUntil(ctx.when.next("monday").at("09:00"), { label: "monday-9am" });

// Tomorrow morning, in a fixed timezone instead of the user's
await ctx.sleepUntil(ctx.when.tz("America/New_York").tomorrow().at("08:00"));

// Five days out, clamped into business hours
const at = ctx.when.in(days(5)).window("09:00", "17:00").at("14:00");
await ctx.sleepUntil(at, { label: "day-5-followup" });

waitForEvent(opts: {
  event: string;
  timeout: DurationObject;
  label?: string;
}): Promise<{ timedOut: boolean }>

// After signup, wait up to 7 days for activation. If it never comes, nudge.
run: async (user, ctx) => {
  const { timedOut } = await ctx.waitForEvent({
    event: Events.FEATURE_USED,
    timeout: days(7),
    label: "await-activation",
  });

  if (!timedOut) return; // they activated on their own — nothing to do

  if (!(await ctx.guard.isSubscribed())) return;

  await sendEmail({
    to: user.email,
    userId: user.id,
    journeyStateId: user.stateId,
    template: Templates.ACTIVATION_NUDGE,
    subject: "Still haven't tried the key feature?",
    journeyName: user.journeyName,
  });
};

checkpoint(label: string): Promise<void>

await ctx.checkpoint("branch:paid-path");
// ... continue execution

trigger(opts: {
  event: string;
  userId: string;
  userEmail?: string;
  properties?: Record<string, unknown>;
}): Promise<void>

await ctx.trigger({
  event: Events.USER_SUPPRESSED,
  userId: user.id,
  properties: {
    reason: "dormancy_sequence_completed",
    suppressedAt: new Date().toISOString(),
  },
});

const subscribed = await ctx.guard.isSubscribed();
if (!subscribed) return; // exit journey early

hasEvent(opts: {
  userId: string;
  event: string;
  within?: DurationObject;
}): Promise<{ found: boolean; count: number }>

// Has the user used a feature at all?
const { found } = await ctx.history.hasEvent({
  userId: user.id,
  event: Events.FEATURE_USED,
});

// Has the user used a feature in the last 2 days?
const { found, count } = await ctx.history.hasEvent({
  userId: user.id,
  event: Events.FEATURE_USED,
  within: days(2),
});

journey(opts: {
  userId: string;
  journeyId: string;
}): Promise<{
  completed: boolean;
  lastCompletedAt: string | null;
  entryCount: number;
}>

const { completed, entryCount } = await ctx.history.journey({
  userId: user.id,
  journeyId: "activation-welcome",
});

if (!completed) {
  // user never finished onboarding
}

email(opts: {
  email: string;
  template: string;
}): Promise<{
  sent: boolean;
  lastSentAt: string | null;
  count: number;
}>

const { sent, count } = await ctx.history.email({
  email: user.email,
  template: Templates.ACTIVATION_WELCOME,
});

if (sent) {
  // skip duplicate send
}

import { days, hours, minutes } from "@hogsend/engine";

days(3)      // { hours: 72 }
hours(12)    // { hours: 12 }
minutes(30)  // { minutes: 30 }

interface DurationObject {
  readonly hours?: number;
  readonly minutes?: number;
  readonly seconds?: number;
}

suppress: hours(12),
entryPeriod: days(7),
await ctx.sleep({ duration: days(2) });
await ctx.history.hasEvent({ userId, event, within: days(3) });

// src/journeys/constants/index.ts
export const Events = {
  USER_CREATED: "user.created",
  USER_DELETED: "user.deleted",
  FEATURE_USED: "feature.used",
  TRIAL_STARTED: "trial.started",
  PAYMENT_FAILED: "payment.failed",
  PAYMENT_SUCCEEDED: "payment.succeeded",
  SUBSCRIPTION_CANCELLED: "subscription.cancelled",
  // ... more events your product emits
} as const;

export type EventName = (typeof Events)[keyof typeof Events];

export const Templates = {
  ACTIVATION_WELCOME: "activation/welcome",
  ACTIVATION_ADVANCED: "activation/advanced",
  ACTIVATION_NUDGE: "activation/nudge",
  CHURN_PAYMENT_FAILED: "churn-payment-failed",
  // ... more template keys (must exist in the email registry)
} as const;

export type TemplateName = (typeof Templates)[keyof typeof Templates];

import { Events, Templates } from "./constants/index.js";

start -> active -> waiting (sleep / waitForEvent) -> active (on resume) -> completed
                                                                        -> failed (on error)
                                                                        -> exited (exitOn / cancel)

# Enable specific journeys by ID
ENABLED_JOURNEYS=activation-welcome,churn-prevention

# Enable all journeys (default)
ENABLED_JOURNEYS=*

// src/journeys/conversion-abandoned-checkout.ts
import { days, hours } from "@hogsend/core";
import { defineJourney, sendEmail } from "@hogsend/engine";
import { Events, Templates } from "./constants/index.js";

export const conversionAbandonedCheckout = defineJourney({
  meta: {
    id: "conversion-abandoned-checkout",
    name: "Conversion — Abandoned Checkout",
    enabled: true,
    trigger: { event: Events.CHECKOUT_ABANDONED },
    entryLimit: "once_per_period",
    entryPeriod: days(7),
    suppress: hours(4),
    exitOn: [
      { event: Events.CHECKOUT_COMPLETED },
      { event: Events.USER_DELETED },
    ],
  },

  run: async (user, ctx) => {
    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.CONVERSION_WINBACK_OFFER,
      subject: "You left something behind",
      journeyName: user.journeyName,
    });

    await ctx.sleep({ duration: days(1), label: "day-1-followup" });

    const { found } = await ctx.history.hasEvent({
      userId: user.id,
      event: Events.CHECKOUT_COMPLETED,
      within: days(1),
    });

    if (!found) {
      await sendEmail({
        to: user.email,
        userId: user.id,
        journeyStateId: user.stateId,
        template: Templates.CONVERSION_WINBACK_OFFER,
        subject: "Still interested? Here's 10% off",
        journeyName: user.journeyName,
        props: { discountPercent: 10 },
      });
    }
  },
});

// src/journeys/index.ts
import type { DefinedJourney } from "@hogsend/engine";
import { conversionAbandonedCheckout } from "./conversion-abandoned-checkout.js";
import { welcome } from "./welcome.js";

export const journeys: DefinedJourney[] = [
  welcome,
  conversionAbandonedCheckout,
];

// src/index.ts (HTTP)
import { createApp, createHogsendClient } from "@hogsend/engine";
import { journeys } from "./journeys/index.js";
import { webhookSources } from "./webhook-sources/index.js";

const container = createHogsendClient({ journeys });
const app = createApp(container, { webhookSources });

// src/worker.ts (task execution)
import { createHogsendClient, createWorker } from "@hogsend/engine";
import { journeys } from "./journeys/index.js";

const container = createHogsendClient({ journeys });
const worker = createWorker({ container, journeys });
await worker.start();

import { days, hours } from "@hogsend/core";
import { defineJourney, sendEmail } from "@hogsend/engine";
import { Events, Templates } from "./constants/index.js";

export const churnPrevention = defineJourney({
  meta: {
    id: "churn-prevention",
    name: "Churn — Payment Recovery & Prevention",
    enabled: true,
    trigger: { event: Events.PAYMENT_FAILED },
    entryLimit: "once_per_period",
    entryPeriod: days(7),
    suppress: hours(4),
    exitOn: [
      { event: Events.PAYMENT_SUCCEEDED },
      { event: Events.SUBSCRIPTION_CANCELLED },
      { event: Events.USER_DELETED },
    ],
  },

  run: async (user, ctx) => {
    // Immediate: let them know
    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.CHURN_PAYMENT_FAILED,
      subject: "Your payment didn't go through",
      journeyName: user.journeyName,
    });

    await ctx.sleep({ duration: days(1), label: "first-retry" });

    // Day 1: check if they fixed it
    const { found: hasRetried } = await ctx.history.hasEvent({
      userId: user.id,
      event: Events.PAYMENT_SUCCEEDED,
      within: days(1),
    });
    if (hasRetried) return;

    // Day 1: gentle reminder
    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.CHURN_PAYMENT_FAILED,
      subject: "Reminder: please update your payment method",
      journeyName: user.journeyName,
      props: { gracePeriodDays: 2 },
    });

    await ctx.sleep({ duration: days(2), label: "final-notice" });

    // Day 3: final warning
    const { found: hasResolved } = await ctx.history.hasEvent({
      userId: user.id,
      event: Events.PAYMENT_SUCCEEDED,
      within: days(3),
    });
    if (!hasResolved) {
      await sendEmail({
        to: user.email,
        userId: user.id,
        journeyStateId: user.stateId,
        template: Templates.CHURN_PAYMENT_FAILED,
        subject: "Final notice: your account will be downgraded tomorrow",
        journeyName: user.journeyName,
        props: { gracePeriodDays: 1 },
      });
    }
  },
});