whisp-js 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 startapp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,297 @@
-# Temporary Holding Version
+# whisp-js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Send WhatsApp messages from your Whisp numbers, read their chats, and react to what happens on them, from your server.
+
+- Zero dependencies: `fetch`, Web Streams and Web Crypto only.
+- Node 22.12+ and Bun 1.2+. ESM and CommonJS. Typed.
+- Retries with backoff. Every send carries an `Idempotency-Key`, so a retry never sends twice.
+- `on('message', ...)` over a live event stream that resumes where it stopped.
+- `verifyWebhook` checks the `X-Whisp-Signature` header of webhook requests.
+
+## Install
+
+```sh
+npm install whisp-js
+# or: bun add whisp-js
+```
+
+## 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.
+
+```ts
+import { Whisp } from 'whisp-js'
+
+// Reads WHISP_API_TOKEN when it first needs it.
+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}`)
+})
+```
+
+Phones are WhatsApp digits in international form: `972501234567`. The SDK also takes `+972 50-123-4567` and turns it into digits.
+
+## 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'`. |
+| 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.
+
+### 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:
+
+```ts
+const otp = new Whisp({ phone: ['972501234567', '972501234568'], dailyCap: 300, sticky: false })
+await otp.send('972521112233', 'Your code is 482913') // from the healthiest number that sent under 300 in 24 h
+await otp.send('972521112233', 'Your code is 115720', { dailyCap: 100 }) // this send only
+```
+
+`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:
+
+```ts
+const whisp = new Whisp() // the whole project
+const support = whisp.number('num_7Hq2kD3x')
+```
+
+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.
+
+## Sending
+
+```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
+})
+```
+
+`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`.
+
+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`.
+
+### Files
+
+```ts
+// A public https URL: the server downloads it.
+await whisp.sendImage('972521112233', { url: 'https://example.com/receipt.png' }, { caption: 'Your receipt' })
+
+// 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).
+
+`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.
+
+## Reading
+
+```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 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.
+
+### Downloading a message's file
+
+```ts
+const response = await whisp.downloadMedia(message) // a fetch Response
+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.
+
+## Listening
+
+```ts
+const whisp = new Whisp({ phone: '972501234567', cursor: await loadCursor() })
+
+whisp.on('message', async msg => {
+	await handleReply(msg.from, 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))
+whisp.on('number.status', e => console.log(e.number, e.status))
+whisp.on('gap', gap => reconcile(gap.reason)) // events may have been missed: catch up with reads
+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. |
+
+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.
+
+- **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`).
+- **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:
+
+```ts
+import { verifyWebhook, WhispSignatureError } from 'whisp-js'
+
+const event = await verifyWebhook({
+	body: rawBody, // string, Uint8Array or ArrayBuffer
+	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.
+
+**Express**: the raw body, not `express.json()`:
+
+```ts
+app.post('/whisp', express.raw({ type: 'application/json' }), async (req, res) => {
+	try {
+		const event = await verifyWebhook({ body: req.body, signature: req.get('x-whisp-signature'), secret: process.env.WHISP_WEBHOOK_SECRET })
+		await handle(event)
+		res.sendStatus(200)
+	} catch (error) {
+		res.sendStatus(error instanceof WhispSignatureError ? 400 : 500)
+	}
+})
+```
+
+**Next.js route handlers**: `await request.text()`:
+
+```ts
+export async function POST(request: Request) {
+	const event = await verifyWebhook({ body: await request.text(), signature: request.headers.get('x-whisp-signature'), secret: process.env.WHISP_WEBHOOK_SECRET })
+	await handle(event)
+	return new Response(null, { status: 200 })
+}
+```
+
+**Hono**: `await c.req.text()`:
+
+```ts
+app.post('/whisp', async c => {
+	const event = await verifyWebhook({ body: await c.req.text(), signature: c.req.header('x-whisp-signature'), secret: c.env.WHISP_WEBHOOK_SECRET })
+	await handle(event)
+	return c.body(null, 200)
+})
+```
+
+**Bun.serve**:
+
+```ts
+Bun.serve({
+	async fetch(request) {
+		const event = await verifyWebhook({ body: await request.text(), signature: request.headers.get('x-whisp-signature'), secret: Bun.env.WHISP_WEBHOOK_SECRET })
+		await handle(event)
+		return new Response(null, { status: 200 })
+	},
+})
+```
+
+- 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`.
+- Message text comes from strangers: treat it as untrusted input.
+
+## Errors
+
+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`. |
+| `requestId` | The API's `X-Request-Id`, for support. |
+| `retryAfter` | Seconds the API asked to wait, or `null`. |
+
+`WhispConnectionError` (`NETWORK_ERROR`, `TIMEOUT`) means no answer after every retry. `WhispSignatureError` comes from `verifyWebhook`.
+
+| 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 | |
+|---|---|---|
+| `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.
+
+## 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>)`).
+- Webhook secrets never travel at all: they only sign.
+
+## Runtimes
+
+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.
+
+## License
+
+MIT

