Failed payment dunning

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

export const dunning = defineJourney({
  meta: {
    id: "dunning",
    name: "Billing — failed payment dunning",
    enabled: true,
    trigger: { event: Events.INVOICE_PAYMENT_FAILED },
    // a card that keeps failing re-enters at most once a week
    entryLimit: "once_per_period",
    entryPeriod: days(7),
    suppress: hours(4),
    exitOn: [
      { event: Events.INVOICE_PAID },         // recovered — stop immediately
      { event: Events.SUBSCRIPTION_DELETED }, // cancelled — stop dunning
    ],
  },

  run: async (user, ctx) => {
    // Immediately: most failures are a stale card, not a churn decision.
    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.BILLING_PAYMENT_FAILED, // "billing/payment-failed"
      subject: "Your payment didn't go through",
      journeyName: user.journeyName,
    });

    // Stripe retries on its own schedule — give the first retry three days.
    const firstRetry = await ctx.waitForEvent({
      event: Events.INVOICE_PAID,
      timeout: days(3),
      label: "await-first-retry",
    });
    if (!firstRetry.timedOut) return; // recovered — exitOn already handled it
    if (!(await ctx.guard.isSubscribed())) return;

    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.BILLING_UPDATE_CARD, // "billing/update-card"
      subject: "Action needed: update your payment method",
      journeyName: user.journeyName,
    });

    const secondRetry = await ctx.waitForEvent({
      event: Events.INVOICE_PAID,
      timeout: days(4),
      label: "await-second-retry",
    });
    if (!secondRetry.timedOut) return;
    if (!(await ctx.guard.isSubscribed())) return;

    // Day 7: final notice to the customer…
    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.BILLING_FINAL_NOTICE, // "billing/final-notice"
      subject: "Final notice: your subscription will be paused",
      journeyName: user.journeyName,
    });

    // …and the failure leaves the email channel: flag it for a human.
    await ctx.trigger({
      event: Events.DUNNING_EXHAUSTED,
      userId: user.id,
      userEmail: user.email,
      properties: { stage: "final-notice", source: "dunning" },
    });
  },
});

# .env
STRIPE_WEBHOOK_SECRET=whsec_...

// src/webhook-sources/billing.ts
import { defineWebhookSource } from "@hogsend/engine";
import { z } from "zod";

const schema = z.object({
  id: z.string(),
  type: z.string(),
  customer: z.object({ id: z.string(), email: z.string().optional() }),
  invoice: z.object({ id: z.string(), amount_due: z.number() }).optional(),
});

export const billingSource = defineWebhookSource({
  meta: { id: "billing", name: "Billing provider" },
  auth: {
    type: "signature",
    scheme: "hmac-hex", // HMAC_SHA256(secret, rawBody), lowercase hex
    envKey: "BILLING_WEBHOOK_SECRET",
    header: "x-signature",
  },
  schema,
  async transform(payload) {
    if (
      payload.type !== "invoice.payment_failed" &&
      payload.type !== "invoice.paid"
    ) {
      return null; // accept-and-skip everything else
    }
    return {
      event: payload.type, // the same names the journey triggers on
      userId: payload.customer.id,
      userEmail: payload.customer.email ?? "", // "" when unknown, never undefined
      eventProperties: {
        source: "billing",
        invoiceId: payload.invoice?.id ?? null,
        amountDue: payload.invoice?.amount_due ?? null,
      },
      idempotencyKey: payload.id, // dedupe at-least-once redeliveries
    };
  },
});

// src/workflows/dunning-alert.ts
import { hatchet } from "@hogsend/engine";
import { getContainer } from "../container.js"; // your app's process-wide client
import { Events, Templates } from "../journeys/constants/index.js";

const ALERT_TO = process.env.BILLING_ALERT_EMAIL ?? "ops@example.com";

export const dunningAlertTask = hatchet.durableTask({
  name: "dunning-alert",
  onEvents: [Events.DUNNING_EXHAUSTED],
  retries: 2,
  executionTimeout: "10m",
  fn: async (input: {
    userId: string;
    userEmail: string;
    properties: Record<string, string | number | boolean | null>;
  }) => {
    const { emailService } = getContainer();

    const result = await emailService.send({
      template: Templates.INTERNAL_DUNNING_ALERT, // "internal/dunning-alert"
      to: ALERT_TO,
      subject: `[Dunning] Recovery failed — ${input.userEmail}`,
      props: {
        customerEmail: input.userEmail,
        stage: String(input.properties.stage ?? ""),
      },
      // Operator mail: the customer's unsubscribe must never gate it, and the
      // registry's "transactional" category wins.
      skipPreferenceCheck: true,
      // A task retry after a successful send reuses the prior email_sends row.
      idempotencyKey: `dunning-alert:${input.userId}:${input.properties.stage}`,
    });

    return { status: result.status, emailSendId: result.emailSendId };
  },
});

// src/journeys/constants/index.ts
export const Events = {
  INVOICE_PAYMENT_FAILED: "invoice.payment_failed",
  INVOICE_PAID: "invoice.paid",
  SUBSCRIPTION_DELETED: "subscription.deleted",
  DUNNING_EXHAUSTED: "dunning.exhausted",
} as const;

export const Templates = {
  BILLING_PAYMENT_FAILED: "billing/payment-failed",
  BILLING_UPDATE_CARD: "billing/update-card",
  BILLING_FINAL_NOTICE: "billing/final-notice",
  INTERNAL_DUNNING_ALERT: "internal/dunning-alert",
} as const;