@flow-engineer/flow 0.0.0-stage → 0.2.0

package/dist/flow-messaging/src/client.d.ts

@@ -0,0 +1,34 @@
+export declare const API_VERSION = "2026-11-01";
+/** The spec's typed error ({"error": {type, message, channel_code, retry_after, ...}}), or "network". */
+export declare class FlowMessagingError extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly channelCode?: string;
+    readonly retryAfter?: number;
+    constructor(status: number, type: string, message: string, extra?: {
+        channelCode?: string;
+        retryAfter?: number;
+    });
+    /** Worth trying again later: rate limits, Flow's or the channel's 5xx, no answer. */
+    get retryable(): boolean;
+}
+export declare class Client {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: {
+        apiKey: string;
+        baseUrl: string;
+    });
+    get<T>(path: string): Promise<T>;
+    /** A file's bytes: GET /v1/files/{id} answers them or redirects to a signed URL, which fetch follows without the key. */
+    download(fileId: string): Promise<Uint8Array>;
+    /** A POST with its own Idempotency-Key, kept across the retries of this one call; `tries: 1` for courtesies. */
+    post<T>(path: string, body: unknown, tries?: number): Promise<T>;
+    private request;
+}
+/**
+ * Flow-Signature: `t=<unix seconds>,v1=<hex>[,v1=<hex>]`. Each v1 is HMAC-SHA256, under one of the
+ * endpoint's signing secrets, of `t.<t>.<raw body>`; any match within five minutes of now passes
+ * (two secrets overlap while one is rotated).
+ */
+export declare function verifySignature(body: Buffer, header: string | undefined, secrets: string[], nowSeconds?: number): boolean;

package/dist/flow-messaging/src/client.js