package/dist/cjs/client.d.ts

@@ -0,0 +1,164 @@
+import { type EventHandlers } from './listener.js';
+import { type MediaSource } from './media.js';
+import { type Timers } from './runtime.js';
+import type { Chat, ChatListQuery, ChatMessagesQuery, Message, PhoneCheck, ProjectInfo, PublicEventType, SendMessageBody, SendStrategy, WebhookEvent, WhatsAppNumber } from './types.js';
+import { type VerifyWebhookInput } from './webhook.js';
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const DEFAULT_MAX_RETRIES = 2;
+/** `downloadMedia` waits for a file being prepared at most this long. */
+export declare const MEDIA_WAIT_MAX_MS = 60000;
+export interface WhispOptions {
+    /** The project token (`wsp_live_…`). Default: WHISP_API_TOKEN, read on each call until set. */
+    token?: string;
+    /** Phones (`972501234567`, `+972 50-123-4567`) or number ids (`num_7Hq2kD3x`); none = the whole project. */
+    phone?: string | readonly string[];
+    /**
+     * How a pool picks its sender: 'healthiest' (the server's default), 'random' or 'round-robin'. Only used
+     * with several numbers or none.
+     */
+    strategy?: SendStrategy;
+    /** Keep a recipient on the number that last talked to them. Default true. */
+    sticky?: boolean;
+    /**
+     * Send from a number only while it has sent fewer than this many messages in the last 24 hours (1 to
+     * 10,000), on every send of this instance. A number's own daily cap still applies: the lower one wins. The
+     * server counts and enforces it; a pool skips numbers at their cap, a single number answers
+     * DAILY_CAP_REACHED.
+     */
+    dailyCap?: number;
+    /** Default: WHISP_API_URL, else https://api.whisp.lue.my. */
+    baseUrl?: string;
+    /** Per attempt. Default 30,000 ms. */
+    timeoutMs?: number;
+    /** Attempts after the first, for network errors, timeouts, 429 and 5xx. Default 2. */
+    maxRetries?: number;
+    /** Resume the event stream after this cursor (a saved `whisp.cursor`). */
+    cursor?: string;
+    /** Any WHATWG fetch. Default: the global one, looked up on each call. */
+    fetch?: typeof fetch;
+    /**
+     * The SDK refuses to run in a browser, where every visitor could copy the
+     * token. Even with this set, the API answers 403 TOKEN_IN_BROWSER.
+     */
+    dangerouslyAllowBrowser?: boolean;
+}
+/** Test hooks; not part of the published options. */
+export interface InternalWhispOptions extends WhispOptions {
+    timers?: Timers;
+    /** Where errors go when nobody listens to `'error'`. Default console.error. */
+    report?: (error: Error) => void;
+}
+export interface SendOptions {
+    /** A `msg_` id or a WhatsApp id of a message in the same chat. */
+    replyTo?: string;
+    /** Your own id for this send (1-128 characters), echoed on the message and its events. */
+    reference?: string;
+    /** Wait for the outcome: true is 15 s, or a number of ms from 1,000 to 20,000. */
+    wait?: boolean | number;
+    /** This send's daily cap (1 to 10,000), in place of the instance's `dailyCap`. */
+    dailyCap?: number;
+    /** Makes retries safe across your own restarts too. Default: a random UUID per call, kept across its retries. */
+    idempotencyKey?: string;
+}
+export interface SendFileOptions extends SendOptions {
+    caption?: string;
+}
+export interface MessagesQuery {
+    reference: string;
+}
+export interface DownloadOptions {
+    variant?: 'original' | 'thumb';
+}
+/** One page of a list, and the cursor of the next one (null on the last). */
+export interface Page<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+/** Await it for the first page, or `for await` it for every item across pages. */
+export type PageResult<T> = Promise<Page<T>> & AsyncIterable<T>;
+export interface VerifyResult extends ProjectInfo {
+    numbers: WhatsAppNumber[];
+}
+export declare class Whisp {
+    #private;
+    constructor(options?: WhispOptions);
+    /**
+     * The cursor after the last event delivered to handlers (6.5): save it and
+     * pass it as `cursor` to resume after a restart. Not an event's `evt_` id,
+     * which is `event.event.id` in a handler. Before the first event it is
+     * where the stream started (its `ready`), so a save then resumes from
+     * there; null until the stream first opens, unless `cursor` was given
+     * (sdk-reconnect-without-cursor-loses-events).
+     */
+    get cursor(): string | null;
+    /** A copy that sends from, reads and listens on this one number (a phone or a `num_` id). */
+    number(phoneOrId: string): Whisp;
+    /**
+     * Checks the token and the instance's numbers (GET /project, then GET
+     * /numbers): throws NUMBER_NOT_IN_PROJECT listing every phone or id that
+     * isn't the token's project's. Optional: the first send or listen reports
+     * the same.
+     */
+    verify(): Promise<VerifyResult>;
+    /** Sends text (`POST /messages`) from the instance's number, pool or project. Resolves the message (`pending`, or its status after `wait`). */
+    send(to: string, text: string, options?: SendOptions): Promise<Message>;
+    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>;
+    sendVoice(to: string, media: MediaSource, options?: SendOptions): Promise<Message>;
+    /**
+     * `POST /messages` with a body you build (5.6). The instance's `from`,
+     * `strategy`, `sticky` and `dailyCap` fill in what the body leaves out.
+     */
+    sendMessage(body: SendMessageBody, options?: Pick<SendOptions, 'idempotencyKey'>): Promise<Message>;
+    /** Every number of the project, any status. */
+    numbers(): Promise<WhatsAppNumber[]>;
+    /** One message of the project's numbers; 404 MESSAGE_NOT_FOUND otherwise. */
+    message(messageId: string): Promise<Message>;
+    /** What earlier sends with this `reference` made, newest first, at most 50. */
+    messages(query: MessagesQuery): Promise<Message[]>;
+    /** Is this phone on WhatsApp, asked through the instance's number. */
+    check(phone: string): Promise<PhoneCheck>;
+    /** The number's chats, newest activity first. */
+    chats(query?: ChatListQuery): PageResult<Chat>;
+    /** One chat: a phone, a `cht_` id or a group JID (a merged-away id resolves to the chat it joined). */
+    chat(chat: string): Promise<Chat>;
+    /**
+     * A chat's messages, newest first, history included. Each next page is
+     * older (`nextCursor` goes in `before`); after an `after` request, each next
+     * page is newer (`nextCursor` goes in `after`).
+     */
+    chatMessages(chat: string, query?: ChatMessagesQuery): PageResult<Message>;
+    /**
+     * A message's file as a fetch `Response` (12.3). Asks the API for a
+     * 5-minute link with the token, then fetches the link with no token and no
+     * redirects. A file still being prepared (409 MEDIA_NOT_READY with
+     * Retry-After) is waited for, up to 60 s.
+     */
+    downloadMedia(message: Message | string, options?: DownloadOptions): Promise<Response>;
+    /**
+     * Calls `handler` for each event of this name (12.4): any of the twelve
+     * types, `'message'` (= `message.received`), `'*'`, or the stream's own
+     * `'open'`, `'close'`, `'gap'` and `'error'`. The first event handler
+     * opens the stream. Returns `off()`.
+     */
+    on(event: '*', handler: EventHandlers['*']): () => void;
+    on(event: 'message', handler: EventHandlers['message']): () => void;
+    on(event: 'open', handler: EventHandlers['open']): () => void;
+    on(event: 'close', handler: EventHandlers['close']): () => void;
+    on(event: 'gap', handler: EventHandlers['gap']): () => void;
+    on(event: 'error', handler: EventHandlers['error']): () => void;
+    on<T extends PublicEventType>(event: T, handler: EventHandlers[T]): () => void;
+    /** Removes a handler; the stream closes with the last event handler. */
+    off(event: '*', handler: EventHandlers['*']): void;
+    off(event: 'message', handler: EventHandlers['message']): void;
+    off(event: 'open', handler: EventHandlers['open']): void;
+    off(event: 'close', handler: EventHandlers['close']): void;
+    off(event: 'gap', handler: EventHandlers['gap']): void;
+    off(event: 'error', handler: EventHandlers['error']): void;
+    off<T extends PublicEventType>(event: T, handler: EventHandlers[T]): void;
+    /** Ends the stream, forgets every handler, and stops retries still waiting for their turn. */
+    close(): void;
+    /** The standalone `verifyWebhook`, for convenience. */
+    verifyWebhook(input: VerifyWebhookInput): Promise<WebhookEvent>;
+}