@flow-engineer/flow 0.3.3 → 0.4.1

package/docs/agents.md

@@ -173,6 +173,13 @@ preview card's title becomes the phone's notification instead of the message's t
 action use `link` (`agent.nudge({ to, text, link: { label, url } })`, or the agent's send with
 `link`), not a URL in the text.
 
+When the business's backend should tell people what happened (an order shipped, an item is back),
+mount `flowEvents` instead of writing a route: one signed `POST /v1/events`, each event sent by its
+delivery level (critical at once, standard after quiet hours, optional merged or dropped), with the
+agent's own wording checked against the template's values. The envelope, signing, answers and a
+mounting sample are in `docs/events.md` in the package
+(https://github.com/flow-engineer/flow/blob/main/docs/events.md).
+
 ## Shared test numbers and privacy
 
 The free trial runs on Flow's shared Telegram bot, WhatsApp number and iMessage line. Sending an
@@ -190,4 +197,59 @@ version in `package.json` for production.
 
 ## Host it
 
-Coming soon: `npx @flow-engineer/flow deploy`, to keep the agent answering while the laptop sleeps.
+`npx @flow-engineer/flow deploy` puts the agent on Flow's hosting, so it answers while the laptop
+sleeps. It needs `package.json`, `package-lock.json` and `src/agent.ts`, whose `buildAgent` passes
+`options.host` on to `createAgent`, and the agent's CI key in `FLOW_FRAMEWORK_CLOUD_KEY` (the
+environment, else `.env`; `flow setup` writes it).
+
+One command deploys, the first time included:
+
+```sh
+npx @flow-engineer/flow deploy
+```
+
+It sends the `.env`'s values as the agent's secrets, then builds and follows it to live. The rest:
+
+```sh
+npx @flow-engineer/flow deploy [--env staging|production] [--version <v>] [--no-secrets] [--json]
+npx @flow-engineer/flow deploy promote [--no-secrets] [--json]
+npx @flow-engineer/flow deploy status [--env staging|production] [--json]
+npx @flow-engineer/flow logs [--env staging|production] [--since 1h] [--follow] [--json]
+npx @flow-engineer/flow deploy secret NAME [--env staging|production] < value.txt
+npx @flow-engineer/flow deploy secrets --from-env [<file>] [--env staging|production] [--json]
+```
+
+- `deploy` first sends each non-empty value in the agent's `.env` as a secret for that
+  environment, before the service starts, so the first live version has its keys: never the CI
+  key, the cloud's address or a name Flow sets itself (`FLOW_FRAMEWORK_TRACES_*`, `FLOW_STORE_*`,
+  `PORT`, ...). Later deploys send only the new or changed ones (`.flow/secrets.json` keeps a hash
+  per name, never a value). It prints the names it sent, never values; `--no-secrets` sends none.
+  A secret the host refuses stops the deploy before it starts, naming it.
+- `deploy` packs the folder (without `node_modules`, `.git`, `.env*` and `.flow`, at most 50 MB),
+  uploads it, and follows the build until it is live, refused or failed. The default is staging;
+  production refuses an agent that ignores `host` or brings its own database, and the build
+  refuses an agent on a newer framework than Flow hosts yet. `--json` prints
+  `{ ok, deploy: { id, environment, status, version, findings, error }, url, next }` on stdout
+  (`url` is null when the cloud does not say it yet; the human output then says "URL: not available
+  on this Flow yet"); progress goes to stderr. The deploy's id is kept in `.flow/deploys.json`. The
+  version is the folder's git commit, `<sha>+dirty` (with a warning) when the folder has
+  uncommitted changes, since what is packed is the folder as it is; `--version` names it yourself.
+- `promote` moves staging's live version to production, with no new build. Production keeps its
+  own secrets: promote sends the `.env`'s new or changed values there first (`--no-secrets` sends none).
+- `status` shows, per environment (both unless `--env`), the deploy serving it (`status`, `version`,
+  `id`, `updated_at`), its URL and a newer one still building. `--json` prints
+  `{ ok, environments: { staging: { deploy, pending, url, from } | null, production: ... }, next }`;
+  `from` is `list` (the cloud's list) or `this_folder` (the last deploy from `.flow/deploys.json`, on
+  a Flow whose cloud does not list deploys to a CI key yet).
+- `logs` prints the hosted agent's log lines from `--since` (30s, 15m, 1h, 2d; default 1h), and with
+  `--follow` keeps printing new ones; `--json` is one `{ time, severity, text }` per line. On a Flow
+  whose cloud has no logs route yet it says so: `error.code` `not_available`, exit 1.
+- `secret NAME` (one value from stdin) and `secrets --from-env` (every value in a file, now) are for
+  changing a secret by hand; `deploy` already sends the `.env`. `--json` prints
+  `{ ok, environment, saved, skipped, refused, next }`. Before the agent's first deploy the host has
+  no agent to keep them for: they are refused, exit 1, and `next` is `deploy`. A secret takes effect
+  on the next deploy.
+- Exit codes: 0 live or saved, 1 refused, failed or not reachable, 2 a usage problem (no CI key, a
+  missing file, a bad name). On an error, `--json` prints `{ ok: false, error: { code, message }, next }`.
+
+Run each answer's `next`. Promote, or deploy to production, only when the owner says so.

package/docs/events.md

@@ -0,0 +1,243 @@
+# Business events
+
+A business's backend posts what happened (an order shipped, an order is late, an item is back in
+stock) to one signed route on the agent, `POST /v1/events`. The agent turns each event into a
+WhatsApp message for one person, at the event's delivery level: some go at once, some wait for the
+end of quiet hours, some are merged or dropped. Sends go through the agent's `nudge()`, so STOP and
+the no-contact rules apply to every one.
+
+`flowEvents` (from `@flow-engineer/flow`) is the engine. What your events mean (which types exist,
+their templates and wording, your own rules) stays in your app.
+
+## The envelope
+
+```json
+{
+  "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" }
+  }
+}
+```
+
+| Field | |
+|---|---|
+| `id` | Required. Unique per event: the same id twice is processed once. |
+| `type` | Required. One of your catalog's types, or `notification.cancelled`. Any other is a 400. |
+| `occurredAt` | Required. ISO time. |
+| `subject` | Required. What it is about, as you name it (`order:4821`, `user:77`). |
+| `delivery` | `critical`, `standard` or `optional`. The floor: never sent lower. Default: the type's level. |
+| `data` | Required object. Your payload. |
+| `sentBy` | You already sent this message yourself: kept as context, never sent (see Copies). |
+| `expiresAt` | ISO time: not sent after it. Also read from `data.expiresAt`. |
+| `collapseKey` | A newer event with the same key replaces one still held. Also read from `data.collapseKey`. |
+
+By default the person is `data.user.phone` (E.164, required on a notification) and they agreed to
+messages when `data.consent.whatsappUpdates === true`; without consent nothing is sent. Change
+either with `addressOf(event)` and `consented(event)`. `data.wording: "exact"` always sends the
+template, never the agent's words.
+
+To cancel one not yet sent, post `notification.cancelled` with the id in `data.cancels`:
+
+```json
+{ "id": "evt_01J9Z7", "type": "notification.cancelled", "occurredAt": "2026-10-20T14:06:00Z",
+  "subject": "order:4821", "data": { "cancels": "evt_01J9Z6" } }
+```
+
+## Signing
+
+Every POST carries `Flow-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>`, the HMAC of
+`t.{t}.{raw body}` with the secret you gave the agent (`whsec_...`). `t` may be at most 5 minutes
+off. The header may hold several `v1` values, so a secret can be rotated without dropping events.
+`signEvent(secret, body)` makes the header; `verifyEventSignature(secret, header, body)` checks one.
+
+From any Node backend, without the package:
+
+```js
+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,
+});
+```
+
+Sign the exact bytes you send.
+
+## Answers
+
+| Status | Body | When |
+|---|---|---|
+| 202 | `{"status":"accepted"}` or `{"status":"duplicate"}` | Recorded; processed in order in the background. A duplicate id was already taken. |
+| 400 | `{"field","error"}` | Malformed; `field` names what is wrong (`data.user.phone`, `type`, a value your message needs). |
+| 401 | `{"error"}` | Bad or missing `Flow-Signature`. |
+| 405 | `{"error"}` | Not a POST. |
+| 503 | `{"error"}` | The agent has no secret configured. |
+
+On a network error, a 429 or a 5xx, retry with the same `id`: the id dedupes, so a retry never
+sends twice. An `Idempotency-Key` header is honoured too.
+
+## Delivery levels
+
+| Level | In quiet hours | Also |
+|---|---|---|
+| `critical` | Sent at once. | |
+| `standard` | Held, sent when they end (on the agent's tick). | |
+| `optional` | Held too. | One a day per `collapseKey`; dropped when its topic closes. |
+
+- `liveOnly` on a type: its button acts on something live, so it is dropped once its topic closes,
+  whatever the level.
+- `collapseKey`: a newer standard or optional event with the same key replaces the one held.
+- `expiresAt`: a held one past it is dropped.
+- Quiet hours are 22:00 to 08:00 in `timezone` (default UTC); `quietHours: { from, to }` changes
+  them, `null` turns them off.
+
+A topic (`topic(event)` on the type, such as `order:4821`) closes with `events.close(topic)`.
+
+### Watches raise a message
+
+When a person asked to be told about a topic (`events.watch({ address, topic, title })`, from one of
+your tools), a message about it is raised: an optional one is kept as standard, it is never dropped
+when the topic closes and it skips the caps. A watch with `urgent: true` ("tell me as soon as") makes
+it critical. A message is never lowered. Watches last `watchDays` (30) and end a day after
+`close(topic)`.
+
+## Wording
+
+Outside WhatsApp's 24-hour window the template goes. Inside it the agent phrases the message to fit
+the chat; every value and the link are checked by `events.phrasing.check` in the channel's send. A
+message that drops a value or changes the link is refused, and the template goes instead; if the
+template fails, its text goes as a message with a link button (`wording: { linkInText: true }` puts
+the link in the text). `data.wording: "exact"` always uses the template.
+
+## Copies
+
+`sentBy` says the business already sent this message itself (allowed only for the names in the
+`sentBy` option). It is never sent. It is kept as the agent's context, read with
+`events.context(conversationId)`, so the agent can answer when they reply about it. It counts as
+already told: an identical message within a day, and a held one with the same `collapseKey`, are
+not sent. If the agent has `reach()`, the person's conversation is opened, so the copy is there when
+they write.
+
+## Nudges
+
+Messages you start from what people watch (rather than from an event) go through
+`events.schedule({ delivery: "nudge", nudge: "<kind>", eventId, address, topic, message, notBefore: Date.now(), exact: false })`.
+They are held in quiet hours and capped: `caps: { perDay: 2, perKeyPerDay: 1, perWeek: 5 }` by
+default (per person; `perKeyPerDay` per topic). A raised nudge skips the caps.
+`events.notInterested(address)` mutes the topic last nudged and ends its watch;
+`events.mute(address, topic)` mutes one; `events.stopped(address)` ends their watches and held nudges.
+
+## Test list
+
+Off production, a send the business starts goes only to listed numbers, so a staging copy of real
+data never reaches a real customer:
+
+```ts
+testList: eventTestList({ testing: false, madeUp: /^\+1555/ })
+```
+
+- `FLOW_ENVIRONMENT=production`: no list, everyone.
+- Otherwise only `FLOW_TEST_NUMBERS` (comma-separated E.164); none set sends nothing.
+- `testing: true` also allows the numbers `madeUp` matches (a test run's made-up numbers).
+
+A stopped send calls `onUnlisted({ event, type, address })`, else it is logged. A held send is
+checked again when it comes due. Replies to people who wrote first are never checked.
+
+## App event types
+
+A catalog type with `kind: "event"` sends nothing itself: it is handled in your `onEvent(event, events)`,
+in order with the rest. Its `validate(event)` returns `{ field, error }` for a 400, or null.
+
+## What stays in your app
+
+The catalog (each type's level, `message`, `topic`, `liveOnly`), the templates and wording, and your
+rules: `rules.notification` (return `"handled"` when you sent or dropped it yourself),
+`rules.copy`, `onEvent` and `onTick`.
+
+The engine keeps its state in memory (`createEventState()`); pass your own `state` to keep or share it.
+
+## Mount it
+
+```ts
+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() });
+
+// The channel's send checks a phrased notification before it goes; a throw refuses it.
+const wa = whatsapp(provider);
+const checked = {
+  ...wa,
+  send: (to: string, out: Parameters<typeof wa.send>[1]) => {
+    const why = events.phrasing.check(to, out);
+    if (why) throw new Error(why);
+    return wa.send(to, out);
+  },
+};
+
+const agent = createAgent({
+  // ...dir, model, tools, templates
+  channels: [checked],
+  routes: events.routes,
+  onTick: events.onTick,
+  context: (conversationId) => events.context(conversationId),
+});
+events.attach(agent);
+```
+
+The agent then answers `POST /v1/events` through `agent.fetch(request)`, and held sends go out on
+its tick.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-engineer/flow",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "An open-source runtime for chat agents that feel like a person texting back.",
   "license": "Apache-2.0",
   "repository": {
@@ -51,6 +51,7 @@
     "examples/http-agent",
     "flow-messaging/README.md",
     "docs/agents.md",
+    "docs/events.md",
     "coding-agents",
     "spec",
     "README.md",