whisp-js 0.1.0 → 0.3.1

package/README.md

@@ -8,13 +8,34 @@ Send WhatsApp messages from your Whisp numbers, read their chats, and react to w
 - `on('message', ...)` over a live event stream that resumes where it stopped.
 - `verifyWebhook` checks the `X-Whisp-Signature` header of webhook requests.
 
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [The client](#the-client): options, auth, numbers and pools, daily caps
+- [Sending](#sending): text, files, voice notes, replies, mentions, `wait`, idempotency
+- [Message actions](#message-actions): react, edit, delete for everyone
+- [Chats](#chats): mark read, typing
+- [Reading](#reading): numbers, messages, chats, phone checks, downloads
+- [Listening](#listening): `on()`, every event, cursors and reconnects
+- [Webhooks](#webhooks)
+- [Errors](#errors): `WhispError` and every code
+- [Limits and guardrails](#limits-and-guardrails)
+- [Server updates (`WORKER_OUTDATED`)](#server-updates-worker_outdated)
+- [Security](#security)
+- [Everything the package exports](#everything-the-package-exports)
+- [Versions](#versions)
+- [FAQ](#faq)
+
 ## Install
 
 ```sh
-npm install whisp-js
+npm i whisp-js
 # or: bun add whisp-js
 ```
 
+Node 22.12 or later, or Bun 1.2 or later. The package ships ESM (`import { Whisp } from 'whisp-js'`) and CommonJS (`const { Whisp } = require('whisp-js')`) with types for both. Deno and edge runtimes can send and read; `on()` needs a process that stays up.
+
 ## Quick start
 
 Copy the token from your project's **API & SDK** tab and set it on your server as `WHISP_API_TOKEN`. The token can send from every number of the project: keep it on the server, never in a browser bundle or a repository.
@@ -28,25 +49,72 @@ const support = new Whisp({ phone: '972501234567' })
 const message = await support.send('972521112233', 'Your order shipped')
 console.log(message.id, message.status) // msg_..., 'pending'
 
-support.on('message', msg => {
-	console.log(`${msg.from} wrote to ${msg.number}: ${msg.text}`)
+support.on('message', async msg => {
+	await support.startTyping(msg.chatId) // "typing..." until the reply goes out
+	const answer = await askYourModel(msg.text)
+	await support.send(msg.chatId, answer, { replyTo: msg.id }) // the same chat, a group too
 })
 ```
 
-Phones are WhatsApp digits in international form: `972501234567`. The SDK also takes `+972 50-123-4567` and turns it into digits.
+Phones are WhatsApp digits in international form: `972501234567`. The SDK also takes `+972 50-123-4567` and turns it into digits. A recipient (`to`) or a chat (`chat`) is named by the other side's phone, the chat's `cht_` id (`msg.chatId`), a group's JID (`120363025246125486@g.us`) or a LID JID (`123456789012345@lid`, a contact WhatsApp knows without a phone).
+
+## The client
+
+### `new Whisp(options?: WhispOptions)`
+
+Nothing is called when you construct it. The token and the base URL are read when a call needs them, so a value set after import still counts. Bad options throw at once (`OPTIONS_INVALID`, `PHONE_INVALID`, or `TOKEN_IN_BROWSER` in a browser).
+
+| Option | Type | Default | |
+|---|---|---|---|
+| `token` | `string` | `WHISP_API_TOKEN` | The project token (`wsp_live_...`). |
+| `phone` | `string \| readonly string[]` | the whole project | A phone or a `num_` id, or an array of them (a pool, at most 20). |
+| `strategy` | `'healthiest' \| 'random' \| 'round-robin'` | `'healthiest'` | How a pool picks its sender. Only used with several numbers or none. |
+| `sticky` | `boolean` | `true` | Keep a recipient on the number that last talked to them. |
+| `dailyCap` | `number` | none | 1 to 10,000: send from a number only while it sent fewer in the last 24 hours. See [Daily caps](#daily-caps). |
+| `baseUrl` | `string` | `WHISP_API_URL`, else `https://api.whisp.lue.my` | |
+| `timeoutMs` | `number` | `30000` | Per attempt, 1 to 600,000. A send with `wait` gets at least the wait plus 10 s. |
+| `maxRetries` | `number` | `2` | Attempts after the first, 0 to 10. |
+| `cursor` | `string` | none | Resume the event stream after this cursor (a saved `whisp.cursor`). |
+| `fetch` | `typeof fetch` | the global `fetch` | Any WHATWG fetch, looked up on each call. |
+| `dangerouslyAllowBrowser` | `boolean` | `false` | See [Security](#security). |
 
-## Which number sends
+`DEFAULT_TIMEOUT_MS` (30,000) and `DEFAULT_MAX_RETRIES` (2) are exported.
+
+### Auth
+
+One token per project, shown once in the panel and stored hashed. Pass it as `token`, or set `WHISP_API_TOKEN` (`API_TOKEN_ENV`). The SDK sends it as `Authorization: Bearer <token>` to the API's origin and nowhere else. A missing token is `TOKEN_MISSING` on the first call; one that isn't shaped like a project token is `TOKEN_INVALID` before anything is sent. Regenerating the token in the panel revokes the old one at once (`TOKEN_REVOKED`).
+
+### Which number sends
 
 | `phone` | Sends from |
 |---|---|
 | `'972501234567'` or `'num_7Hq2kD3x'` | That number. The identifier is on the number's page. |
-| `['972501234567', '972501234568']` | One of them, picked on the server for every send: `strategy: 'healthiest'` (the default), `'random'` or `'round-robin'`. |
+| `['972501234567', '972501234568']` | One of them, picked on the server for every send by `strategy`. |
 | left out | The project's default number (Settings), else every number of the project as a pool. |
 
 `healthiest` ranks the pool's numbers on every send: healthy before watch, then numbers with a sending record before new or idle ones, then the lower health score (in bands of 10, so numbers of about the same health share the traffic), then the most daily cap left, then the fewest messages sent this hour, then at random. Messages still queued on a number count as sent, so a burst of sends spreads over the pool instead of piling up behind one number. Numbers that are not connected, at risk, paused, at their daily cap (queued messages included) or with a full queue are skipped. Each number's `healthScore` (0 to 100, lower is healthier) is on `whisp.numbers()`. A number that hasn't sent 20 messages in the last 24 hours (just linked, or idle for a day) has no record yet: it scores at least 30 and takes the pool's messages only when no healthy number with a record can, so a new number doesn't get the pool's cold traffic.
 
 Pools are sticky by default: a recipient keeps getting messages from the number that last talked to them, so the conversation stays in one chat. With `healthiest`, only while that number is healthy and within one score band of the best one; otherwise the healthiest number takes the message and the recipient stays with it from then on. `sticky: false` (a good fit for one-time codes) always takes the healthiest. A contact WhatsApp only knows by a LID (no phone) can't be matched by phone, so in a pool it may land on another number.
 
+A send from one number that is reconnecting waits on the server and goes out when it reconnects; a disconnected number answers `NUMBER_NOT_CONNECTED` (in a pool it is skipped instead).
+
+### `whisp.number(phoneOrId: string): Whisp`
+
+A copy with the same options that sends from, reads and listens on that one number. Throws `PHONE_INVALID` for anything that is neither a phone nor a `num_` id. `chats`, `chat`, `chatMessages`, `check`, `markRead`, `startTyping` and `stopTyping` need one number (a `phone` string, or an array of one): on a pool or a whole-project instance they fail with `NUMBER_REQUIRED` before any request. `chats` and `chatMessages` throw it from the call; the others reject.
+
+```ts
+const whisp = new Whisp() // the whole project
+const support = whisp.number('num_7Hq2kD3x')
+```
+
+### `whisp.verify(): Promise<VerifyResult>`
+
+Checks the token (`GET /project`) and that every phone or id you named belongs to the project (`GET /numbers`). Resolves `{ project, token, numbers }`; rejects with `NUMBER_NOT_IN_PROJECT` (`params.number` lists the ones that aren't) or the token's error. Optional: the first send or listen reports the same.
+
+```ts
+const { project, numbers } = await new Whisp({ phone: ['972501234567', '972501234568'] }).verify()
+```
+
 ### Daily caps
 
 Each number has a daily cap in its settings in the panel (600 messages in any 24 hours unless changed). The SDK can set one too:
@@ -59,32 +127,53 @@ await otp.send('972521112233', 'Your code is 115720', { dailyCap: 100 }) // this
 
 `dailyCap` goes with every send; per send it replaces the instance's. A number may send only while it has sent fewer messages than the lower of the two caps in the last 24 hours. A pool skips numbers at their cap; a single number at its cap answers `DAILY_CAP_REACHED` with `params.cap` (the cap that applied), `params.used` and `params.resetAt`. The server counts and enforces it: the SDK never counts by itself, because several instances of your app can share one number. The server checks it when it accepts a send, on counts up to 10 seconds old, so a burst of sends in parallel can pass the cap by a few messages.
 
-`whisp.number(phoneOrId)` returns a copy that sends from, reads and listens on that one number:
+## Sending
+
+Every send resolves the message as the API created it: `pending` until the number sends it, or its status after `wait`. A message that can't go out ends as a `message.status` event with `status: 'failed'` and an `error.code` (see [Why a message failed](#why-a-message-failed)).
+
+### `send(to: string, text: string, options?: SendOptions): Promise<Message>`
 
 ```ts
-const whisp = new Whisp() // the whole project
-const support = whisp.number('num_7Hq2kD3x')
+const message = await whisp.send('972521112233', 'Hello from Whisp', {
+	reference: 'order-1042', // your own id (1-128 characters), echoed on the message and its events
+	replyTo: 'msg_...', // a msg_ id or a WhatsApp id of a message in the same chat
+	wait: true, // wait up to 15 s for the outcome (or a number of ms, 1,000 to 20,000)
+	dailyCap: 300, // this send only (see Daily caps)
+	idempotencyKey: 'order-1042-shipped', // default: a new UUID per call, kept across its retries
+	mentions: ['972521112233'], // groups only (see Mentions)
+})
 ```
 
-A send from one number that is reconnecting waits on the server and goes out when it reconnects; a disconnected number answers `NUMBER_NOT_CONNECTED` (in a pool it is skipped instead). `await whisp.verify()` checks the token and that every phone you named belongs to the project, and throws `NUMBER_NOT_IN_PROJECT` listing the ones that don't.
+`SendOptions`:
 
-## Sending
+| Field | Type | |
+|---|---|---|
+| `replyTo` | `string` | A `msg_` id or a WhatsApp id of a message in the same chat. `REPLY_TARGET_NOT_FOUND` otherwise. |
+| `reference` | `string` | Your own id, 1-128 characters, on the message and its events; find messages by it with `messages()`. |
+| `wait` | `boolean \| number` | Wait for the outcome: `true` is 15 s, or 1,000 to 20,000 ms. The message comes back `sent` or `failed`, or still `pending` when the wait ran out. |
+| `dailyCap` | `number` | This send's cap (1 to 10,000), in place of the instance's. |
+| `idempotencyKey` | `string` | Makes retries safe across your own restarts too: 1 to 255 printable ASCII characters, no spaces. |
+| `mentions` | `string[]` | Phones or `<digits>@lid` JIDs, each written `@<digits>` in the text. Groups only, at most 50. |
+
+Errors: `RECIPIENT_INVALID`, `NUMBER_NOT_IN_PROJECT`, `NUMBER_NOT_CONNECTED`, `NO_NUMBER_AVAILABLE`, `NUMBER_PAUSED`, `DAILY_CAP_REACHED`, `SEND_QUEUE_FULL`, `GROUPS_IGNORED`, `NOT_IN_GROUP`, `REPLY_TARGET_NOT_FOUND`, `IDEMPOTENCY_KEY_INVALID`, `IDEMPOTENCY_KEY_REUSED`, the mention codes, `VALIDATION_FAILED`, `RATE_LIMITED`, `OPTIONS_INVALID` (a bad `dailyCap` or `mentions`, before any request), `WORKER_OUTDATED` (a send with `mentions` during a server update).
+
+### Idempotency
+
+Every send carries an `Idempotency-Key`, the same on each of its retries, so a retry after a timeout never sends twice. Pass your own `idempotencyKey` to stay safe across your own restarts too: the same key and body within 24 hours answer the first message again; the same key with another body is `IDEMPOTENCY_KEY_REUSED`.
 
 ```ts
-await whisp.send('972521112233', 'Hello from Whisp', {
-	reference: 'order-1042', // your own id, echoed on the message and its events
-	replyTo: 'msg_...', // a message in the same chat
-	wait: true, // wait up to 15 s for the outcome (or a number of ms, up to 20,000)
-	dailyCap: 300, // this send only: a number that sent 300 in 24 h is skipped (see Daily caps)
-	idempotencyKey: 'order-1042-shipped', // default: a new UUID per call
-})
+await whisp.send('972521112233', 'Your order shipped', { idempotencyKey: `order-${order.id}-shipped` })
 ```
 
-`send` resolves the message as the API created it: `pending` until the number sends it, or its status after `wait` (`sent`, `failed`). A message that can't go out (the phone isn't on WhatsApp, the number stayed offline) ends as a `message.status` event with `status: 'failed'` and an `error.code`, such as `NOT_ON_WHATSAPP`.
+### Files: `sendImage`, `sendVideo`, `sendDocument`
 
-Every send carries an `Idempotency-Key`, the same on each of its retries, so a retry after a timeout never sends twice. Pass your own key to stay safe across your own restarts too: the same key and body within 24 hours answer the first message again; the same key with another body is `IDEMPOTENCY_KEY_REUSED`.
+```ts
+sendImage(to: string, media: MediaSource, options?: SendFileOptions): Promise<Message>
+sendVideo(to: string, media: MediaSource, options?: SendFileOptions): Promise<Message>
+sendDocument(to: string, media: MediaSource, options?: SendFileOptions): Promise<Message>
+```
 
-### Files
+`SendFileOptions` is `SendOptions` plus `caption?: string` (at most 1,024 characters).
 
 ```ts
 // A public https URL: the server downloads it.
@@ -92,48 +181,236 @@ await whisp.sendImage('972521112233', { url: 'https://example.com/receipt.png' }
 
 // Bytes you hold: the SDK uploads them first.
 await whisp.sendDocument('972521112233', { file: pdfBytes, fileName: 'invoice.pdf' })
-await whisp.sendVoice('972521112233', { file: Bun.file('note.ogg') })
 await whisp.sendVideo('972521112233', { file: await fs.openAsBlob('clip.mp4'), mime: 'video/mp4' })
 ```
 
-`file` is a `Blob` (a `File`, `Bun.file()`, Node's `fs.openAsBlob()`), a `Uint8Array`, an `ArrayBuffer` or a `ReadableStream`. The upload signs the file's exact length, so a stream is read into memory first; pass a `Blob` for big files. The type comes from `mime`, else the Blob's type, else the file name's extension. Limits: images 16 MB (JPEG, PNG, WebP, GIF), videos 64 MB (MP4), voice notes 16 MB (OGG, MP3, M4A, AAC, WAV, WebM), documents 100 MB (any type).
+`MediaSource` is one of:
+
+- `MediaUrl`: `{ url: string; fileName?: string; mime?: string }`. https only; the server fetches it, refusing private addresses and redirects (`MEDIA_URL_NOT_ALLOWED`). A URL that can't be fetched fails the message later with `MEDIA_FETCH_FAILED`, one over its kind's limit with `MEDIA_TOO_LARGE`.
+- `MediaFile`: `{ file: Blob | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>; fileName?: string; mime?: string; size?: number }`. A `Blob` is a `File`, `Bun.file()` or Node's `fs.openAsBlob()`. The upload signs the file's exact length, so a stream is read into memory first; pass a `Blob` for big files. The type comes from `mime`, else the Blob's type, else the file name's extension.
+
+Limits: images 16 MB (JPEG, PNG, WebP, GIF), videos 64 MB (MP4), voice notes 16 MB (OGG, MP3, M4A, AAC, WAV, WebM), documents 100 MB (any type). A file the SDK can't upload as given (no bytes, no type, too big) is `MEDIA_INVALID` before anything is sent; a failed PUT to storage is `UPLOAD_FAILED`. Anything else than `{ url }` or `{ file }` is `MEDIA_INVALID`.
+
+### Voice notes: `sendVoice(to: string, media: MediaSource, options?: SendVoiceOptions): Promise<Message>`
+
+```ts
+await whisp.sendVoice('972521112233', { file: Bun.file('note.ogg') })
+```
+
+`SendVoiceOptions` is `SendOptions` without `mentions` (a voice note has no text to carry them). The server converts it to OGG/Opus, and WhatsApp shows "recording audio..." for its length before it goes out (see [Limits and guardrails](#limits-and-guardrails)).
+
+### Any body: `sendMessage(body: SendMessageBody, options?: Pick<SendOptions, 'idempotencyKey'>): Promise<Message>`
+
+A raw `POST /messages` body for anything the helpers don't cover. The instance's `from`, `strategy`, `sticky` and `dailyCap` fill in what the body leaves out.
+
+```ts
+await whisp.sendMessage({ to: '972521112233', type: 'document', media: { uploadId }, caption: 'Signed' })
+```
+
+### Mentions
+
+In a group, a text or a caption can mention people. Name each one in `mentions`, by phone or by `<digits>@lid` JID, and write `@` and the same digits in the text; WhatsApp shows the person's name there and notifies them:
+
+```ts
+const team = whisp.number('972501234567')
+await team.send('120363025246125486@g.us', 'Thanks @972521112233, and welcome @123456789012345!', {
+	mentions: ['+972 52-111-2233', '123456789012345@lid'],
+})
+await team.sendImage('120363025246125486@g.us', { url: 'https://example.com/plan.png' }, {
+	caption: '@972521112233 the new plan',
+	mentions: ['972521112233'],
+})
+```
+
+- Groups only: a mention in a direct chat is `MENTIONS_NEED_GROUP`. Each mention's `@<digits>` must be in the text (`MENTION_NOT_IN_TEXT`, with `params.mention`). At most 50; one person in two spellings counts once. A ref that is neither a phone nor a LID JID is `VALIDATION_FAILED` with `params.reason: 'mentions'`.
+- Some groups hide their members' phone numbers (LID-addressed groups). There the server sends each phone mention as the person's LID, so the phone is never shown to the group. When nobody can match a phone to its LID (someone who never wrote to the number), the message fails with `MENTION_UNRESOLVED` (a `message.status` event, `status: 'failed'`) and nothing is sent. Mention that person by `<digits>@lid` instead: their LID is on a message they sent (`sender.lid`) and in the `group.participants` event.
+- Received and sent messages carry `mentions`: the people mentioned, each with `phone`, `lid` and the `name` your project knows them by. `@` and their phone or LID digits mark each one in `text`.
+
+### Waiting for the outcome
+
+`wait` holds the request on the server until the message is `sent` or `failed`, up to the wait. Without it, follow the message with events (`message.sent`, `message.status`) or read it again:
+
+```ts
+const sent = await whisp.send('972521112233', 'Your code is 482913', { wait: 10_000 })
+if (sent.status === 'failed') console.log(sent.error?.code)
+else if (sent.status === 'pending') console.log('still queued: follow it with events')
+
+const later = await whisp.message(sent.id)
+```
+
+`wait` doesn't make a send any slower to go out: the guardrails' delay and typing apply either way (see [Limits and guardrails](#limits-and-guardrails)), so with a wait under about 5 s a send that queued behind others can come back `pending`.
 
-`sendMessage(body)` sends a raw `POST /messages` body for anything the helpers don't cover; the instance's `phone`, `strategy`, `sticky` and `dailyCap` fill in what the body leaves out.
+## Message actions
+
+None of these carries an `Idempotency-Key`: each is idempotent by state, so the SDK retries them like reads. None counts toward the daily cap, the guardrails or the number's health.
+
+### `react(message: Message | string, emoji: string): Promise<void>`
+
+Sets this number's reaction to a message (one emoji: a ZWJ sequence, a flag or a skin tone included), replacing its earlier one. Resolves once the server queued it for the number's connection; a `message.reaction` event with `fromMe: true` follows.
+
+### `unreact(message: Message | string): Promise<void>`
+
+Removes this number's reaction.
+
+```ts
+await whisp.react(message, '👍') // a Message or its msg_ id
+await whisp.unreact(message.id)
+```
+
+Errors: `MESSAGE_NOT_FOUND`, `MESSAGE_DELETED`, `MESSAGE_NOT_SENT` (this number's own message that failed, or hasn't gone out yet: held by a pause, the daily cap or the queue), `NOT_IN_GROUP`, `GROUPS_IGNORED`, `NUMBER_NOT_CONNECTED` (neither connected nor reconnecting), `VALIDATION_FAILED` (`params.reason: 'emoji'` for anything but one emoji), `WORKER_OUTDATED`, `RATE_LIMITED`; `OPTIONS_INVALID` locally for an empty emoji (use `unreact`) or a bad message id. A reaction to a number that is reconnecting goes out when it is back, within 10 minutes. A paused number may react.
+
+### `edit(message: Message | string, text: string, options?: EditOptions): Promise<Message>`
+
+Edits the text, or the caption of a picture, video or document, of a message this number sent, within WhatsApp's 15 minutes. Resolves the edited message; the same text without `mentions` resolves it unchanged and sends nothing. A `message.edited` event follows.
+
+`EditOptions`: `{ mentions?: string[] }` replaces the message's mentions; left out, the mentions still named in the new text are kept.
+
+```ts
+const fixed = await whisp.edit(message, 'Your code is 482914')
+```
+
+Errors: `MESSAGE_NOT_OURS`, `MESSAGE_NOT_SENT` (retry a failed message first), `MESSAGE_DELETED`, `MESSAGE_NOT_EDITABLE` (`params.reason`: `type`, `no_caption`, `no_raw`), `EDIT_WINDOW_PASSED` (`params.sentAt`, `params.windowMinutes`), `NUMBER_PAUSED` (an edit puts new text in front of everyone in the chat), `NUMBER_NOT_CONNECTED`, `NOT_IN_GROUP`, `GROUPS_IGNORED`, the mention codes, `WA_REJECTED` (WhatsApp's own text in `params.detail`), `VALIDATION_FAILED` (`params.reason: 'caption'` past 1,024 characters), `WORKER_UNAVAILABLE`, `WORKER_OUTDATED`, `RATE_LIMITED`; `OPTIONS_INVALID` locally (empty text, a bad message id, `mentions` that isn't a non-empty list).
+
+### `revoke(message: Message | string): Promise<Message>`
+
+Deletes a message this number sent for everyone, within 2 days. Resolves the message with `deletedAt` set, also when it was deleted already. A `message.deleted` event follows.
+
+```ts
+const gone = await whisp.revoke(message)
+```
+
+Errors: `MESSAGE_NOT_OURS`, `MESSAGE_NOT_SENT`, `REVOKE_WINDOW_PASSED` (`params.sentAt`, `params.windowHours`), `NUMBER_NOT_CONNECTED`, `NOT_IN_GROUP`, `GROUPS_IGNORED`, `WA_REJECTED`, `WORKER_UNAVAILABLE`, `WORKER_OUTDATED`, `RATE_LIMITED`; `OPTIONS_INVALID` locally (a bad message id). A paused number may delete.
+
+`WORKER_UNAVAILABLE` on an edit or a delete means the server didn't hear back from WhatsApp in time: it may still go through, and if it does the message is updated and the event sent as usual, so check the message (or wait for the event) before you call again. A number takes at most 30 edits and deletes a minute, from the API and the panel together.
+
+## Chats
+
+### `markRead(chat: string): Promise<MarkReadResult>`
+
+Marks a chat of this instance's number read (a phone, a `cht_` id or a group JID): zeroes its unread count and sends read receipts (the sender's blue ticks) when the number's setting sends them, as opening the chat in the panel does. Needs one number.
+
+```ts
+const { chat, readReceipts } = await whisp.number('972501234567').markRead('972521112233')
+```
+
+- `MarkReadResult` is `{ chat: Chat; readReceipts: 'queued' | 'off' | 'none' }`.
+- Unread is one count per chat, shared with the panel: this clears it for your team's members too.
+- `readReceipts` is `'queued'` (handed to the server; not proof WhatsApp got them, since a number that is not connected drops them), `'off'` (the number's or the project's setting) or `'none'` (nothing was unread).
+- Works on a paused number and while it reconnects. Errors: `NUMBER_REQUIRED` (locally), `NUMBER_NOT_IN_PROJECT`, `CHAT_NOT_FOUND`, `RECIPIENT_INVALID`, `RATE_LIMITED`.
+
+### `startTyping(chat: string, options?: TypingOptions): Promise<TypingResult>`
+
+Shows "typing..." (or "recording audio..." with `state: 'recording'`) in a chat of this instance's number while your app works on a reply. The server keeps it up, sending it again every 10 seconds, until the first of:
+
+- a message of this number goes out in that chat, whoever sends it (your send, a teammate in the inbox, Whisp's own reply to a call, or a message typed on the phone). **You don't need to stop before sending.** Nothing more is sent: the message ends the recipient's "typing..." by itself. A phone message from before your start (one WhatsApp delivers late, after a reconnect) doesn't end it.
+- `stopTyping(chat)`, 2 minutes after the latest start (call it again to keep going), the number being paused or starting to ignore groups (in a group chat), a message of this number failing in that chat (the reply won't come), or the number typing in a 26th chat (at most 25 per number are kept; the oldest ends). Each of these sends WhatsApp's "paused" at once.
+- the number's connection closing, or the server restarting. Nothing is sent: the typing fades on the recipient's phone within about 25 seconds.
+
+`TypingOptions`: `{ state?: 'composing' | 'recording' }`, `composing` by default. `TypingResult` is `{ state: 'composing' | 'recording' | 'paused'; keptUntil: string | null }`: `keptUntil` is when it stops at the latest (2 minutes from now), or null while the server's worker is an older build that shows typing once, for about 25 seconds, with no keep-alive.
+
+```ts
+const bot = whisp.number('972501234567')
+bot.on('message', async msg => {
+	await bot.startTyping(msg.chatId)
+	const answer = await askYourModel(msg.text) // takes 20 s: "typing..." stays up
+	await bot.send(msg.chatId, answer) // ends the typing; no stopTyping needed
+})
+```
+
+- Calling it again is cheap: a repeated start within 5 seconds sends nothing to WhatsApp and only moves the 2-minute limit; switching between `composing` and `recording` goes out at once.
+- A number that is reconnecting starts typing once it is back (within the 2 minutes).
+- Typing is not a send: no daily cap, no guardrail delay, no effect on health. Whisp's own typing before an API send (see [Limits and guardrails](#limits-and-guardrails)) is skipped while yours is on, and its wait counts the time yours has already shown, so a bot that typed for 20 seconds isn't held another 4.
+- It shows a chatstate only: the number is not shown online by it.
+- Errors: `NUMBER_REQUIRED` and `OPTIONS_INVALID` (a state other than the two) locally; `NUMBER_PAUSED` (its message would be held, so the recipient would watch "typing..." for nothing), `NOT_IN_GROUP`, `GROUPS_IGNORED`, `NUMBER_NOT_CONNECTED` (neither connected nor reconnecting), `CHAT_NOT_FOUND` (typing needs a chat that exists: send first to a new phone), `NUMBER_NOT_IN_PROJECT`, `RECIPIENT_INVALID`, `RATE_LIMITED`.
+
+### `stopTyping(chat: string): Promise<void>`
+
+Stops this number's typing in the chat at once (WhatsApp's "paused"). Safe to call when nothing is typing, and never refused for the number's state: a paused or disconnected number may always stop. Errors: `NUMBER_REQUIRED` (locally), `NUMBER_NOT_IN_PROJECT`, `CHAT_NOT_FOUND`, `RECIPIENT_INVALID`, `RATE_LIMITED`.
+
+```ts
+await bot.startTyping(chat)
+try {
+	await bot.send(chat, await askYourModel(question))
+} catch (error) {
+	await bot.stopTyping(chat) // the reply won't come: don't leave "typing..." up
+	throw error
+}
+```
+
+`startTyping` and `stopTyping` share their own limit of 240 calls a minute per token.
 
 ## Reading
 
+### `numbers(): Promise<WhatsAppNumber[]>`
+
+Every number of the project, any status, with `status`, `risk`, `healthScore`, `paused`, `capReached` and `last24h`.
+
+### `message(messageId: string): Promise<Message>`
+
+One message of the project's numbers; another project's id is `MESSAGE_NOT_FOUND`, as a missing one is.
+
+### `messages(query: MessagesQuery): Promise<Message[]>`
+
+What earlier sends with this `reference` made, newest first, at most 50. `MessagesQuery` is `{ reference: string }`.
+
 ```ts
-const numbers = await whisp.numbers() // every number of the project, any status
-const message = await whisp.message('msg_...')
-const sent = await whisp.messages({ reference: 'order-1042' }) // newest first, at most 50
+const sent = await whisp.messages({ reference: 'order-1042' })
+```
+
+### `check(phone: string): Promise<PhoneCheck>`
 
+Whether a phone is on WhatsApp, asked through the instance's one number. `PhoneCheck` is `{ phone: string; exists: boolean; jid: string | null }`. Answers are cached for 10 minutes; uncached lookups are limited to 30 a minute per token and 30 a minute per number (`RATE_LIMITED` with `retryAfter`). The number must be connected (`NUMBER_NOT_CONNECTED`). You don't need it before sending: every first send to a phone is checked by the server, and fails with `NOT_ON_WHATSAPP` when it isn't.
+
+### `chats(query?: ChatListQuery): PageResult<Chat>`
+
+The number's chats, newest activity first. `ChatListQuery` is `{ kind?: 'direct' | 'group'; unread?: boolean; done?: boolean; cursor?: string; limit?: number }` (`limit` 1 to 100, 50 by default).
+
+### `chat(chat: string): Promise<Chat>`
+
+One chat: a phone, a `cht_` id or a group JID. A merged-away `cht_` id resolves to the chat it joined. `CHAT_NOT_FOUND` otherwise.
+
+### `chatMessages(chat: string, query?: ChatMessagesQuery): PageResult<Message>`
+
+A chat's messages, newest first, history included. `ChatMessagesQuery` is `{ before?: string; after?: string; limit?: number }`. Each next page is older (its cursor goes in `before`); after an `after` request, each next page is newer.
+
+`PageResult<T>` is `Promise<Page<T>> & AsyncIterable<T>`, with `Page<T>` = `{ items: T[]; nextCursor: string | null }`: await it for one page, or `for await` it for every item across pages.
+
+```ts
 const support = whisp.number('972501234567')
 const { items, nextCursor } = await support.chats({ unread: true, limit: 20 })
 for await (const msg of support.chatMessages('972521112233')) {
 	// newest first, page after page
 }
-const chat = await support.chat('972521112233') // a phone, a cht_ id or a group JID
-const { exists } = await support.check('972521112233') // is this phone on WhatsApp?
 ```
 
-`chats`, `chat`, `chatMessages` and `check` read one number: on a pool or a whole-project instance they throw `NUMBER_REQUIRED`, so call them on `whisp.number(...)`. Awaiting a list gives one page; `for await` walks every page.
+`chats`, `chat`, `chatMessages` and `check` read one number: on a pool or a whole-project instance they throw `NUMBER_REQUIRED`. A cursor that isn't one of ours is `VALIDATION_FAILED` with `params.reason: 'cursor'`.
+
+### `downloadMedia(message: Message | string, options?: DownloadOptions): Promise<Response>`
 
-### Downloading a message's file
+A message's file as a fetch `Response`. `DownloadOptions` is `{ variant?: 'original' | 'thumb' }`.
 
 ```ts
-const response = await whisp.downloadMedia(message) // a fetch Response
+const response = await whisp.downloadMedia(message)
 await Bun.write('photo.jpg', response)
 ```
 
-The SDK asks the API for a 5-minute link with your token, then fetches the link without it. It never follows the API's redirect with the token attached. A file the server is still preparing is waited for, up to 60 s. With cURL, use `-L` without `--location-trusted`, so the `Authorization` header isn't sent on to storage.
+The SDK asks the API for a 5-minute link with your token, then fetches the link without it. It never follows the API's redirect with the token attached. A file the server is still preparing (`MEDIA_NOT_READY`) is waited for, up to 60 s. Errors: `MESSAGE_NOT_FOUND`, `MEDIA_NOT_READY` (after 60 s), `MEDIA_VARIANT_NOT_FOUND` (no thumbnail for this file), `MEDIA_DOWNLOAD_FAILED` (the link answered an error), `OPTIONS_INVALID`. With cURL, use `-L` without `--location-trusted`, so the `Authorization` header isn't sent on to storage.
 
 ## Listening
 
+```ts
+on(event, handler): () => void
+off(event, handler): void
+close(): void
+get cursor(): string | null
+```
+
 ```ts
 const whisp = new Whisp({ phone: '972501234567', cursor: await loadCursor() })
 
 whisp.on('message', async msg => {
-	await handleReply(msg.from, msg.text)
+	// chatId is the reply target, a group too; msg.from is the sender and null for a contact without a phone
+	await handleReply(msg.chatId, msg.text)
 	await saveCursor(whisp.cursor) // resume after this event next time
 })
 whisp.on('message.status', e => console.log(e.messageId, e.previousStatus, '->', e.status))
@@ -142,41 +419,72 @@ whisp.on('gap', gap => reconcile(gap.reason)) // events may have been missed: ca
 whisp.on('error', (error, event) => console.error(error, event?.event.id))
 ```
 
-| Name | When |
-|---|---|
-| `message` | `message.received`: a new inbound message. |
-| `message.received`, `message.sent`, `message.status`, `message.reaction`, `message.deleted` | Messages: in, out (from the API, the inbox or the phone), delivered, read, played or failed, reactions, deletions. |
-| `chat.updated`, `presence.updated` | Unread, done, pinned, assignee, labels, title; typing and online. |
-| `group.updated`, `group.participants` | Group subject, description and settings; members added, removed, promoted, demoted. |
-| `number.status`, `number.risk`, `call.received` | The number connected or disconnected; its health; an incoming call. |
-| `*` | Every event above. |
-| `open`, `close`, `gap`, `error` | The stream itself: connected, disconnected, a resume that couldn't be honoured, a failure. |
+`on` returns a function that removes the handler. `on('x', fn)` with something other than a function throws `OPTIONS_INVALID`.
+
+A handler gets the event's `data` with the envelope folded in (`ListenerEvent<T>`): the data's fields, plus `number` (the Whisp number's phone), `numberId`, and `event` (`EventMeta`: `id`, `type`, `createdAt`, `cursor`).
 
-A handler gets the event's data with the envelope folded in: `msg.from`, `msg.text`, `msg.number` (the Whisp number's phone), `msg.numberId`, and `msg.event` with the event's `id`, `type`, `createdAt` and `cursor`. `on` returns a function that removes the handler.
+### Events
+
+| Name | When | The handler's data (besides `number`, `numberId`, `event`) |
+|---|---|---|
+| `message` | `message.received` | The `Message`. |
+| `message.received` | A new inbound message. | `Message`: `id`, `waId`, `chatId`, `chat`, `fromMe`, `from`, `sender`, `to`, `type`, `text`, `media`, `quoted`, `content`, `status`, `error`, `sentBy`, `reference`, `at`, `editedAt`, `deletedAt`, `mentions`. |
+| `message.sent` | A message of the number went out: from the API, the inbox, Whisp's call reply or the phone (`sentBy`). | `Message`. |
+| `message.status` | Delivered, read, played, or failed. | `messageId`, `waId`, `chatId`, `to`, `status` (`delivered`, `read`, `played`, `failed`), `previousStatus`, `error` (`{ code, message }` or null), `reference`, `at`. |
+| `message.reaction` | A reaction set or removed, theirs or ours. | `messageId`, `waId`, `chatId`, `emoji`, `removed`, `fromMe`, `actor` (`Actor` or null), `reference`, `at`. |
+| `message.deleted` | Deleted for everyone, by them or by us. | `messageId`, `waId`, `chatId`, `fromMe`, `deletedBy`, `reference`, `at`. |
+| `message.edited` | A text or caption edited, theirs or ours. | `messageId`, `waId`, `chatId`, `fromMe`, `text` (the new one), `mentions`, `reference`, `at`. |
+| `chat.updated` | Unread, done, pinned, assignee, labels, title or disappearing messages changed. | `chat` (`Chat`), `changes` (which of `unread`, `done`, `pinned`, `assignee`, `labels`, `title`, `ephemeral`). |
+| `presence.updated` | Someone is typing, recording, paused, online or offline (WhatsApp sends these for chats the number watches: one a member has open in the panel). | `chatId`, `chat` (`{ kind, jid, phone }`), `state` (`available`, `unavailable`, `composing`, `recording`, `paused`), `participant` (in groups), `at`. |
+| `group.updated` | A group's subject, description or settings changed. | `chatId`, `jid`, `changes` (`subject`, `description`, `announce`, `restrict`, `joinApprovalMode`, `memberAddMode`, `ephemeralDuration`, each only when it changed), `by`, `at`. |
+| `group.participants` | Members added, removed, promoted, demoted or changed. | `chatId`, `jid`, `action` (`add`, `remove`, `promote`, `demote`, `modify`), `participants` (`Actor[]`), `by`, `at`. |
+| `number.status` | The number connected, disconnected, or started reconnecting. | `status`, `previousStatus`, `reason` (a `DisconnectReason` or null), `detail` (`{ code, until }` or null), `at`. |
+| `number.risk` | The number's health level changed. | `risk`, `previousRisk`, `reason` (the first reason's sentence), `reasons` (at most two `{ signal, level, value, text }`), `paused` (sending is paused after this change: route sends elsewhere), `at`. |
+| `call.received` | An incoming call. | `callId`, `from` (`Actor`), `chatId`, `video`, `group`, `offline` (delivered after a reconnect, already over), `rejected` (the number's "Reject calls" setting), `at`. |
+| `*` | Every event above. | `AnyListenerEvent`: check `e.event.type`. |
+| `open` | A connection reached `ready`. | `StreamReady`: `{ resumed: boolean; reason?: 'cursor_unknown' \| 'cursor_expired' }`. |
+| `close` | A connection ended. | `StreamClose`: `{ reconnect: boolean; error?: Error }`. `reconnect` is false once the listener stopped. |
+| `gap` | A resume was asked and couldn't be honoured. | `StreamGap`: `{ reason: 'cursor_unknown' \| 'cursor_expired'; cursor: string }`. |
+| `error` | A handler threw, the server sent `error`, or the listener stopped for good. | `(error: Error, event?: AnyListenerEvent)`. |
+
+An `Actor` is `{ phone: string | null; lid: string | null; name: string | null }` (`phone` is null for someone WhatsApp only knows by a LID). Every type is exported (`Message`, `Chat`, `MessageStatusData`, `NumberRiskData`, ...); `EventData[T]` is the data of type `T`.
+
+### How the stream behaves
 
 - **One stream per instance.** The first event handler opens it; removing the last one, or `close()`, ends it. It covers the instance's numbers (all of the project's for a whole-project instance, numbers linked later included) and every type: adding a handler never reconnects.
-- **Order.** Handlers run one at a time, in the order events happened. A handler that throws emits `error` with the event, and the stream goes on. While a handler runs, the stream waits; a listener that falls far behind is caught up from storage on its next connection, so nothing is dropped.
-- **Resuming.** `whisp.cursor` is the position after the last event whose handlers finished (before the first event, where the stream started, as soon as it opens). The server's pings move it on while your numbers are quiet, so a saved cursor stays fresh even when nothing happens for days. Save it, and pass it as `cursor` after a restart: you get every event after it, in order, for up to 7 days. Older than that (or a cursor from another server), `gap` fires once and the stream continues from now. The cursor is not the event id: use `event.id` to drop an event you already handled, since one handled right before a crash, before its cursor was saved, comes again.
-- **Reconnects.** After a dropped connection the SDK reconnects after 1, 2, 4, 8 and 15 seconds, then every 15 seconds, always resuming from the cursor, also before the first event: nothing that happens while it reconnects is lost. A connection silent for 45 seconds is replaced (the server pings every 20). It stops for good, with `error`, when the token is invalid or regenerated (`TOKEN_INVALID`, `TOKEN_REVOKED`) or a number isn't the project's (`NUMBER_NOT_IN_PROJECT`).
+- **Order.** Handlers run one at a time, in the order events happened. A handler that throws emits `error` with the event, and the stream goes on. While a handler runs, the stream waits; a listener that falls far behind (1,000 events) is caught up from storage on its next connection, so nothing is dropped. With no `error` handler, errors go to `console.error`.
+- **Resuming.** `whisp.cursor` is the position after the last event whose handlers finished (before the first event, where the stream started, as soon as it opens; null until then unless you passed `cursor`). The server's pings move it on while your numbers are quiet, so a saved cursor stays fresh even when nothing happens for days. Save it, and pass it as `cursor` after a restart: you get every event after it, in order, for up to 7 days (typing and online for an hour). Older than that (or a cursor from another server), `gap` fires once and the stream continues from now. The cursor is not the event id: use `event.id` to drop an event you already handled, since one handled right before a crash, before its cursor was saved, comes again.
+- **Reconnects.** After a dropped connection the SDK reconnects after 1, 2, 4, 8 and 15 seconds, then every 15 seconds, always resuming from the cursor, also before the first event: nothing that happens while it reconnects is lost. A connection silent for 45 seconds is replaced (the server pings every 20). A 429 (`TOO_MANY_STREAMS`: at most 10 open streams per token) waits 30 seconds. It stops for good, with `error` and then `close` with `reconnect: false`, when the token is invalid or regenerated (`TOKEN_INVALID`, `TOKEN_REVOKED`), a number isn't the project's (`NUMBER_NOT_IN_PROJECT`), or the server answers another 4xx a retry can't change (403, 400), and when `token` and `WHISP_API_TOKEN` are both missing (`TOKEN_MISSING`). A server restart ends the stream with a `SHUTDOWN` frame: the SDK reconnects and resumes without emitting `error`. Any other `error` frame is emitted (its `code`, or `STREAM_ERROR`) and the stream reconnects.
 - **Long-lived processes.** The stream suits a server or a worker that stays up. In serverless functions, use webhooks instead.
 
 ## Webhooks
 
-Each request to your endpoint carries the event as JSON and an `x-whisp-signature` header: `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`, keyed with the endpoint's signing secret (`wsp_whs_...`, shown once when you create or rotate it). `verifyWebhook` checks it against the **raw** body, before any JSON parsing, and returns the event:
+### `verifyWebhook(input: VerifyWebhookInput): Promise<WebhookEvent>`
+
+Also `whisp.verifyWebhook(input)`, the same function. Each request to your endpoint carries the event as JSON and an `x-whisp-signature` header: `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`, keyed with the endpoint's signing secret (`wsp_whs_...`, shown once when you create or rotate it). `verifyWebhook` checks it against the **raw** body, before any JSON parsing, and returns the event typed by `type`.
+
+| `VerifyWebhookInput` | Type | |
+|---|---|---|
+| `body` | `string \| Uint8Array \| ArrayBuffer` | The raw body: `await request.text()`, or the Buffer of `express.raw()`. |
+| `signature` | `string \| null \| undefined` | The `x-whisp-signature` header. |
+| `secret` | `string \| readonly string[] \| null \| undefined` | The signing secret; several are tried in turn. |
+| `toleranceSeconds` | `number` | How far the signature's time may be from now. Default 300. |
+| `now` | `number` | "Now" in Unix ms, for tests. |
 
 ```ts
 import { verifyWebhook, WhispSignatureError } from 'whisp-js'
 
 const event = await verifyWebhook({
-	body: rawBody, // string, Uint8Array or ArrayBuffer
+	body: rawBody,
 	signature: request.headers.get('x-whisp-signature'),
 	secret: process.env.WHISP_WEBHOOK_SECRET,
-	toleranceSeconds: 300, // the default
 })
 if (event.type === 'message.received') console.log(event.data.from, event.data.text)
 ```
 
-It throws `WhispSignatureError` with `reason` `'missing'`, `'malformed'`, `'timestamp'` (older than the tolerance) or `'mismatch'`: answer 400 and do nothing. A missing or mistyped secret throws `WhispError` (`SECRET_MISSING`, `SECRET_INVALID`) instead, since that is your setup, not the request.
+It throws `WhispSignatureError` (code `SIGNATURE_INVALID`) with `reason` `'missing'`, `'malformed'`, `'timestamp'` (outside the tolerance: an old or replayed request, or a wrong clock) or `'mismatch'`: answer 400 and do nothing. A missing or mistyped secret throws `WhispError` (`SECRET_MISSING`, `SECRET_INVALID`) instead, since that is your setup, not the request; a runtime without Web Crypto throws `CRYPTO_UNAVAILABLE`.
+
+A webhook body is the event envelope: `{ id, type, createdAt, projectId, number: { id, phone }, data }`, with `data` as in the [events table](#events) (not folded: `event.data.text`, `event.number.phone`).
 
 **Express**: the raw body, not `express.json()`:
 
@@ -224,10 +532,10 @@ Bun.serve({
 })
 ```
 
-- Answer 2xx quickly. No answer within 10 seconds, a network error, 408, 429 or 5xx is retried up to 8 times over about a day; a redirect or another 4xx is not (the endpoint said no).
-- The same event can arrive twice (a retry after a timeout you actually handled): dedupe on `event.id`. Order is not guaranteed: order by `createdAt` and the event's `at`.
-- During a secret rotation the header carries one `v1` per valid secret for 24 hours, so either secret verifies. `secret` also takes an array.
-- "Send test event" in the panel delivers `type: 'webhook.test'` with `number: null`.
+- **Retries.** Answer 2xx quickly. No answer within 10 seconds, a network error, 408, 429 or 5xx is retried up to 8 times over about a day (after 10 s, 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 10 h, with some jitter; a `Retry-After` up to an hour is honoured). A redirect or another 4xx is not retried (the endpoint said no). After 3 failures in a row the endpoint is Failing and gets one probe at a time; failing for a day pauses it (resume it in the panel).
+- **Duplicates and order.** The same event can arrive twice (a retry after a timeout you actually handled): dedupe on `event.id`. Order is not guaranteed: order by `createdAt` and the event's `at`. A `presence.updated` older than a minute is not delivered.
+- **Signing.** During a secret rotation the header carries one `v1` per valid secret for 24 hours, so either secret verifies; `secret` also takes an array.
+- "Send test event" in the panel delivers `type: 'webhook.test'` with `number: null` (`WebhookTestEvent`).
 - Message text comes from strangers: treat it as untrusted input.
 
 ## Errors
@@ -237,60 +545,196 @@ Every error is a `WhispError`:
 | Field | |
 |---|---|
 | `code` | Stable: `NUMBER_NOT_IN_PROJECT`, `RATE_LIMITED`, `TOKEN_MISSING`, ... |
-| `status` | The HTTP status when the API answered; `null` when nothing was sent. |
-| `message` | English, safe to log; never contains your token. |
-| `params` | The values the code names (`number`, `total`, `reason`, ...), or `null`. |
+| `status` | The HTTP status when the API answered; `null` when nothing was sent (a local check) or no answer came. |
+| `message` | English, safe to log; never contains your token or a webhook secret. |
+| `params` | The values the code names (`number`, `cap`, `reason`, ...), or `null`. |
 | `requestId` | The API's `X-Request-Id`, for support. |
-| `retryAfter` | Seconds the API asked to wait, or `null`. |
+| `retryAfter` | Seconds the API asked to wait (`Retry-After`), or `null`. |
 
-`WhispConnectionError` (`NETWORK_ERROR`, `TIMEOUT`) means no answer after every retry. `WhispSignatureError` comes from `verifyWebhook`.
+Subclasses: `WhispConnectionError` (`NETWORK_ERROR`, `TIMEOUT`: no answer after every retry; `cause` is the runtime's error) and `WhispSignatureError` (`SIGNATURE_INVALID`, with `reason`). One `instanceof WhispError` catches them all. `SDK_ERROR_CODES` lists the codes the SDK makes itself.
 
-| Code | Means |
+```ts
+import { WhispError } from 'whisp-js'
+
+try {
+	await support.send(to, text)
+} catch (error) {
+	if (error instanceof WhispError && error.code === 'DAILY_CAP_REACHED') {
+		await queueForLater(to, text, error.params?.resetAt)
+	} else throw error
+}
+```
+
+### Codes the SDK makes (nothing was sent, or no answer came)
+
+| Code | Means | What to do |
+|---|---|---|
+| `TOKEN_MISSING` | No `token` and no `WHISP_API_TOKEN`. | Set it. |
+| `TOKEN_INVALID` | Not shaped like a project token (`wsp_live_...`). The API uses the same code. | Copy it again from the API & SDK tab. |
+| `TOKEN_IN_BROWSER` | The SDK was created in a browser. | Run it on your server. |
+| `PHONE_INVALID` | A `phone` or `number(...)` that is neither international digits nor a `num_` id. | Fix the value. |
+| `NUMBER_REQUIRED` | A one-number method on a pool or the whole project. | Call it on `whisp.number(...)`. |
+| `OPTIONS_INVALID` | An option or argument the SDK can tell is wrong (`baseUrl`, `timeoutMs`, `dailyCap`, an empty emoji, a typing state, ...). | Fix the call. |
+| `MEDIA_INVALID` | A file that can't be uploaded as given (no bytes, no type, too big). | Fix the file or pass `mime`. |
+| `UPLOAD_FAILED` | The upload to storage failed after its retries. | Try again. |
+| `MEDIA_DOWNLOAD_FAILED` | The signed file link answered an error. | Call `downloadMedia` again. |
+| `INVALID_RESPONSE` | A 2xx in an undocumented shape, or a redirect the SDK refused to follow. | Check `baseUrl`. |
+| `NETWORK_ERROR`, `TIMEOUT` | No HTTP answer after every retry; or the event stream was silent for 45 s (it reconnects). | Retry later; a send kept its `Idempotency-Key`, so pass your own key to retry it safely. |
+| `SECRET_MISSING`, `SECRET_INVALID`, `SIGNATURE_INVALID`, `CRYPTO_UNAVAILABLE` | `verifyWebhook` (see [Webhooks](#webhooks)). | |
+
+### Codes the API answers
+
+| Code | Status | Means | What to do |
+|---|---|---|---|
+| `TOKEN_INVALID` | 401 | Missing, malformed or unknown token. | Copy it again. |
+| `TOKEN_REVOKED` | 401 | Regenerated, or its project deleted. | Use the new token. |
+| `TOKEN_IN_BROWSER` | 403 | The token was used from a browser page; the panel flags it. | Regenerate it and keep it on the server. |
+| `NOT_FOUND` | 404 | No such route: usually an API older than this SDK, answering a 0.3.0 method. | Update the server, or don't call the method yet. |
+| `PAYLOAD_TOO_LARGE` | 413 | A JSON body over 64 KB, or one without a `Content-Length` (the SDK always sends it). | Send files by upload or URL, not inline. |
+| `VALIDATION_FAILED` | 400, 422 | A field the route doesn't take, a bad value, or a body that isn't JSON; `params.reason` names some (`number`, `cursor`, `emoji`, `caption`, `mentions`, `unreadable_body`). | Fix the request. |
+| `RATE_LIMITED` | 429 | Over a limit (see [Limits](#limits-and-guardrails)); `retryAfter` says when. | The SDK waits and retries up to a minute; slow down. |
+| `NUMBER_NOT_IN_PROJECT` | 404 | That phone or id isn't a number of the token's project (`params.number`). | Check `phone`. |
+| `NUMBER_NOT_CONNECTED` | 409 | The number is disconnected (or, for edits, deletes and phone checks, not connected right now). | Wait for `number.status`, or use another number. |
+| `NO_NUMBER_AVAILABLE` | 409 | No number of the pool can send (`params` counts each reason: disconnected, paused, at risk, at its cap). | Add numbers or wait. |
+| `NUMBER_PAUSED` | 409 | Sending from the API is paused on that number (by a member, or automatically when it was at risk). Also an edit or a typing start there. | Send from another number; a member resumes it in the panel. |
+| `DAILY_CAP_REACHED` | 429 | The number sent its daily cap in 24 hours. `params`: `cap`, `used`, `resetAt`. | Wait until `resetAt`, or use a pool. |
+| `SEND_QUEUE_FULL` | 429 | 1,000 messages already wait on that number (for a pool: on every number that could send). | Slow down. |
+| `RECIPIENT_INVALID` | 400 | `to` or `:chat` isn't a phone in international form, a chat id or a group JID. | Fix it. |
+| `CHAT_NOT_FOUND` | 404 | No such chat on that number (reads, `markRead`, typing). | Send first to open it. |
+| `MESSAGE_NOT_FOUND` | 404 | No such message in the project. | |
+| `REPLY_TARGET_NOT_FOUND` | 404 | `replyTo` isn't a message of that chat. | |
+| `GROUPS_IGNORED` | 409 | The number ignores groups (its setting). | |
+| `NOT_IN_GROUP` | 409 | The number left the group or was removed. | |
+| `MESSAGE_NOT_OURS` | 409 | An edit or a delete of someone else's message. | |
+| `MESSAGE_NOT_SENT` | 409 | It never reached WhatsApp (failed, or still waiting its turn): edit, delete or react once it is out. `params.status`. | Retry a failed message in the panel first. |
+| `MESSAGE_NOT_EDITABLE` | 409 | A type WhatsApp can't edit. `params.reason`. | |
+| `MESSAGE_DELETED` | 409 | It was deleted for everyone. | |
+| `EDIT_WINDOW_PASSED`, `REVOKE_WINDOW_PASSED` | 409 | WhatsApp's 15 minutes for an edit, or 2 days for a delete, have passed. `params.sentAt`. | Send a correction instead. |
+| `MENTIONS_NEED_GROUP` | 400 | Mentions in a direct chat. | |
+| `MENTION_NOT_IN_TEXT` | 400 | A mention's `@<digits>` isn't in the text. `params.mention`. | |
+| `MENTION_UNRESOLVED` | 409 | An edit's phone mention a LID-addressed group can't place (a send fails with it as a `message.status` instead). | Mention them by `<digits>@lid`. |
+| `WA_REJECTED` | 400 | WhatsApp refused an edit or a delete; `params.detail` is its text. | |
+| `IDEMPOTENCY_KEY_INVALID` | 400 | An `idempotencyKey` that isn't 1 to 255 printable ASCII characters (no spaces). | |
+| `IDEMPOTENCY_KEY_REUSED` | 409 | The key was used for another body within 24 hours. | Use a new key for a new message. |
+| `MEDIA_URL_NOT_ALLOWED` | 400 | A file URL the server won't fetch (not https, a private address). `params.reason`. | |
+| `UPLOAD_NOT_FOUND`, `UPLOAD_TOO_LARGE`, `UPLOAD_MISMATCH`, `MEDIA_TYPE_NOT_ALLOWED` | 404, 413, 409, 415 | An upload that expired (an hour), is over its kind's limit, changed after it was signed, or a type that kind doesn't take. | Upload again. |
+| `MEDIA_NOT_READY` | 409 | The file is still being prepared (`downloadMedia` waits up to 60 s). | |
+| `MEDIA_VARIANT_NOT_FOUND` | 404 | No thumbnail for this file. `params.variant`. | Ask for `original`. |
+| `TOO_MANY_STREAMS` | 429 | More than 10 open event streams for the token. | Share one `Whisp` instance per process. |
+| `WORKER_UNAVAILABLE` | 503 | An edit, a delete or a phone check got no answer from WhatsApp in time; an edit or a delete may still go through. | Check the message before calling again. |
+| `WORKER_OUTDATED` | 503 | The server is being updated (see below). | Retry in a few minutes. |
+| `NOT_CONFIGURED` | 503 | File storage isn't set up on this server: uploads and downloads can't work. | Tell the server's owner; text sends still work. |
+| `INTERNAL` | 500 | A server error. `requestId` for support. | The SDK retries it. |
+| `HTTP_<status>` | any | An error answer without the API's JSON body (a proxy in front of it, usually). | Check `baseUrl`; 5xx are retried. |
+
+### Why a message failed
+
+A send the API accepted can still fail later: the message's `status` becomes `failed`, with `error.code` on it and on its `message.status` event.
+
+| `error.code` | Means |
 |---|---|
-| `TOKEN_MISSING` | No `token` and no `WHISP_API_TOKEN`. |
-| `TOKEN_INVALID`, `TOKEN_REVOKED` | Not a token of ours, or regenerated (or its project deleted). |
-| `TOKEN_IN_BROWSER` | The token was used from a browser. Regenerate it. |
-| `PHONE_INVALID` | A `phone` that is neither international digits nor a `num_` id. |
-| `NUMBER_REQUIRED` | A read of one number on a pool or the whole project. |
-| `NUMBER_NOT_IN_PROJECT` | That phone or id isn't a number of the token's project. |
-| `NUMBER_NOT_CONNECTED`, `NO_NUMBER_AVAILABLE` | The number is disconnected, or no number of the pool can send (disconnected, paused, at risk or at its daily cap; `params` counts each). |
-| `NUMBER_PAUSED` | Sending from the API is paused on that number (by a member, or automatically when it was at risk). Send from another number. |
-| `DAILY_CAP_REACHED` | The number sent its daily cap in the last 24 hours (its own, or your `dailyCap` when that is lower). `params`: `cap`, `used`, `resetAt`; `retryAfter` says when it can send again. |
-| `GROUPS_IGNORED`, `NOT_IN_GROUP` | A send to a group of a number that ignores groups, or that is no longer in the group. |
-| `RECIPIENT_INVALID` | `to` isn't a phone in international form, a chat id or a group JID. |
-| `RATE_LIMITED`, `SEND_QUEUE_FULL` | Too many requests or sends (for a pool, every number that could send has a full queue); see `retryAfter`. |
-| `IDEMPOTENCY_KEY_REUSED` | The key was used for another body. |
-| `MEDIA_INVALID`, `UPLOAD_FAILED`, `MEDIA_URL_NOT_ALLOWED` | A file the SDK couldn't upload, or a URL the server won't fetch. |
-
-## Retries and timeouts
-
-Network errors, timeouts, 408, 429 and 5xx are retried with full-jitter backoff (0.5 s, doubling, at most 8 s), or exactly as long as `Retry-After` asks, up to a minute; longer than that, the call fails at once with `retryAfter` set. Other 4xx are never retried.
-
-| Option | Default | |
+| `NOT_ON_WHATSAPP` | The phone isn't on WhatsApp. |
+| `NUMBER_OFFLINE` | The number stayed offline 6 hours, so the message wasn't sent late. |
+| `NUMBER_PAUSED` | It waited 6 hours on a paused number. |
+| `NUMBER_NOT_CONNECTED` | The number was stopped (logged out, banned, unlinked) with the message queued. |
+| `DAILY_CAP_REACHED` | The number reached its cap while the message was queued. |
+| `GROUPS_IGNORED`, `NOT_IN_GROUP` | The number started ignoring groups, or left the group, while it was queued. |
+| `MENTION_UNRESOLVED` | A phone mention a LID-addressed group can't place. Nothing was sent. |
+| `RECIPIENT_CHECK_FAILED` | The server couldn't check the recipient on WhatsApp (3 tries). |
+| `MEDIA_FETCH_FAILED`, `MEDIA_TOO_LARGE` | The file URL couldn't be fetched (`params.reason`), or the file is over its kind's limit. |
+| `WA_REJECTED`, `MEDIA_REJECTED` | WhatsApp refused the message, or its file. |
+| `ACCOUNT_RESTRICTED` | WhatsApp restricted messages from this number for now. Not retried automatically. |
+| `WA_<code>` | Another error from WhatsApp (`WA_479`). |
+| `SEND_FAILED` | Anything else that ended the send after its retries. |
+
+A member can retry a failed message from the panel.
+
+### Retries and timeouts
+
+Network errors, timeouts, 408, 429 and 5xx (but 501) are retried `maxRetries` times with full-jitter backoff (0.5 s, doubling, at most 8 s), or exactly as long as `Retry-After` asks, up to a minute; longer than that, the call fails at once with `retryAfter` set. Other 4xx are never retried. Every attempt of a send carries the same `Idempotency-Key`. `close()` stops retries that are waiting for their turn.
+
+## Limits and guardrails
+
+What your app sees of the server's limits:
+
+| Limit | Value | Over it |
 |---|---|---|
-| `token` | `WHISP_API_TOKEN` | The project token (`wsp_live_...`), read when a call needs it. |
-| `phone` | the whole project | A phone, a `num_` id, or an array of them (a pool, at most 20). |
-| `strategy` | `'healthiest'` | `'healthiest'`, `'random'` or `'round-robin'`, for pools. |
-| `sticky` | `true` | Keep a recipient on one number. |
-| `dailyCap` | none | 1 to 10,000: send from a number only while it sent fewer in 24 hours. See Daily caps. |
-| `baseUrl` | `WHISP_API_URL`, else `https://api.whisp.lue.my` | |
-| `timeoutMs` | `30000` | Per attempt. A send with `wait` gets the wait on top. |
-| `maxRetries` | `2` | Attempts after the first. |
-| `cursor` | none | Resume the event stream after this cursor. |
-| `fetch` | the global `fetch` | Any WHATWG fetch. |
-| `dangerouslyAllowBrowser` | `false` | See below. |
-
-`close()` ends the stream and stops retries that are waiting for their turn.
+| Requests, every route | 600 a minute per token | `RATE_LIMITED` (429) |
+| Sends | 120 a minute per token | `RATE_LIMITED` |
+| Phone checks | 30 a minute per token, and 30 uncached lookups a minute per number | `RATE_LIMITED` |
+| Uploads | 60 a minute per token | `RATE_LIMITED` |
+| Reactions, edits, deletes, read marks | 120 a minute per token; edits and deletes 30 a minute per number | `RATE_LIMITED` |
+| Typing (start and stop) | 240 a minute per token | `RATE_LIMITED` |
+| Queued messages | 1,000 per number | `SEND_QUEUE_FULL` (429) |
+| Event streams | 10 open per token | `TOO_MANY_STREAMS` (429) |
+| JSON body | 64 KB | `PAYLOAD_TOO_LARGE` (413) |
+
+Answers on a limited bucket carry `RateLimit-Policy` and `RateLimit` headers.
+
+**Guardrails** protect each number from looking like spam. A member sets them per number in the panel; they apply to sends from the API and Whisp's own call replies, not to replies typed in the inbox (those get the delay only):
+
+- **A random gap** of 1 to 4 seconds between two sends of a number, and at most 18 sends in any minute. A burst of 100 sends to one number goes out over about 5 minutes, in order. Use a pool to go faster.
+- **Typing before the send**: a text of 40 characters or more shows "typing..." for 30 ms a character (1 to 4 seconds) before it goes out; a voice note shows "recording audio..." for its length (1 to 4 seconds). When your app already called `startTyping` in that chat, Whisp sends no typing of its own and waits only what is left of that time.
+- **The daily cap** (600 by default): see [Daily caps](#daily-caps).
+- **The pause**: a member can pause a number, and it pauses itself when its health reaches At risk (`number.risk` with `paused: true`). A paused number refuses new API sends (`NUMBER_PAUSED`) and holds the ones already queued until it is resumed (6 hours at most, then they fail with `NUMBER_PAUSED`).
+- **Health**: `number.risk` and `numbers()` (`risk`, `healthScore`) tell you how WhatsApp is likely to see the number: volume against its usual, messages to people who never wrote, the reply rate, failures, fresh links, disconnects and bursts. Pools route around numbers at risk.
+
+Reactions, edits, deletes, read marks and typing never count toward the cap, the gap or health.
+
+## Server updates (`WORKER_OUTDATED`)
+
+Whisp's server has an API and a worker that talks to WhatsApp, deployed one after the other. For a few minutes during an update, a feature the new API knows may be newer than the running worker. Then the call answers 503 `WORKER_OUTDATED` instead of failing later inside WhatsApp:
+
+- In 0.3.0: `react` and `unreact`, `edit`, `revoke`, and sends with `mentions`.
+- The SDK retries it as a server error (twice by default); if it still fails, try again once the update is done.
+- `startTyping` and `stopTyping` never answer it: during the window they show typing once (about 25 seconds, `keptUntil: null`) without the keep-alive.
+- Everything else (plain sends, reads, `markRead`, events) is unaffected.
 
 ## Security
 
 - The SDK refuses to run in a browser: there, every visitor could copy the token and send from your numbers. `dangerouslyAllowBrowser: true` lets it construct, but the API still answers `403 TOKEN_IN_BROWSER` and flags the token in the panel.
 - The token only ever travels in the `Authorization` header to the API's origin. Redirects are never followed with it, and the SDK sends no other identifying header than its `User-Agent` (`whisp-sdk/<version> (<runtime>/<version>)`).
+- File uploads go straight to storage with a signed URL and no token; downloads fetch the signed link without it.
 - Webhook secrets never travel at all: they only sign.
 
-## Runtimes
+## Everything the package exports
+
+- `Whisp`, `DEFAULT_TIMEOUT_MS`, `DEFAULT_MAX_RETRIES`, and the option types `WhispOptions`, `SendOptions`, `SendFileOptions`, `SendVoiceOptions`, `EditOptions`, `DownloadOptions`, `MessagesQuery`, `Page`, `PageResult`, `VerifyResult`.
+- `verifyWebhook` and `VerifyWebhookInput`.
+- `WhispError`, `WhispConnectionError`, `WhispSignatureError`, `SDK_ERROR_CODES`, `SdkErrorCode`, `SignatureFailureReason`, `ErrorParams`.
+- The listener's types: `EventHandlers`, `ListenerEvent`, `AnyListenerEvent`, `ListenerName`, `EventMeta`, `StreamClose`, `StreamGap`.
+- `MediaSource`, `MediaUrl`, `MediaFile`.
+- Every API shape: `Message`, `Chat`, `WhatsAppNumber`, `Actor`, `PublicEvent`, `EventData`, `WebhookEvent`, `MarkReadResult`, `TypingOptions`, `TypingResult`, `TypingStartState`, `SendMessageBody`, `PhoneCheck`, and the rest.
+- Constants: `SDK_VERSION`, `SDK_PACKAGE_NAME`, `API_TOKEN_ENV`, `API_URL_ENV`, `DEFAULT_BASE_URL`, `PUBLIC_EVENT_TYPES`, `SIGNATURE_HEADER`, `SIGNATURE_TOLERANCE_SECONDS`, `TOKEN_PREFIX`, `WEBHOOK_SECRET_PREFIX`, `EVENT_CURSOR_PREFIX`, `USER_AGENT_PREFIX`.
+
+## Versions
+
+The API only grows: a field can be added, never renamed, removed or retyped, and a new value of a union is announced here first.
+
+- **0.3.1**: no change to the API or the code. The first release from the repository's new home, `StartAppil/Whisp`.
+- **0.3.0**: `react`, `unreact`, `edit`, `revoke`, `markRead`, `startTyping` and `stopTyping`; `mentions` on text and caption sends, and on every `Message`; the `message.edited` event (0.1.0 skips it). Edits and typing starts are refused on a paused number, a phone mention that a LID-addressed group can't place fails with `MENTION_UNRESOLVED`, and `markRead` clears the chat's unread for your team too, with `queued` read receipts not yet delivered. Against an API older than these methods, each new method answers 404 `NOT_FOUND`.
+- **0.1.0**: the first release: sends (text, files, voice notes, pools, daily caps, idempotency, `wait`), reads, downloads, the event stream, and `verifyWebhook`.
+
+## FAQ
+
+**How do I make the sender see blue ticks?** Call `markRead(chat)` on the number when your app has handled the message. The ticks go out only when read receipts are on: the number's "Read receipts" setting, or the project's "Send read receipts" when the number follows the project. `readReceipts: 'off'` tells you they are off; `'queued'` means they were handed to WhatsApp's connection (a number that is offline drops them).
+
+**How do I show "typing..." while my bot thinks?** `await whisp.number(phone).startTyping(chat)` before you start, then send. The send ends it; there's no need to call `stopTyping` unless you decide not to reply. It lasts at most 2 minutes from the latest start: for a longer job, call `startTyping` again every minute or so (cheap: it sends nothing new within 5 seconds). Use `{ state: 'recording' }` before a voice note.
+
+**Does typing make the number look online?** No. It sends WhatsApp's typing state only, never "online". Whether a number shows as online is its "Always online" setting in the panel. Whether the recipient sees "typing..." while the number is offline is up to WhatsApp's app on their side.
+
+**Why didn't my message go out at once?** Look at the message's `status` and `error`, and at the number in `numbers()`:
+
+- `pending` for a few seconds: the guardrails' gap and typing (1 to 4 seconds each), or other sends of the same number ahead of it.
+- `pending` for longer: the number is reconnecting (`status: 'connecting'`; it goes out when it is back, within 6 hours), or paused (`paused: true`; held until a member resumes it).
+- `failed` with `DAILY_CAP_REACHED`, `NUMBER_PAUSED`, `NUMBER_OFFLINE`: see [Why a message failed](#why-a-message-failed).
+- Refused at once with `NUMBER_PAUSED`, `DAILY_CAP_REACHED` or `NO_NUMBER_AVAILABLE`: the number (or the whole pool) can't take sends now; `number.risk` and `numbers()` say why.
+
+**Can I send to someone who never wrote to the number?** Yes, but every such message counts against the number's health (messages to new contacts and the reply rate are risk signals). Keep it to people who expect your message.
+
+**How do I find a message I sent from my own data?** Send it with `reference: yourId`, then `messages({ reference: yourId })`; the reference is also on every event about it.
 
-Node 22.12+ and Bun 1.2+, as ESM (`import`) or CommonJS (`require`). Deno and edge runtimes can send and read; `on()` needs a process that stays up.
+**What if my process restarts while listening?** Save `whisp.cursor` after you handle each event and pass it as `cursor` next time. Dedupe on `event.id`.
 
 ## License