Abandoned cart recovery

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

export const abandonedCart = defineJourney({
  meta: {
    id: "abandoned-cart",
    name: "E-commerce — abandoned cart",
    enabled: true,
    trigger: {
      event: Events.CHECKOUT_STARTED,
      // carts under $25 never enter the journey at all
      where: (b) => b.prop("cart_value").gte(25),
    },
    entryLimit: "once_per_period",
    entryPeriod: days(7),
    suppress: hours(12),
    exitOn: [{ event: Events.CHECKOUT_COMPLETED }],
  },

  run: async (user, ctx) => {
    // The trigger event's scalar properties ride in on user.properties.
    const cartId = String(user.properties.cart_id ?? "");
    const cartValue = Number(user.properties.cart_value ?? 0);

    // Give the purchase four hours to complete on its own.
    const first = await ctx.waitForEvent({
      event: Events.CHECKOUT_COMPLETED,
      timeout: hours(4),
      label: "await-checkout",
    });
    if (!first.timedOut) return; // they bought — nothing to recover

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

    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.ECOMMERCE_CART_REMINDER, // "ecommerce/cart-reminder"
      subject: "You left items in your cart",
      journeyName: user.journeyName,
      props: { cartId, cartValue },
    });

    // One more day. exitOn still covers a purchase mid-wait.
    const second = await ctx.waitForEvent({
      event: Events.CHECKOUT_COMPLETED,
      timeout: days(1),
      label: "await-checkout-2",
    });
    if (!second.timedOut) return;

    // Land the last call at 09:30 in the shopper's own timezone.
    await ctx.sleepUntil(ctx.when.nextLocal("09:30"), {
      label: "morning-send",
    });
    if (!(await ctx.guard.isSubscribed())) return;

    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.ECOMMERCE_CART_LAST_CALL, // "ecommerce/cart-last-call"
      subject: "Your cart is about to expire",
      journeyName: user.journeyName,
      props: { cartId, cartValue },
    });
  },
});

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

// checkout reached — starts the race
await hs.events.send({
  name: "checkout.started",
  email: customer.email,
  userId: customer.id,
  eventProperties: {
    cart_id: cart.id,
    cart_value: cart.subtotal,
    item_count: cart.items.length,
  },
  idempotencyKey: `checkout-started-${cart.id}`,
});

// order placed — exits the journey and resolves both waits
await hs.events.send({
  name: "checkout.completed",
  userId: customer.id,
  eventProperties: { cart_id: cart.id, order_id: order.id, revenue: order.total },
  idempotencyKey: `checkout-completed-${order.id}`,
});

// src/journeys/constants/index.ts
export const Events = {
  CHECKOUT_STARTED: "checkout.started",
  CHECKOUT_COMPLETED: "checkout.completed",
} as const;

export const Templates = {
  ECOMMERCE_CART_REMINDER: "ecommerce/cart-reminder",
  ECOMMERCE_CART_LAST_CALL: "ecommerce/cart-last-call",
} as const;