Trial conversion sequence

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

export const trialOnboarding = defineJourney({
  meta: {
    id: "trial-onboarding",
    name: "Conversion — trial onboarding",
    enabled: true,
    trigger: { event: Events.TRIAL_STARTED },
    entryLimit: "once",
    suppress: hours(12),
    exitOn: [
      { event: Events.SUBSCRIPTION_CREATED },
      { event: Events.USER_DELETED },
    ],
  },

  run: async (user, ctx) => {
    // Day 1 — one concrete outcome, not a feature tour.
    await ctx.sleep({ duration: days(1), label: "day-1" });
    if (!(await ctx.guard.isSubscribed())) return;

    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.TRIAL_FIRST_VALUE, // "trial/first-value"
      subject: "Get your first result today",
      journeyName: user.journeyName,
    });

    // Mid-trial — branch on what they actually did.
    await ctx.sleep({ duration: days(3), label: "mid-trial" });
    if (!(await ctx.guard.isSubscribed())) return;

    const usage = await ctx.history.hasEvent({
      userId: user.id,
      event: Events.FEATURE_USED,
      within: days(4),
    });

    if (usage.count >= 3) {
      // Engaged — sell the paid tier on what they already use.
      await sendEmail({
        to: user.email,
        userId: user.id,
        journeyStateId: user.stateId,
        template: Templates.TRIAL_UPGRADE_VALUE, // "trial/upgrade-value"
        subject: "You're getting value — here's what Pro adds",
        journeyName: user.journeyName,
        props: { usageCount: usage.count },
      });
    } else {
      // Cold — conversion needs activation first, not a pitch.
      await sendEmail({
        to: user.email,
        userId: user.id,
        journeyStateId: user.stateId,
        template: Templates.TRIAL_ACTIVATION_NUDGE, // "trial/activation-nudge"
        subject: "Three days in — the fastest path to a result",
        journeyName: user.journeyName,
      });
    }
  },
});

// src/buckets/trial-expiring-soon.ts (ships in the scaffold)
import { days, defineBucket } from "@hogsend/engine";

export const trialExpiringSoon = defineBucket({
  meta: {
    id: "trial-expiring-soon",
    name: "Trial expiring soon",
    enabled: true,
    entryLimit: "once",
    // Unconditional time-box: out 14 days after joining, no matter what.
    maxDwell: days(14),
    criteria: (b) =>
      b.all(
        b.prop("plan").eq("trial"),
        b.prop("trial_days_left").lte(3),
        b.prop("converted").neq(true),
      ),
  },
});

// src/journeys/trial-expiring.ts
import { days, hours } from "@hogsend/engine";
import { defineJourney, sendEmail } from "@hogsend/engine";
// Leaf module, not ../buckets/index.js — reading a typed ref through the
// barrel inside meta would close an ESM cycle.
import { trialExpiringSoon } from "../buckets/trial-expiring-soon.js";
import { Events, Templates } from "./constants/index.js";

export const trialExpiring = defineJourney({
  meta: {
    id: "trial-expiring",
    name: "Conversion — trial expiring",
    enabled: true,
    // typed ref — a misspelled bucket id is a compile error
    trigger: { event: trialExpiringSoon.entered },
    entryLimit: "once",
    suppress: hours(12),
    exitOn: [
      { event: trialExpiringSoon.left },      // converted or trial extended
      { event: Events.SUBSCRIPTION_CREATED },
    ],
  },

  run: async (user, ctx) => {
    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.TRIAL_EXPIRING_SOON, // "trial/expiring-soon"
      subject: "Your trial ends in 3 days",
      journeyName: user.journeyName,
      props: { daysLeft: Number(user.properties.trial_days_left ?? 3) },
    });

    // Two days for them to upgrade on their own → last call lands at T-1.
    const { timedOut } = await ctx.waitForEvent({
      event: Events.SUBSCRIPTION_CREATED,
      timeout: days(2),
      label: "await-upgrade",
    });
    if (!timedOut) return; // they upgraded — exitOn already handled it
    if (!(await ctx.guard.isSubscribed())) return;

    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.TRIAL_LAST_DAY, // "trial/last-day"
      subject: "Last day — keep what you've built",
      journeyName: user.journeyName,
    });
  },
});

// your app server
import { hs } from "./lib/hogsend.js";

await hs.events.send({
  name: "app.active",
  userId: account.ownerId,
  email: account.ownerEmail,
  eventProperties: { source: "session" },
  // Profile state → the contact record; bucket membership re-evaluates on ingest.
  contactProperties: {
    plan: account.plan,                    // "trial" | "pro" | …
    trial_days_left: account.trialDaysLeft,
    converted: account.hasSubscription,
  },
});

// src/journeys/constants/index.ts
export const Events = {
  TRIAL_STARTED: "trial.started",
  SUBSCRIPTION_CREATED: "subscription.created",
  FEATURE_USED: "feature.used",
  USER_DELETED: "user.deleted",
} as const;

export const Templates = {
  TRIAL_FIRST_VALUE: "trial/first-value",
  TRIAL_ACTIVATION_NUDGE: "trial/activation-nudge",
  TRIAL_UPGRADE_VALUE: "trial/upgrade-value",
  TRIAL_EXPIRING_SOON: "trial/expiring-soon",
  TRIAL_LAST_DAY: "trial/last-day",
} as const;