Concierge onboarding

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

export const conciergeOnboarding = defineJourney({
  meta: {
    id: "concierge-onboarding",
    name: "Onboarding — enterprise concierge",
    enabled: true,
    trigger: {
      event: Events.USER_SIGNED_UP,
      // self-serve plans take the automated welcome journey instead
      where: (b) => b.prop("plan").eq("enterprise"),
    },
    entryLimit: "once",
    suppress: hours(12),
    // a booked meeting means onboarding is in human hands — stop all of this.
    // The awaited csm.contacted event must NEVER appear here.
    exitOn: [{ event: Events.MEETING_BOOKED }],
  },

  run: async (user, ctx) => {
    const seats = Number(user.properties.seats ?? 0);

    // Page a human. A real ingested event — the csm-alert task (onEvents)
    // emails the CSM inbox with the account context.
    await ctx.trigger({
      event: Events.CSM_ASSIGNMENT_REQUESTED,
      userId: user.id,
      properties: {
        plan: "enterprise",
        seats,
        requestedAt: new Date().toISOString(),
      },
    });
    await ctx.checkpoint("csm-paged");

    // Park until the CSM marks contact — one event from their tool or CRM.
    let contact = await ctx.waitForEvent({
      event: Events.CSM_CONTACTED,
      timeout: days(1),
      label: "await-csm",
    });

    if (contact.timedOut) {
      // A day of silence: re-page. The fresh requestedAt gives the alert
      // task a new idempotency key, so the reminder isn't deduped against
      // the first page.
      await ctx.trigger({
        event: Events.CSM_ASSIGNMENT_REQUESTED,
        userId: user.id,
        properties: {
          plan: "enterprise",
          seats,
          requestedAt: new Date().toISOString(),
          reminder: true,
        },
      });

      contact = await ctx.waitForEvent({
        event: Events.CSM_CONTACTED,
        timeout: days(1),
        label: "await-csm-2",
        // covers a csm.contacted that landed between the two waits
        lookback: hours(1),
      });
    }

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

    if (contact.timedOut) {
      // Two days, no human: the customer never waits on an absent CSM.
      await sendEmail({
        to: user.email,
        userId: user.id,
        journeyStateId: user.stateId,
        template: Templates.ONBOARDING_ENTERPRISE_WELCOME, // "onboarding/enterprise-welcome"
        subject: "Getting your team set up",
        journeyName: user.journeyName,
      });
      return;
    }

    // The CSM's event carries who reached out — it flows straight into the
    // customer-facing email as a typed template prop.
    const csmName = String(contact.properties?.csm_name ?? "your account team");

    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.ONBOARDING_CONCIERGE_INTRO, // "onboarding/concierge-intro"
      subject: "Next steps for your rollout",
      journeyName: user.journeyName,
      props: { csmName },
    });
  },
});

// src/workflows/csm-alert.ts
import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
import { hatchet } from "@hogsend/engine";
import { getContainer } from "../container.js";
import { Events, Templates } from "../journeys/constants/index.js";

/** The CSM team inbox — operational mail to operators, never a contact. */
const CSM_INBOX = process.env.CSM_ALERT_EMAIL ?? "csm@example.com";

/** The ingest pipeline's Hatchet push payload. */
interface AssignmentRequestedInput {
  userId: JsonValue;
  userEmail: JsonValue;
  properties: JsonValue;
  [key: string]: JsonValue;
}

export const csmAlertTask = hatchet.durableTask({
  name: "csm-alert",
  onEvents: [Events.CSM_ASSIGNMENT_REQUESTED],
  retries: 2,
  executionTimeout: "15m",
  fn: async (input: AssignmentRequestedInput) => {
    const { emailService } = getContainer();

    const userId = typeof input.userId === "string" ? input.userId : "";
    if (!userId) return { status: "skipped", reason: "missing_user_id" };
    const customerEmail =
      typeof input.userEmail === "string" ? input.userEmail : userId;

    const props = (input.properties ?? {}) as Record<
      string,
      string | number | boolean | null
    >;
    const reminder = props.reminder === true;
    const requestedAt = String(props.requestedAt ?? new Date().toISOString());

    const result = await emailService.send({
      template: Templates.TRANSACTIONAL_CSM_ALERT, // "transactional/csm-alert"
      to: CSM_INBOX,
      subject: reminder
        ? `[CSM — reminder] enterprise signup waiting: ${customerEmail}`
        : `[CSM] new enterprise signup: ${customerEmail}`,
      props: {
        customerEmail,
        customerId: userId,
        seats: Number(props.seats ?? 0),
        reminder,
        requestedAt,
      },
      // Registry "transactional" wins (no category override), and the
      // customer's unsubscribe state never gates operator mail.
      skipPreferenceCheck: true,
      // requestedAt is part of the key, so the journey's re-page (a fresh
      // timestamp) sends — but a task retry of the SAME page doesn't.
      idempotencyKey: `csm-alert:${userId}:${requestedAt}`,
    });
    return { status: result.status };
  },
});

// CRM automation or internal tool
import { hs } from "./lib/hogsend.js";

await hs.events.send({
  name: "csm.contacted",
  userId: "user_123", // the customer's id — the wait is scoped to them
  eventProperties: { csm_name: "Sarah", channel: "email" },
});

await hs.events.send({
  name: "meeting.booked",
  userId: "user_123",
  eventProperties: { meeting_at: "2026-06-18T15:00:00Z" },
});

// src/journeys/constants/index.ts
export const Events = {
  USER_SIGNED_UP: "user.signed_up",
  CSM_ASSIGNMENT_REQUESTED: "csm.assignment_requested",
  CSM_CONTACTED: "csm.contacted",
  MEETING_BOOKED: "meeting.booked",
} as const;

export const Templates = {
  ONBOARDING_CONCIERGE_INTRO: "onboarding/concierge-intro",
  ONBOARDING_ENTERPRISE_WELCOME: "onboarding/enterprise-welcome",
  TRANSACTIONAL_CSM_ALERT: "transactional/csm-alert",
} as const;