Business events

{
  "id": "evt_01J9Z6",
  "type": "order.shipped",
  "occurredAt": "2026-10-20T14:05:00Z",
  "subject": "order:4821",
  "delivery": "critical",
  "data": {
    "user": { "phone": "+15550001234" },
    "consent": { "whatsappUpdates": true },
    "order": { "number": "4821", "carrier": "Parcelco", "trackingUrl": "https://shop.example/t/4821" }
  }
}

{ "id": "evt_01J9Z7", "type": "notification.cancelled", "occurredAt": "2026-10-20T14:06:00Z",
  "subject": "order:4821", "data": { "cancels": "evt_01J9Z6" } }

import { createHmac } from "node:crypto";

const body = JSON.stringify(event);
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac("sha256", process.env.FLOW_EVENTS_SECRET).update(`t.${t}.${body}`).digest("hex");
await fetch("https://agent.example/v1/events", {
  method: "POST",
  headers: { "content-type": "application/json", "flow-signature": `t=${t},v1=${v1}` },
  body,
});

const keepMePosted = tool({
  name: "keep_me_posted",
  description: "Save a topic the person asked to be kept posted on, after they said yes.",
  input: z.object({ topic: z.string(), title: z.string().optional() }),
  run: ({ topic, title }, context) => {
    if (!context.events || !context.address) return { saved: false };
    // The address the events are sent to: on WhatsApp, their number in E.164, as `addressOf` reads it.
    return { saved: context.events.watch({ address: context.address, topic, title }).outcome };
  },
});

testList: eventTestList({ testing: false, madeUp: /^\+1555/ })

import { createAgent, eventTestList, flowEvents, whatsapp, type BusinessEvent, type EventCatalog } from "@flow-engineer/flow";

const order = (e: BusinessEvent) => e.data.order ?? {};

const catalog: EventCatalog = {
  "order.shipped": {
    level: "critical",
    topic: (e) => e.subject,
    message: (e) => {
      const o = order(e);
      if (!o.trackingUrl) return { missing: "data.order.trackingUrl" };
      return {
        template: { name: "order_shipped", body: [o.number, o.carrier] },
        text: `Order ${o.number} shipped with ${o.carrier}.`,
        values: [o.number, o.carrier],
        link: { label: "Track it", url: o.trackingUrl },
      };
    },
  },
  "order.delayed": {
    level: "standard",
    liveOnly: true,
    topic: (e) => e.subject,
    message: (e) => {
      const o = order(e);
      if (!o.newDate) return { missing: "data.order.newDate" };
      return {
        template: { name: "order_delayed", body: [o.number, o.newDate] },
        text: `Order ${o.number} is running late; it should arrive ${o.newDate}.`,
        values: [o.number, o.newDate],
        link: { label: "See order", url: `https://shop.example/o/${o.number}` },
      };
    },
  },
  restock: {
    level: "optional", // posted with a collapseKey, such as "restock:sku-19"
    topic: (e) => e.subject,
    message: (e) => ({
      template: { name: "back_in_stock", body: [e.data.item] },
      text: `${e.data.item} is back in stock.`,
      values: [e.data.item],
      link: { label: "Shop now", url: e.data.url },
    }),
  },
};

const events = flowEvents({ secret: process.env.FLOW_EVENTS_SECRET, catalog, timezone: "America/New_York", testList: eventTestList() });

const agent = createAgent({
  // ...dir, model, tools, templates
  channels: [whatsapp(provider)],
  // A phrased notification is checked before it goes; { refuse } sends nothing and tells the agent why.
  beforeSend: (message, { address }) => {
    const why = events.phrasing.check(address, message);
    return why ? { refuse: why } : undefined;
  },
  routes: events.routes,
  onTick: events.onTick,
  context: (conversationId) => events.context(conversationId),
});
events.attach(agent);