@@ -0,0 +1,130 @@
+// A small client for Flow Messaging (api.flow.engineer), against its OpenAPI spec, version
+// 2026-11-01: plain fetch, only the calls the channels and the webhook make.
+//
+// Every POST carries an Idempotency-Key, and a retry repeats the same key, so a send is never made
+// twice. A 429 or a 5xx is tried again in place after its Retry-After when that is short; a longer
+// wait, or any other error, is raised as FlowMessagingError (the spec's typed error). Keys and
+// message text are never logged.
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+export const API_VERSION = "2026-11-01";
+const TRIES = 3;
+/** The longest Retry-After waited out in place (seconds); a longer one is the caller's. */
+const MAX_WAIT = 10;
+const TIMEOUT_MS = 20_000;
+/** How far a webhook's signed timestamp may be from now (seconds), as the spec says. */
+const SIGNATURE_TOLERANCE = 300;
+/** The spec's typed error ({"error": {type, message, channel_code, retry_after, ...}}), or "network". */
+export class FlowMessagingError extends Error {
+    status;
+    type;
+    channelCode;
+    retryAfter;
+    constructor(status, type, message, extra = {}) {
+        super(message);
+        this.name = "FlowMessagingError";
+        this.status = status;
+        this.type = type;
+        this.channelCode = extra.channelCode;
+        this.retryAfter = extra.retryAfter;
+    }
+    /** Worth trying again later: rate limits, Flow's or the channel's 5xx, no answer. */
+    get retryable() {
+        return this.status === 0 || this.status === 429 || this.status >= 500 || (this.type === "idempotency_conflict" && this.channelCode === "in_progress");
+    }
+}
+export class Client {
+    apiKey;
+    baseUrl;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        let end = options.baseUrl.length;
+        while (end > 0 && options.baseUrl[end - 1] === "/")
+            end--;
+        this.baseUrl = options.baseUrl.slice(0, end);
+    }
+    get(path) {
+        return this.request("GET", path);
+    }
+    /** A file's bytes: GET /v1/files/{id} answers them or redirects to a signed URL, which fetch follows without the key. */
+    async download(fileId) {
+        if (!this.apiKey)
+            throw new Error("set FLOW_MESSAGING_KEY (or pass apiKey) to reach Flow Messaging");
+        const response = await fetch(`${this.baseUrl}/v1/files/${fileId}`, { headers: { authorization: `Bearer ${this.apiKey}`, "flow-version": API_VERSION }, signal: AbortSignal.timeout(60_000) });
+        if (!response.ok)
+            throw await errorOf(response);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    /** A POST with its own Idempotency-Key, kept across the retries of this one call; `tries: 1` for courtesies. */
+    post(path, body, tries = TRIES) {
+        return this.request("POST", path, body, randomUUID(), tries);
+    }
+    async request(method, path, body, idempotencyKey, tries = TRIES) {
+        if (!this.apiKey)
+            throw new Error("set FLOW_MESSAGING_KEY (or pass apiKey) to reach Flow Messaging");
+        const headers = { authorization: `Bearer ${this.apiKey}`, "flow-version": API_VERSION };
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        if (idempotencyKey)
+            headers["idempotency-key"] = idempotencyKey;
+        let last;
+        for (let attempt = 1; attempt <= tries; attempt++) {
+            let response;
+            try {
+                response = await fetch(this.baseUrl + path, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(TIMEOUT_MS) });
+            }
+            catch (error) {
+                last = new FlowMessagingError(0, "network", `no answer from Flow Messaging (${error instanceof Error ? error.name : "error"})`);
+                if (attempt < tries)
+                    await wait(2 ** (attempt - 1));
+                continue;
+            }
+            if (response.ok) {
+                const text = await response.text();
+                return (text ? JSON.parse(text) : {});
+            }
+            last = await errorOf(response);
+            const pause = last.retryAfter ?? 2 ** (attempt - 1);
+            if (!last.retryable || attempt === tries || pause > MAX_WAIT)
+                throw last;
+            await wait(pause);
+        }
+        throw last;
+    }
+}
+async function errorOf(response) {
+    let body = {};
+    try {
+        const parsed = (await response.json());
+        if (parsed && typeof parsed.error === "object")
+            body = parsed.error;
+    }
+    catch { }
+    const header = Number(response.headers.get("retry-after"));
+    const retryAfter = typeof body.retry_after === "number" ? body.retry_after : Number.isFinite(header) && response.headers.has("retry-after") ? header : undefined;
+    const type = body.type ?? (response.status >= 500 ? "api_error" : "invalid_request");
+    return new FlowMessagingError(response.status, type, body.message ?? `Flow Messaging answered ${response.status}`, { channelCode: body.channel_code, retryAfter });
+}
+const wait = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
+/**
+ * Flow-Signature: `t=<unix seconds>,v1=<hex>[,v1=<hex>]`. Each v1 is HMAC-SHA256, under one of the
+ * endpoint's signing secrets, of `t.<t>.<raw body>`; any match within five minutes of now passes
+ * (two secrets overlap while one is rotated).
+ */
+export function verifySignature(body, header, secrets, nowSeconds = Date.now() / 1000) {
+    let stamp = "";
+    const given = [];
+    for (const part of (header ?? "").split(",")) {
+        const [key, value = ""] = part.trim().split("=", 2);
+        if (key === "t")
+            stamp = value;
+        else if (key === "v1" && value)
+            given.push(value);
+    }
+    if (!/^\d+$/.test(stamp) || !given.length || Math.abs(nowSeconds - Number(stamp)) > SIGNATURE_TOLERANCE)
+        return false;
+    const signed = Buffer.concat([Buffer.from(`t.${stamp}.`), body]);
+    return secrets.some((secret) => {
+        const expected = Buffer.from(createHmac("sha256", secret).update(signed).digest("hex"));
+        return given.some((value) => value.length === expected.length && timingSafeEqual(Buffer.from(value), expected));
+    });
+}

package/dist/flow-messaging/src/index.d.ts

