@flow-engineer/flow 0.2.0 → 0.2.1

package/flow-messaging/README.md

@@ -1,9 +1,13 @@
 # Flow Messaging channels
 
-Put a Flow Framework (`npm i @flow-engineer/flow`) agent on real WhatsApp, Telegram and US SMS
+Put a Flow Framework (`npm i @flow-engineer/flow`) agent on real WhatsApp, Telegram, iMessage and US SMS
 through [Flow Messaging](https://api.flow.engineer) (API version 2026-11-01). `@flow-engineer/flow/flow-messaging` gives you
-channels that send through Flow's senders, and a webhook that checks Flow's signed events and hands
-them to the agent. It needs nothing beyond the framework (it uses `fetch` and `node:crypto`).
+channels that send through Flow's senders, and two ways to receive Flow's events: the live event
+stream, an outbound WebSocket that needs no public URL, and a webhook that checks Flow's
+signatures. It needs nothing beyond the framework (it uses `fetch`, Node's `WebSocket` and `node:crypto`).
+
+On a laptop, `npx @flow-engineer/flow link` signs in, writes `FLOW_MESSAGING_KEY` and the Telegram
+sender into `.env` and prints the link for your phone, so you can skip step 1 below.
 
 ```sh
 npm install @flow-engineer/flow
@@ -26,7 +30,8 @@ Each sender has an ID (`snd_...`), a link to open on your phone, and a join code
 
 The sandbox has Telegram today. WhatsApp and iMessage come as they open. A sandbox key lasts 7 days
 and covers one contact. Live keys (`fk_live_...`) and your own WhatsApp, Telegram or
-SMS senders are set up from the dashboard at https://api.flow.engineer.
+SMS senders are set up from the dashboard at https://api.flow.engineer. iMessage lines, Flow's
+shared one included, are arranged with the Flow team.
 
 Open the Telegram sandbox sender's link on your phone and send its join code. You are now the
 sandbox contact your agent can talk to.
@@ -35,31 +40,58 @@ sandbox contact your agent can talk to.
 
 ```ts
 // main.ts
-import { createServer } from "node:http";
 import { createAgent } from "@flow-engineer/flow";
 import { flowMessaging } from "@flow-engineer/flow/flow-messaging";
 
-const fm = flowMessaging(); // reads FLOW_MESSAGING_KEY and FLOW_MESSAGING_WEBHOOK_SECRET
+const fm = flowMessaging(); // reads FLOW_MESSAGING_KEY (and FLOW_MESSAGING_WEBHOOK_SECRET for a webhook)
 
 const agent = createAgent({
   dir: "./agent", // your agent's folder (AGENTS.md, ...)
   model: yourModel,
   // only the channels you have senders for
-  channels: [fm.telegram(), fm.whatsapp(), fm.sms()],
+  channels: [fm.telegram(), fm.whatsapp(), fm.imessage(), fm.sms()],
 });
 await agent.resume();
 
-createServer(fm.webhook(agent)).listen(Number(process.env.PORT ?? 8080));
+const live = fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor" });
+live.stopped.then((why) => console.error(`Flow Messaging refused the stream: ${why.message}`));
 ```
 
-Already have an HTTP server? Hand the raw body and headers to `fm.receive` instead:
+That's it on a laptop: with no webhook secret, `fm.start` opens the event stream (`fm.stream(agent)`
+does only that).
+
+### The event stream
+
+`GET /v1/stream` is a WebSocket the agent opens to Flow, with the key offered as a subprotocol
+(Node's `WebSocket` cannot set headers). It asks only for the events the adapter handles and hands
+each, in log order, to the same handler as the webhook.
+
+- **Acknowledged once handled.** The stream has no ack frame for events; it resumes from `after`.
+  The adapter moves its cursor past an event only once the agent has taken it, so an event that
+  fails, or arrives as the socket drops, comes again.
+- **Reconnects.** A dropped socket, Flow's `reconnect` frame (it restarts, or a connection reaches
+  24 hours) and a failed event reconnect with `after` set to the last handled event: at once the
+  first time, then backing off to 30 s, or after Flow's `retry_after` (too many streams for the
+  key, Flow busy). An event that fails 5 times in a row is passed over, so it cannot hold up every
+  later one; it stays in Flow's log (`GET /v1/events`).
+- **Offline messages.** With `cursorFile`, the last handled event's ID is kept on disk, so after a
+  restart Flow replays everything that came while the agent was stopped, for as long as your plan
+  keeps events (30 days by default). Without it, a dropped stream still resumes, but a restart
+  starts from now. A cursor older than Flow's log starts again from now, and says so.
+- **Stops for good** on a refused key or request (close codes 4401, 4403, 4400): `stopped`
+  resolves with the code, type and Flow's message. `close()` ends the stream.
+- **Replies go over HTTP**, with their Idempotency-Keys, so they never wait for the stream.
+- The stream cannot send `Flow-Version`, so its events come in the version your app was pinned to.
+
+### Or a webhook
+
+Already have an HTTP server? Hand the raw body and headers to `fm.receive`, or serve `fm.webhook(agent)`
+(with a webhook secret set, `fm.start` serves it on `port`, default `PORT` else 8080):
 
 ```ts
 const { status, body } = await fm.receive(agent, { body: rawBody, headers: req.headers });
 ```
 
-### 3. Point Flow's webhook at it
-
 Flow posts events to a public HTTPS URL. Create a webhook endpoint for it:
 
 ```sh
@@ -72,32 +104,31 @@ curl https://api.flow.engineer/v1/webhook_endpoints \
 The answer holds the signing secret (`secret`, `whsec_...`), shown once. Save it as
 `FLOW_MESSAGING_WEBHOOK_SECRET`.
 
-On a laptop there is no public URL. Run a tunnel to the port (for example
-`cloudflared tunnel --url http://localhost:8080`) and register that URL.
+On a laptop there is no public URL: use the event stream instead.
 
 ## Environment
 
 | Variable | What it is |
 |---|---|
 | `FLOW_MESSAGING_KEY` | Your app's API key, `fk_test_...` or `fk_live_...`. Keep it on your server. |
-| `FLOW_MESSAGING_WEBHOOK_SECRET` | The webhook endpoint's signing secret, `whsec_...`. While you rotate it, give both, comma-separated. |
-| `FLOW_MESSAGING_TELEGRAM_SENDER`, `FLOW_MESSAGING_WHATSAPP_SENDER`, `FLOW_MESSAGING_SMS_SENDER` | Each channel's sender, `snd_...`. Needed to start conversations (nudges, templates) and to tell senders apart. Replies to people who wrote first work without it. |
+| `FLOW_MESSAGING_WEBHOOK_SECRET` | The webhook endpoint's signing secret, `whsec_...`. While you rotate it, give both, comma-separated. Without it, `fm.start` uses the event stream. |
+| `FLOW_MESSAGING_TELEGRAM_SENDER`, `FLOW_MESSAGING_WHATSAPP_SENDER`, `FLOW_MESSAGING_IMESSAGE_SENDER`, `FLOW_MESSAGING_SMS_SENDER` | Each channel's sender, `snd_...`. Needed to start conversations (nudges, templates) and to tell senders apart. Replies to people who wrote first work without it. |
 | `FLOW_MESSAGING_BASE_URL` | Optional. Default `https://api.flow.engineer`. |
 
 Each of these can also be passed in code: `flowMessaging({ apiKey, webhookSecret, baseUrl })`, and
-`fm.telegram({ sender, name, instructions })` (the same for `whatsapp` and `sms`).
+`fm.telegram({ sender, name, instructions })` (the same for `whatsapp`, `imessage` and `sms`).
 
 ## What it maps
 
 **Out (agent to person):**
 
-- Text: Markdown on Telegram, plain text on WhatsApp and SMS.
+- Text: Markdown on Telegram, plain text on WhatsApp, iMessage and SMS.
 - Reply buttons and lists, sent as Flow `buttons`. WhatsApp shows up to 3 reply buttons, or a list
-  for 4 to 10. Telegram shows an inline keyboard.
-- A link: one URL button (WhatsApp's call-to-action button).
+  for 4 to 10. Telegram shows an inline keyboard. iMessage has none, so the agent is not offered them.
+- A link: one URL button (WhatsApp's call-to-action button); on iMessage, the URL on its own line.
 - 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.
-- Quotes (`reply_to`), reactions, typing, and read receipts (WhatsApp).
+- Quotes (`reply_to`), reactions (tapbacks on iMessage), typing, and read receipts (WhatsApp, iMessage).
 - WhatsApp templates, by name or `tpl_` ID, with their header (text, or media by URL or file ID),
   body values (`{{1}}`, `{{2}}`, ...) and button values (URL suffixes, quick-reply payloads).
 
@@ -122,24 +153,32 @@ Each of these can also be passed in code: `flowMessaging({ apiKey, webhookSecret
   template.
 - A permanent refusal (opted out, no consent, ...) reaches the agent once, with "don't resend it".
 - Signatures are checked: HMAC-SHA256, five minutes' tolerance, and any of the secrets you gave.
-- An event Flow delivers twice reaches the agent once. A failure answers 500, so Flow delivers the
-  event again.
+- An event Flow delivers twice (or by both the stream and a webhook) reaches the agent once. On the
+  webhook a failure answers 500, so Flow delivers the event again; on the stream it comes again on
+  the next connection.
 - `contact.deleted` makes it forget the contact.
 - Keys and message text are never logged.
 
-What it remembers (conversations, contacts, event IDs) is kept in memory. After a restart, the
+What it remembers (conversations, contacts, event IDs) is kept in memory, except the stream's
+`cursorFile`. After a restart, the
 first send to someone starts from the channel's sender, and Flow puts it into the open conversation
 if there is one.
 
-The framework has no Telegram channel kind yet, so Telegram is a custom channel. iMessage is not in this
-package yet.
+The framework has no Telegram or iMessage channel kind yet, so both are custom channels. On iMessage
+a person is their phone number, or their email address when that is their handle; they are not joined
+with the same number on WhatsApp or SMS.
+
+**iMessage replies only.** On Flow's shared iMessage sender (as on WhatsApp after 24 hours) the agent
+can only answer someone who wrote first. A nudge or scheduled message to anyone else fails, and
+reaches the agent as "Not delivered" (`outside_window`). Ask people to write first with the line's
+opt-in link. Text takes up to 9999 characters; there are no buttons, lists or templates.
 
 ## Also exported
 
 - `verifySignature(body, header, secrets)`: checks a `Flow-Signature` header yourself.
 - `FlowMessagingError`: the API's typed error (`status`, `type`, `channelCode`, `retryAfter`).
 - `API_VERSION`: the API version every request asks for, `2026-11-01`.
-- `TELEGRAM`: the Telegram channel's limits, as a framework `ChannelInfo`.
+- `TELEGRAM`, `IMESSAGE`: the Telegram and iMessage channels' limits, as framework `ChannelInfo`s.
 
 ## Links
 
@@ -149,4 +188,4 @@ package yet.
 
 ## License
 
-MIT, as the rest of this repository.
+Apache-2.0, as the rest of this repository.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@flow-engineer/flow",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "An open-source runtime for chat agents that feel like a person texting back.",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/flow-engineer/flow.git"
@@ -42,6 +42,7 @@
     "examples/cafe/tests",
     "examples/http-agent",
     "flow-messaging/README.md",
+    "docs/agents.md",
     "coding-agents",
     "spec",
     "README.md",

package/spec/agent-endpoint.openapi.yaml

@@ -3,8 +3,8 @@ info:
   title: Flow Framework agent endpoint
   version: 0.1.0
   license:
-    name: MIT
-    identifier: MIT
+    name: Apache-2.0
+    identifier: Apache-2.0
   description: |
     The HTTP endpoint an agent on any framework, in any language, exposes so Flow Framework's test suite
     can talk to it: `flow test --agent-url <url>`. Implement this one operation and the test

package/spec/nudges.openapi.yaml

@@ -3,8 +3,8 @@ info:
   title: Flow Framework nudges over HTTP
   version: 0.1.0
   license:
-    name: MIT
-    identifier: MIT
+    name: Apache-2.0
+    identifier: Apache-2.0
   description: |
     The endpoint `nudgeHandler(agent, { token, base })` serves in the agent's own server, so a
     backend that is a separate service can send nudges (messages the business starts) without a