Agent feedback loop

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

export const exitInterview = defineJourney({
  meta: {
    id: "exit-interview",
    name: "Agentic — exit interview",
    enabled: true,
    trigger: {
      event: Events.TRIAL_COMPLETED,
      where: (b) => b.prop("converted").neq(true),
    },
    entryLimit: "once",
    suppress: hours(12),
    // Buying ends the conversation. Neither awaited event may appear here.
    exitOn: [{ event: Events.SUBSCRIPTION_CREATED }],
  },

  run: async (user, ctx) => {
    await sendEmail({
      to: user.email,
      userId: user.id,
      journeyStateId: user.stateId,
      template: Templates.FEEDBACK_EXIT_INTERVIEW, // "feedback/exit-interview"
      subject: "What stopped you?",
      journeyName: user.journeyName,
    });

    // The user's answer — EmailAction buttons fire churn.reason_provided.
    const answer = await ctx.waitForEvent({
      event: Events.CHURN_REASON_PROVIDED,
      timeout: days(5),
      label: "await-reason",
      lookback: minutes(30),
    });
    if (answer.timedOut) return; // never answered — leave them be

    // The agent's verdict. The confirmed answer is already on its way to the
    // agent as an email.action delivery; the agent fires
    // churn.followup_selected back. The lookback covers a verdict that landed
    // before this wait was established — the agent can decide in seconds.
    const verdict = await ctx.waitForEvent({
      event: Events.CHURN_FOLLOWUP_SELECTED,
      timeout: hours(6),
      label: "await-verdict",
      lookback: minutes(30),
    });

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

    const action = verdict.timedOut
      ? "none"
      : String(verdict.properties?.action ?? "none");

    if (action === "offer") {
      await sendEmail({
        to: user.email,
        userId: user.id,
        journeyStateId: user.stateId,
        template: Templates.FEEDBACK_SAVE_OFFER, // "feedback/save-offer"
        subject: "One more month on us",
        journeyName: user.journeyName,
      });
      return;
    }

    if (action === "handoff") {
      // scalars only — the alert task resolves identity server-side
      await ctx.trigger({
        event: Events.LEAD_FLAGGED,
        userId: user.id,
        properties: {
          reason: "exit-interview",
          answer: String(answer.properties?.reason ?? "unknown"),
          sourceEvent: Events.CHURN_REASON_PROVIDED,
          answeredAt: new Date().toISOString(),
        },
      });
    }
    // "none" or timeout — the answer is recorded; nothing else sends.
  },
});

// one-time setup, with a FULL-ADMIN key
import { Hogsend } from "@hogsend/client";

const admin = new Hogsend({
  baseUrl: process.env.HOGSEND_BASE_URL!,
  apiKey: process.env.HOGSEND_ADMIN_KEY!,
});

const endpoint = await admin.webhooks.create({
  url: "https://agent.example.com/hogsend/actions",
  eventTypes: ["email.action"], // confirmed semantic answers — nothing else
  description: "exit-interview agent",
});
// endpoint.secret ("whsec_…") is returned ONCE — store it as
// HOGSEND_WEBHOOK_SECRET on the agent service.

// the agent service — any HTTPS endpoint you run
import express from "express";
import { Hogsend, verifyHogsendWebhook } from "@hogsend/client";
import { decideFollowup } from "./decide.js"; // your agent: LLM, rules, queue

const hs = new Hogsend({
  baseUrl: process.env.HOGSEND_BASE_URL!,
  apiKey: process.env.HOGSEND_DATA_KEY!, // ingest scope — verdicts are events
});

const app = express();

app.post(
  "/hogsend/actions",
  express.raw({ type: "application/json" }), // keep the raw bytes
  async (req, res) => {
    let event: { id: string; type: string; timestamp: string; data: unknown };
    try {
      event = verifyHogsendWebhook({
        payload: req.body.toString("utf8"),
        headers: req.headers as Record<string, string>,
        secret: process.env.HOGSEND_WEBHOOK_SECRET!,
      }) as typeof event;
    } catch {
      return res.sendStatus(401);
    }

    const data = event.data as {
      event: string;
      properties: Record<string, unknown> | null;
      userId: string | null;
    };
    if (
      event.type !== "email.action" ||
      data.event !== "churn.reason_provided" ||
      !data.userId
    ) {
      return res.sendStatus(200); // not ours — acknowledge and drop
    }

    const action = await decideFollowup(data.userId, data.properties);

    // The verdict is a plain event. Keying it on the delivery id makes the
    // at-least-once webhook stream exactly-once at the decision layer.
    await hs.events.send({
      name: "churn.followup_selected",
      userId: data.userId,
      eventProperties: { action },
      idempotencyKey: `verdict-${event.id}`,
    });

    return res.sendStatus(200);
  },
);

// src/journeys/constants/index.ts
export const Events = {
  TRIAL_COMPLETED: "trial.completed",
  SUBSCRIPTION_CREATED: "subscription.created",
  CHURN_REASON_PROVIDED: "churn.reason_provided",
  CHURN_FOLLOWUP_SELECTED: "churn.followup_selected",
  LEAD_FLAGGED: "lead.flagged",
} as const;

export const Templates = {
  FEEDBACK_EXIT_INTERVIEW: "feedback/exit-interview",
  FEEDBACK_SAVE_OFFER: "feedback/save-offer",
} as const;