@@ -0,0 +1,37 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type Agent, type Channel, type ChannelInfo, type WhatsAppFeature } from "../../src/index.ts";
+export { API_VERSION, FlowMessagingError, verifySignature } from "./client.ts";
+export interface FlowMessagingOptions {
+    /** The app's API key, `fk_live_...` or `fk_test_...`. Default: FLOW_MESSAGING_KEY (or the older FLOW_MESSAGING_API_KEY). */
+    apiKey?: string;
+    /** The webhook endpoint's signing secret(s), comma-separated while one is rotated. Default: FLOW_MESSAGING_WEBHOOK_SECRET. */
+    webhookSecret?: string;
+    /** Default: FLOW_MESSAGING_BASE_URL (or the older FLOW_MESSAGING_API_URL), else https://api.flow.engineer. */
+    baseUrl?: string;
+}
+export interface FlowChannelOptions {
+    /** The Flow sender (`snd_...`) this channel starts conversations from. Default: FLOW_MESSAGING_<CHANNEL>_SENDER. */
+    sender?: string;
+    /** The agent's name for the channel. Default: whatsapp, telegram or sms. */
+    name?: string;
+    instructions?: string;
+}
+/** What the webhook needs of an agent. */
+export type WebhookAgent = Pick<Agent, "message" | "reacted" | "undelivered">;
+/** Telegram as Flow sends it: an inline keyboard of up to 10 buttons (or one link), photos, Markdown, no read receipts for bots. */
+export declare const TELEGRAM: ChannelInfo;
+export declare function flowMessaging(options?: FlowMessagingOptions): {
+    whatsapp: (o?: FlowChannelOptions & {
+        disable?: WhatsAppFeature[];
+    }) => Channel;
+    telegram: (o?: FlowChannelOptions) => Channel;
+    sms: (o?: FlowChannelOptions) => Channel;
+    webhook: (agent: WebhookAgent) => (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    receive: (agent: WebhookAgent, request: {
+        body: Buffer | string;
+        headers: Record<string, string | string[] | undefined>;
+    }) => Promise<{
+        status: number;
+        body: string;
+    }>;
+};

package/dist/flow-messaging/src/index.js

@@ -0,0 +1,409 @@
+// Flow Framework channels on Flow Messaging (api.flow.engineer), Flow's unified messaging API: WhatsApp,
+// Telegram and US SMS from senders Flow hosts, and a webhook that turns Flow's signed events into
+// messages for the agent.
+//
+//   const fm = flowMessaging();                    // FLOW_MESSAGING_KEY, FLOW_MESSAGING_WEBHOOK_SECRET
+//   const agent = createAgent({ ..., channels: [fm.whatsapp(), fm.telegram(), fm.sms()] });
+//   http.createServer(fm.webhook(agent)).listen(8080);
+//
+// Addresses are what Flow Framework joins people by: the phone number on WhatsApp and SMS, the numeric
+// user id on Telegram. A reply goes into the Flow conversation the person last wrote in; with none
+// known yet (a nudge, or after a restart) it starts one from the channel's sender, which Flow puts
+// into the open conversation if there is one. What this process learns (conversations, contacts,
+// event ids) is kept in memory only.
+import { sms as smsChannel, whatsapp as whatsappChannel } from "../../src/index.js";
+import { Client, FlowMessagingError, verifySignature } from "./client.js";
+export { API_VERSION, FlowMessagingError, verifySignature } from "./client.js";
+/** Telegram as Flow sends it: an inline keyboard of up to 10 buttons (or one link), photos, Markdown, no read receipts for bots. */
+export const TELEGRAM = {
+    reactions: true,
+    status: false,
+    formatting: "markdown",
+    maxLength: 4096,
+    replies: true,
+    buttons: { max: 10, labelMax: 20 },
+    linkButton: { labelMax: 20 },
+    images: { captionMax: 1024 },
+    readReceipts: false,
+};
+/** Flow sends a list as buttons, whose labels take at most 20 characters, and has no row descriptions. */
+const LIST_TITLE_MAX = 20;
+const MAX_BODY_BYTES = 1_000_000;
+/** Event ids remembered to drop Flow's redeliveries (deliveries are at least once). */
+const SEEN_MAX = 10_000;
+export function flowMessaging(options = {}) {
+    const env = (...names) => names.map((n) => process.env[n]).find(Boolean);
+    const apiKey = options.apiKey ?? env("FLOW_MESSAGING_KEY", "FLOW_MESSAGING_API_KEY") ?? "";
+    const secrets = (options.webhookSecret ?? process.env.FLOW_MESSAGING_WEBHOOK_SECRET ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const client = new Client({ apiKey, baseUrl: options.baseUrl ?? env("FLOW_MESSAGING_BASE_URL", "FLOW_MESSAGING_API_URL") ?? "https://api.flow.engineer" });
+    const routes = [];
+    const flowConversation = new Map(); // channel + address -> Flow conversation id
+    const frameworkConversation = new Map(); // channel + address -> Flow Framework conversation id
+    const contacts = new Map(); // Flow contact id -> address
+    const templates = new Map(); // sender -> approved templates
+    const seen = new Set();
+    const handling = new Map();
+    const key = (channel, address) => `${channel}\u0000${address}`;
+    function register(kind, o) {
+        const route = { kind, name: o.name ?? kind, sender: o.sender ?? (process.env[`FLOW_MESSAGING_${kind.toUpperCase()}_SENDER`] || undefined) };
+        routes.push(route);
+        return route;
+    }
+    /** The Flow conversation to send into: the one the person wrote in, else the one a message they quote is in. */
+    async function conversationFor(channel, to, messageId) {
+        const known = flowConversation.get(key(channel, to));
+        if (known || !messageId)
+            return known;
+        const found = (await client.get(`/v1/messages/${messageId}`)).conversation;
+        flowConversation.set(key(channel, to), found);
+        return found;
+    }
+    function recipient(kind, to) {
+        if (to.startsWith("ct_"))
+            return { contact: to };
+        if (kind === "telegram")
+            return { telegram_user_id: to };
+        return { phone: to.startsWith("+") ? to : `+${to}` };
+    }
+    /** One message: into the person's conversation, or a new one from the channel's sender. */
+    async function send(route, to, content, replyTo, about = replyTo) {
+        try {
+            const conversation = await conversationFor(route.name, to, about);
+            let sent;
+            if (conversation)
+                sent = await client.post(`/v1/conversations/${conversation}/messages`, { content, ...(replyTo ? { reply_to: replyTo } : {}) });
+            else {
+                if (!route.sender)
+                    throw new Error(`no conversation with them on ${route.name} yet, and no sender to start one (set FLOW_MESSAGING_${route.kind.toUpperCase()}_SENDER)`);
+                sent = await client.post("/v1/messages", { sender: route.sender, to: recipient(route.kind, to), content });
+            }
+            flowConversation.set(key(route.name, to), sent.conversation);
+        }
+        catch (error) {
+            throw error instanceof FlowMessagingError ? new Error(reason(error)) : error;
+        }
+    }
+    /** Typing and read receipts are a courtesy: Flow's spec says to ignore their failures. */
+    async function courtesy(route, to, action, body, messageId) {
+        try {
+            const conversation = await conversationFor(route.name, to, messageId);
+            if (conversation)
+                await client.post(`/v1/conversations/${conversation}/${action}`, body, 1);
+        }
+        catch (error) {
+            console.warn(`@flow-engineer/flow/flow-messaging: ${action} on ${route.name} failed (${error instanceof FlowMessagingError ? error.type : "error"})`);
+        }
+    }
+    /**
+     * A message as Flow content. A link is a url button (WhatsApp's cta_url), a photo a media message
+     * with the text as its caption. Flow's button messages have no image header, so a photo with
+     * buttons or a link goes just before them, on its own.
+     */
+    function contents(kind, message) {
+        const buttons = message.link
+            ? [{ url: message.link.url, label: message.link.label }]
+            : message.buttons?.length
+                ? message.buttons.map((label) => ({ id: label, label }))
+                : message.list?.rows.map((row) => ({ id: row.id, label: row.title }));
+        const photo = message.image && { type: "media", kind: "image", url: message.image.url };
+        if (photo && !buttons)
+            return [{ ...photo, ...(message.text ? { caption: message.text } : {}) }];
+        const main = buttons ? { type: "buttons", text: message.text, buttons } : { type: "text", text: message.text, format: kind === "telegram" ? "markdown" : "plain" };
+        return photo ? [photo, main] : [main];
+    }
+    async function template(sender, wanted) {
+        if (wanted.name.startsWith("tpl_")) {
+            if (!wanted.language)
+                throw new Error(`template ${wanted.name} needs its language`);
+            return { id: wanted.name, language: wanted.language };
+        }
+        const find = () => templates.get(sender)?.find((t) => t.name === wanted.name && (!wanted.language || t.language === wanted.language));
+        if (!find()) {
+            const all = [];
+            let after = "";
+            for (;;) {
+                const page = await client.get(`/v1/templates?sender=${sender}&status=approved&limit=100${after ? `&after=${after}` : ""}`);
+                all.push(...page.data);
+                if (!page.has_more || !page.data.length)
+                    break;
+                after = page.data.at(-1).id;
+            }
+            templates.set(sender, all);
+        }
+        const found = find();
+        if (!found)
+            throw new Error(`no approved template named ${wanted.name}${wanted.language ? ` in ${wanted.language}` : ""} on this sender`);
+        return found;
+    }
+    function provider(route) {
+        return {
+            sendMessage: async (to, message) => {
+                const [first, ...rest] = contents(route.kind, message);
+                await send(route, to, first, message.replyTo);
+                for (const next of rest)
+                    await send(route, to, next);
+            },
+            react: (to, messageId, emoji) => send(route, to, { type: "reaction", message_id: messageId, emoji }, undefined, messageId),
+            typing: (to, on) => courtesy(route, to, "typing", { state: on ? "on" : "off" }),
+            markRead: (to, messageIds) => courtesy(route, to, "read", { up_to: messageIds.at(-1) }, messageIds.at(-1)),
+            sendTemplate: async (to, wanted) => {
+                if (!route.sender)
+                    throw new Error(`a template needs the channel's sender (set FLOW_MESSAGING_${route.kind.toUpperCase()}_SENDER)`);
+                const found = await template(route.sender, wanted);
+                const params = templateParams(wanted);
+                await send(route, to, { type: "template", template_id: found.id, language: wanted.language ?? found.language, ...(Object.keys(params).length ? { params } : {}) });
+            },
+        };
+    }
+    /** WhatsApp from a Flow sender: buttons (a list past 3), lists, link buttons, photos, quotes, reactions, typing, blue ticks, templates. */
+    function whatsapp(o = {}) {
+        const route = register("whatsapp", o);
+        const channel = whatsappChannel(provider(route), { name: route.name, disable: o.disable, instructions: o.instructions });
+        return { ...channel, info: { ...channel.info, ...(channel.info.lists ? { lists: { ...channel.info.lists, titleMax: LIST_TITLE_MAX } } : {}) } };
+    }
+    /** US SMS from a Flow number: plain text; STOP, START and HELP are Flow's. */
+    function sms(o = {}) {
+        const route = register("sms", o);
+        return smsChannel(provider(route), { name: route.name, instructions: o.instructions });
+    }
+    /** A Telegram bot connected to Flow. Flow Framework has no Telegram kind yet, so it is a custom channel. */
+    function telegram(o = {}) {
+        const route = register("telegram", o);
+        const p = provider(route);
+        return {
+            name: route.name,
+            kind: "custom",
+            info: TELEGRAM,
+            instructions: o.instructions,
+            send: (to, outbound) => {
+                switch (outbound.type) {
+                    case "message":
+                        return p.sendMessage(to, {
+                            text: outbound.text,
+                            ...(outbound.replyTo ? { replyTo: outbound.replyTo } : {}),
+                            ...(outbound.buttons ? { buttons: outbound.buttons } : {}),
+                            ...(outbound.link ? { link: outbound.link } : {}),
+                            ...(outbound.image ? { image: outbound.image } : {}),
+                        });
+                    case "reaction":
+                        return p.react(to, outbound.messageId, outbound.emoji);
+                    case "typing":
+                        return p.typing(to, outbound.on);
+                    case "template":
+                        throw new Error("Telegram has no templates");
+                    // read: Telegram bots cannot send read receipts; status: Telegram has no status line.
+                }
+            },
+        };
+    }
+    // ---- the webhook ----
+    function routeOf(event) {
+        const c = event.conversation;
+        if (!c)
+            return undefined;
+        return routes.find((r) => r.sender === c.sender) ?? routes.find((r) => r.kind === c.channel && !r.sender);
+    }
+    async function addressOf(route, contactId) {
+        const known = contacts.get(contactId);
+        if (known)
+            return known;
+        const contact = await client.get(`/v1/contacts/${contactId}`);
+        const address = (route.kind === "telegram" ? contact.address?.telegram_user_id : contact.address?.phone) ?? contactId;
+        contacts.set(contactId, address);
+        return address;
+    }
+    async function quoted(id) {
+        try {
+            const m = await client.get(`/v1/messages/${id}`);
+            const text = textOf(m.content);
+            return text ? { text, fromAgent: m.direction === "out" } : undefined;
+        }
+        catch {
+            return undefined; // past Flow's retention, or not known to it: the message reads without the quote
+        }
+    }
+    async function incoming(m) {
+        const c = m.content;
+        let base;
+        if (c.type === "text")
+            base = { text: String(c.text ?? "") };
+        else if (c.type === "button_reply") {
+            const id = String(c.button_id ?? "");
+            const title = String(c.label ?? id);
+            base = { text: title, choice: id && id !== title ? { id, title } : { title } };
+        }
+        else if (c.type === "voice" && c.transcript)
+            base = { text: String(c.transcript) }; // Flow transcribed it already
+        else if ((c.type === "voice" || c.type === "media") && c.file_id && c.kind !== "video") {
+            // Photos, audio and documents go as attachments, their bytes fetched from Flow only when the agent can use them.
+            const kind = c.type === "voice" || c.kind === "audio" ? "audio" : c.kind === "image" ? "image" : "document";
+            const fileId = String(c.file_id);
+            const attachment = { kind, mime: String(c.mime_type ?? "application/octet-stream"), ...(c.filename ? { name: String(c.filename) } : {}), data: () => client.download(fileId) };
+            base = { text: String(c.caption ?? ""), attachments: [attachment] };
+        }
+        else if (c.type === "media" || c.type === "file_blocked") {
+            // A video (Flow Framework reads none), or a file Flow did not keep: the caption, and what it was.
+            const what = String(c.kind ?? "file");
+            base = { text: [c.caption, c.type === "file_blocked" ? `[${what}: not received (${String(c.reason)})]` : `[${what}]`].filter(Boolean).join(" ") };
+        }
+        else if (c.type === "location")
+            base = { text: `[location: ${[c.name, c.address].filter(Boolean).join(", ")} (${c.lat}, ${c.lng})]` };
+        else if (c.type === "contact_card")
+            base = { text: `[contact: ${String(c.name ?? "")}]` };
+        else
+            return null; // reactions arrive as reaction.added
+        if (m.reply_to) {
+            const replyTo = await quoted(m.reply_to);
+            if (replyTo)
+                base.replyTo = replyTo;
+        }
+        return base;
+    }
+    async function handle(agent, event) {
+        if (event.type === "contact.deleted") {
+            // Flow erased the contact and their conversations: forget what this process keeps about them.
+            const id = event.data?.contact;
+            if (!id)
+                return;
+            const address = contacts.get(id);
+            contacts.delete(id);
+            for (const r of routes) {
+                for (const a of address ? [address, id] : [id]) {
+                    flowConversation.delete(key(r.name, a));
+                    frameworkConversation.delete(key(r.name, a));
+                }
+            }
+            return;
+        }
+        const route = routeOf(event);
+        if (!route || !event.conversation)
+            return;
+        const address = await addressOf(route, event.conversation.contact);
+        const person = key(route.name, address);
+        if (event.type === "message.received" && event.data?.message) {
+            flowConversation.set(person, event.conversation.id);
+            const message = await incoming(event.data.message);
+            if (!message)
+                return;
+            const arrived = await agent.message({ channel: route.name, from: address, message, messageId: event.data.message.id });
+            if (arrived)
+                frameworkConversation.set(person, arrived.conversationId);
+            return;
+        }
+        const conversationId = frameworkConversation.get(person);
+        if (!conversationId)
+            return; // not heard from since this process started: nothing to tell
+        if (event.type === "reaction.added" && event.data?.message_id && event.data.emoji) {
+            const target = await quoted(event.data.message_id);
+            if (target?.fromAgent)
+                agent.reacted(conversationId, event.data.emoji, target.text);
+        }
+        else if (event.type === "message.failed" && event.data?.message) {
+            const m = event.data.message;
+            const text = textOf(m.content);
+            const type = m.error?.type ?? "channel_error";
+            if (text)
+                agent.undelivered(conversationId, text, reason({ type, channelCode: m.error?.channel_code, message: m.error?.message ?? "The channel did not take it.", retryable: type === "api_error" || type === "rate_limited" }));
+        }
+    }
+    /**
+     * One delivery: checks Flow-Signature, drops a redelivered event, hands the event to the agent.
+     * 2xx tells Flow it arrived; a failure answers 500, so Flow delivers it again.
+     */
+    const noSecret = () => new Error("@flow-engineer/flow/flow-messaging: set FLOW_MESSAGING_WEBHOOK_SECRET (or pass webhookSecret)");
+    async function receive(agent, request) {
+        if (!secrets.length)
+            throw noSecret();
+        const raw = typeof request.body === "string" ? Buffer.from(request.body) : request.body;
+        const signature = request.headers["flow-signature"];
+        if (!verifySignature(raw, Array.isArray(signature) ? signature.join(",") : signature, secrets))
+            return { status: 401, body: '{"error":"bad signature"}' };
+        let event;
+        try {
+            event = JSON.parse(raw.toString("utf8"));
+        }
+        catch {
+            return { status: 400, body: '{"error":"not JSON"}' };
+        }
+        if (typeof event?.id !== "string" || typeof event.type !== "string")
+            return { status: 400, body: '{"error":"not an event"}' };
+        if (seen.has(event.id))
+            return { status: 200, body: "{}" };
+        let handled = handling.get(event.id);
+        if (!handled) {
+            handled = handle(agent, event);
+            handling.set(event.id, handled);
+        }
+        try {
+            await handled;
+            seen.add(event.id);
+            if (seen.size > SEEN_MAX)
+                seen.delete(seen.values().next().value);
+            return { status: 200, body: "{}" };
+        }
+        catch (error) {
+            console.warn(`@flow-engineer/flow/flow-messaging: event ${event.id} (${event.type}) failed: ${error instanceof FlowMessagingError ? error.type : error instanceof Error ? error.name : "error"}`);
+            return { status: 500, body: '{"error":"failed"}' };
+        }
+        finally {
+            handling.delete(event.id);
+        }
+    }
+    /** A Node http handler for the webhook endpoint: give it the requests to the URL Flow posts to. */
+    function webhook(agent) {
+        if (!secrets.length)
+            throw noSecret();
+        return async (req, res) => {
+            const answer = (status, body) => res.writeHead(status, { "content-type": "application/json" }).end(body);
+            if (req.method !== "POST")
+                return void answer(405, '{"error":"POST only"}');
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of req) {
+                size += chunk.length;
+                if (size > MAX_BODY_BYTES)
+                    return void answer(413, '{"error":"too large"}');
+                chunks.push(chunk);
+            }
+            const result = await receive(agent, { body: Buffer.concat(chunks), headers: req.headers });
+            answer(result.status, result.body);
+        };
+    }
+    return { whatsapp, telegram, sms, webhook, receive };
+}
+/** The text of a message's content, as the agent knew it. */
+function textOf(content) {
+    if (!content)
+        return "";
+    return String(content.text ?? content.caption ?? content.label ?? "");
+}
+/** A template's values as Flow's `params`: header, body (or the older `variables`, by number) and button values, each only when given. */
+function templateParams(t) {
+    const h = t.header;
+    const header = !h ? undefined : h.kind === "text" ? { kind: "text", text: h.text } : { kind: h.kind, ...(h.url ? { url: h.url } : {}), ...(h.fileId ? { file_id: h.fileId } : {}) };
+    let body = t.body;
+    if (!body) {
+        const values = Object.entries(t.variables ?? {});
+        if (values.every(([k]) => /^\d+$/.test(k)))
+            values.sort(([a], [b]) => Number(a) - Number(b));
+        body = values.map(([, v]) => v);
+    }
+    return {
+        ...(header ? { header } : {}),
+        ...(body.length ? { body } : {}),
+        ...(t.buttons?.length ? { buttons: t.buttons.map(({ index, value }) => ({ index, value })) } : {}),
+    };
+}
+/** Why a send did not reach the person, for the agent: Flow Framework's outside_window, else Flow's type and whether to resend. */
+function reason(e) {
+    const what = e.channelCode ? `${e.type} (${e.channelCode})` : e.type;
+    if (e.type === "outside_window" && e.channelCode === "quiet_hours")
+        return `${what}: it is night where they are; send it later`;
+    if (e.type === "outside_window")
+        return "outside_window";
+    if (e.channelCode === "channel_timeout_unknown_outcome")
+        return `${what}: it may have arrived; ask them before sending it again`;
+    if (e.retryable)
+        return `${what}: Flow Messaging could not send it now; it may go through later`;
+    return `${what}: ${e.message} It will fail again: don't resend it.`;
+}

package/dist/simulators/src/index.d.ts

@@ -0,0 +1,2 @@
+export { playgroundClock, simulators, type AgentConnection, type PlaygroundClock, type Line, type LinkCard, type Playground, type PlaygroundAgent, type SimulatorsOptions, type TestCloudSimulators } from "./server.ts";
+export { PLATFORMS, platform, channelOf, smsSegments, type Platform } from "./platforms.ts";

package/dist/simulators/src/index.js

@@ -0,0 +1,2 @@
+export { playgroundClock, simulators } from "./server.js";
+export { PLATFORMS, platform, channelOf, smsSegments } from "./platforms.js";