Usage limit upgrade

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

export const usageLimitUpgrade = defineJourney({
  meta: {
    id: "usage-limit-upgrade",
    name: "Conversion — usage limit upgrade",
    enabled: true,
    trigger: {
      event: Events.USAGE_THRESHOLD_REACHED,
      // below 80% is not pressure — those events never enter the journey
      where: (b) => b.prop("usage_pct").gte(80),
    },
    entryLimit: "once_per_period",
    entryPeriod: days(30), // one nudge sequence per billing cycle
    suppress: hours(24),
    // usage.limit_hit is deliberately NOT here — the journey reacts to it.
    exitOn: [{ event: Events.SUBSCRIPTION_UPGRADED }],
  },

  run: async (user, ctx) => {
    // The trigger event's scalar properties ride in on user.properties.
    const usagePct = Number(user.properties.usage_pct ?? 80);
    const metric = String(user.properties.metric ?? "usage");

    // First touch — headroom is still optional, sell it as such.
    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.USAGE_APPROACHING_LIMIT, // "usage/approaching-limit"
      subject: `You've used ${usagePct}% of your plan`,
      journeyName: user.journeyName,
      props: { usagePct, metric },
    });

    // Second touch only if they actually hit the wall.
    const wall = await ctx.waitForEvent({
      event: Events.USAGE_LIMIT_HIT,
      timeout: days(14),
      label: "await-limit-hit",
    });
    if (wall.timedOut) return; // never hit 100% — one nudge was enough

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

    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.USAGE_LIMIT_HIT, // "usage/limit-hit"
      subject: "You've hit your plan limit",
      journeyName: user.journeyName,
      props: {
        metric: String(wall.properties?.metric ?? metric),
        blockedCount: Number(wall.properties?.blocked_count ?? 0),
      },
    });
  },
});

// your metering job
import { hs } from "./lib/hogsend.js";

// crossing a threshold — enrolls the journey when usage_pct >= 80
await hs.events.send({
  name: "usage.threshold_reached",
  userId: account.id,
  email: account.ownerEmail,
  eventProperties: {
    usage_pct: 82,
    metric: "events", // flat scalars — the journey branches on these
    period: "2026-06",
  },
  idempotencyKey: `usage-80-${account.id}-2026-06`,
});

// the wall — emitted by the limiter the first time a request is blocked
await hs.events.send({
  name: "usage.limit_hit",
  userId: account.id,
  eventProperties: { metric: "events", blocked_count: 1, period: "2026-06" },
  idempotencyKey: `usage-100-${account.id}-2026-06`,
});

// src/journeys/constants/index.ts
export const Events = {
  USAGE_THRESHOLD_REACHED: "usage.threshold_reached",
  USAGE_LIMIT_HIT: "usage.limit_hit",
  SUBSCRIPTION_UPGRADED: "subscription.upgraded",
} as const;

export const Templates = {
  USAGE_APPROACHING_LIMIT: "usage/approaching-limit",
  USAGE_LIMIT_HIT: "usage/limit-hit",
} as const;