whisp-js 0.0.0-stage → 0.3.0

package/dist/esm/client.js

@@ -0,0 +1,566 @@
+/**
+ * The `Whisp` client (phase2-design 12.2, 12.3).
+ *
+ * Nothing is called at construction. The token is read when a call needs it
+ * (`token`, else WHISP_API_TOKEN), and so is the base URL (`baseUrl`, else
+ * WHISP_API_URL, else the hosted API), so a value set after import still
+ * counts. Phones are checked at once: a typo throws here, not on the first
+ * send.
+ *
+ * An instance sends from its `phone`: one number, a pool (an array, picked
+ * server-side by `strategy`, `healthiest` unless set, sticky by default), or
+ * none, the whole project (its default number, else every number as a
+ * pool). `number(x)` returns a copy scoped to one number, which the reads
+ * that need one number require. `dailyCap` (phase3-design 12.4) goes with
+ * every send; the server counts and enforces it, never the SDK, since
+ * several app instances share one number.
+ *
+ * 0.3.0 (api-gaps-design 12, T6): reactions, edits, deletes for everyone,
+ * marking a chat read and typing presence, and `mentions` on text and
+ * caption sends. None of them carries an `Idempotency-Key`: each is
+ * idempotent by state on the server, so they are retried like reads.
+ */
+import { API_TOKEN_ENV, API_URL_ENV, DAILY_CAP_MAX, DAILY_CAP_MIN, DEFAULT_BASE_URL, FROM_MAX, SEND_STRATEGIES, TOKEN_PATTERN, WAIT_DEFAULT_MS, } from './constants.js';
+import { localError, WhispError } from './errors.js';
+import { Listener } from './listener.js';
+import { prepareFile, putUpload } from './media.js';
+import { requireNumberRef } from './refs.js';
+import { isBrowser, randomId, readEnv, realTimers, sleep, userAgent } from './runtime.js';
+import { request } from './transport.js';
+import { verifyWebhook } from './webhook.js';
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_RETRIES = 2;
+/** `downloadMedia` waits for a file being prepared at most this long. */
+export const MEDIA_WAIT_MAX_MS = 60_000;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const invalidResponse = (what) => new WhispError({ code: 'INVALID_RESPONSE', message: `The API's answer to ${what} is not in the documented shape` });
+/** The body as T when `check` holds, else INVALID_RESPONSE. The API only grows (4.1), so only what the SDK reads is checked. */
+const expect = (body, what, check) => {
+    if (!isRecord(body) || !check(body))
+        throw invalidResponse(what);
+    return body;
+};
+const segment = (value) => encodeURIComponent(value);
+const positiveInt = (value, fallback, name, min, max) => {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw localError('OPTIONS_INVALID', `${name} must be a whole number from ${min} to ${max}`);
+    }
+    return value;
+};
+/** A `dailyCap` as the API takes it (1 to 10,000, whole), or undefined when none was given. Checked before any call. */
+const checkDailyCap = (value, name) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < DAILY_CAP_MIN || value > DAILY_CAP_MAX) {
+        throw localError('OPTIONS_INVALID', `${name} must be a whole number from ${DAILY_CAP_MIN} to 10,000`);
+    }
+    return value;
+};
+const checkBaseUrl = (value, source) => {
+    let protocol = '';
+    try {
+        protocol = new URL(value).protocol;
+    }
+    catch {
+        // Reported below.
+    }
+    if (protocol !== 'https:' && protocol !== 'http:') {
+        throw localError('OPTIONS_INVALID', `${source} must be an http(s) URL`);
+    }
+    return value.replace(/\/+$/, '');
+};
+const normalizeFrom = (phone) => {
+    if (phone === undefined)
+        return null;
+    if (typeof phone === 'string')
+        return requireNumberRef(phone, 'phone');
+    if (!Array.isArray(phone))
+        throw localError('OPTIONS_INVALID', 'phone must be a string or an array of strings');
+    if (phone.length === 0)
+        throw localError('OPTIONS_INVALID', 'phone is an empty list; leave it out to use the whole project');
+    const refs = [...new Set(phone.map(ref => requireNumberRef(ref, 'phone')))];
+    if (refs.length > FROM_MAX)
+        throw localError('OPTIONS_INVALID', `A pool has at most ${FROM_MAX} numbers`);
+    return refs;
+};
+/** `mentions` as the API takes them: a list of strings, checked here only for its shape (the server parses each). */
+const checkMentions = (value, name) => {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length === 0 || value.some(item => typeof item !== 'string')) {
+        throw localError('OPTIONS_INVALID', `${name} must be a non-empty list of phones or <digits>@lid JIDs`);
+    }
+    return value;
+};
+/** A message's id: the message itself or its `msg_` id. */
+const messageIdOf = (message, method) => {
+    const id = typeof message === 'string' ? message : message?.id;
+    if (typeof id !== 'string' || !/^msg_[0-9A-Za-z]{1,64}$/.test(id)) {
+        throw localError('OPTIONS_INVALID', `${method}() takes a message or its msg_ id`);
+    }
+    return id;
+};
+const waitMs = (wait) => wait === true ? WAIT_DEFAULT_MS : typeof wait === 'number' && Number.isFinite(wait) ? wait : 0;
+const defaultReport = (error) => {
+    console.error(`[whisp-sdk] ${error.name}: ${error.message}`);
+};
+export class Whisp {
+    #options;
+    #scope;
+    #timeoutMs;
+    #maxRetries;
+    #timers;
+    #listener;
+    /** Aborted by close(): retries waiting for their turn give up. Replaced, so later calls retry again. */
+    #retries = new AbortController();
+    constructor(options = {}) {
+        const internal = options;
+        if (isBrowser() && options.dangerouslyAllowBrowser !== true) {
+            throw localError('TOKEN_IN_BROWSER', 'The Whisp SDK runs on your server: in a browser, every visitor could copy the token and send from your numbers.');
+        }
+        if (options.strategy !== undefined && !SEND_STRATEGIES.includes(options.strategy)) {
+            throw localError('OPTIONS_INVALID', "strategy must be 'healthiest', 'random' or 'round-robin'");
+        }
+        if (options.sticky !== undefined && typeof options.sticky !== 'boolean') {
+            throw localError('OPTIONS_INVALID', 'sticky must be true or false');
+        }
+        checkDailyCap(options.dailyCap, 'dailyCap');
+        if (options.baseUrl !== undefined)
+            checkBaseUrl(options.baseUrl, 'baseUrl');
+        if (options.cursor !== undefined && (typeof options.cursor !== 'string' || options.cursor === '')) {
+            throw localError('OPTIONS_INVALID', 'cursor must be a cursor string saved from whisp.cursor');
+        }
+        this.#options = { ...internal };
+        this.#scope = { from: normalizeFrom(options.phone) };
+        this.#timeoutMs = positiveInt(options.timeoutMs, DEFAULT_TIMEOUT_MS, 'timeoutMs', 1, 600_000);
+        this.#maxRetries = positiveInt(options.maxRetries, DEFAULT_MAX_RETRIES, 'maxRetries', 0, 10);
+        this.#timers = internal.timers ?? realTimers;
+        const numbers = this.#scope.from === null ? null : [this.#scope.from].flat();
+        this.#listener = new Listener({
+            resolve: () => this.#target(),
+            numbers,
+            cursor: options.cursor ?? null,
+            connectTimeoutMs: this.#timeoutMs,
+            timers: this.#timers,
+            report: internal.report ?? defaultReport,
+        });
+    }
+    /**
+     * 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() {
+        return this.#listener.cursor;
+    }
+    /** A copy that sends from, reads and listens on this one number (a phone or a `num_` id). */
+    number(phoneOrId) {
+        const ref = requireNumberRef(phoneOrId, 'number()');
+        return new Whisp({ ...this.#options, phone: ref });
+    }
+    // Connection ---------------------------------------------------------------------------------
+    #fetch() {
+        const custom = this.#options.fetch;
+        // Looked up per call, so a fetch installed after import is used; called unbound, or window.fetch throws.
+        return custom ? (input, init) => custom(input, init) : (input, init) => globalThis.fetch(input, init);
+    }
+    #target() {
+        const token = this.#options.token?.trim() || readEnv(API_TOKEN_ENV);
+        if (!token) {
+            throw localError('TOKEN_MISSING', `No token: pass { token } or set ${API_TOKEN_ENV} (the project's API & SDK tab)`);
+        }
+        if (!TOKEN_PATTERN.test(token)) {
+            throw localError('TOKEN_INVALID', "The token is not a Whisp project token (wsp_live_…). Copy it again from the project's API & SDK tab.");
+        }
+        const baseUrl = this.#options.baseUrl ?? readEnv(API_URL_ENV) ?? DEFAULT_BASE_URL;
+        return {
+            token,
+            baseUrl: checkBaseUrl(baseUrl, this.#options.baseUrl !== undefined ? 'baseUrl' : API_URL_ENV),
+            fetch: this.#fetch(),
+            userAgent: userAgent(),
+        };
+    }
+    #transport() {
+        return {
+            ...this.#target(),
+            timeoutMs: this.#timeoutMs,
+            maxRetries: this.#maxRetries,
+            timers: this.#timers,
+            retrySignal: this.#retries.signal,
+        };
+    }
+    async #call(call) {
+        return (await request(this.#transport(), call)).body;
+    }
+    #single(method) {
+        const { from } = this.#scope;
+        const single = typeof from === 'string' ? from : from?.length === 1 ? from[0] : undefined;
+        if (single === undefined) {
+            throw localError('NUMBER_REQUIRED', `${method}() reads one number's data: call it on whisp.number('<phone or num_ id>')`);
+        }
+        return single;
+    }
+    // Project -------------------------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    async verify() {
+        const info = expect(await this.#call({ method: 'GET', path: '/project' }), 'GET /project', body => isRecord(body.project) && isRecord(body.token));
+        const numbers = await this.numbers();
+        const { from } = this.#scope;
+        const missing = (from === null ? [] : [from].flat()).filter(ref => !numbers.some(number => number.id === ref || number.phone === ref));
+        if (missing.length > 0) {
+            throw new WhispError({
+                code: 'NUMBER_NOT_IN_PROJECT',
+                message: `${missing.join(', ')} ${missing.length === 1 ? 'is not a number' : 'are not numbers'} of this project`,
+                params: { number: missing.join(',') },
+            });
+        }
+        return { ...info, numbers };
+    }
+    // Sending -------------------------------------------------------------------------------------
+    /** Sends text (`POST /messages`) from the instance's number, pool or project. Resolves the message (`pending`, or its status after `wait`). */
+    async send(to, text, options = {}) {
+        // Async, so a bad option rejects like every other failure instead of throwing from the call.
+        return this.#send({ to, type: 'text', text, ...this.#common(options) }, options);
+    }
+    sendImage(to, media, options = {}) {
+        return this.#sendFile('image', to, media, options, options.caption);
+    }
+    sendVideo(to, media, options = {}) {
+        return this.#sendFile('video', to, media, options, options.caption);
+    }
+    sendDocument(to, media, options = {}) {
+        return this.#sendFile('document', to, media, options, options.caption);
+    }
+    sendVoice(to, media, options = {}) {
+        return this.#sendFile('voice', to, media, options, undefined);
+    }
+    /**
+     * `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, options = {}) {
+        const defaults = { ...this.#pool(), ...this.#cap(undefined) };
+        const filled = { ...body };
+        for (const [key, value] of Object.entries(defaults))
+            if (filled[key] === undefined)
+                filled[key] = value;
+        return this.#send(filled, { ...options, wait: body.wait });
+    }
+    /** `from`, `strategy` and `sticky` for this instance; strategy and sticky only where a pool picks. */
+    #pool() {
+        const { from } = this.#scope;
+        const out = {};
+        if (from !== null)
+            out.from = from;
+        if (from === null || Array.isArray(from)) {
+            if (this.#options.strategy !== undefined)
+                out.strategy = this.#options.strategy;
+            if (this.#options.sticky !== undefined)
+                out.sticky = this.#options.sticky;
+        }
+        return out;
+    }
+    /** `dailyCap` for one send: the call's, else the instance's; none when neither set one. */
+    #cap(perCall) {
+        const cap = checkDailyCap(perCall, 'dailyCap') ?? this.#options.dailyCap;
+        return cap === undefined ? {} : { dailyCap: cap };
+    }
+    /** The body fields every send shares; `mentions` only where the kind has text to carry them. */
+    #common(options, { mentions = true } = {}) {
+        const out = { ...this.#pool(), ...this.#cap(options.dailyCap) };
+        if (options.replyTo !== undefined)
+            out.replyTo = options.replyTo;
+        if (options.reference !== undefined)
+            out.reference = options.reference;
+        if (options.wait !== undefined)
+            out.wait = options.wait;
+        const listed = mentions ? checkMentions(options.mentions, 'mentions') : undefined;
+        if (listed !== undefined)
+            out.mentions = listed;
+        return out;
+    }
+    async #send(body, options) {
+        const idempotencyKey = options.idempotencyKey ?? randomId();
+        // The server holds a `wait` send open up to 20 s; the attempt's timeout leaves room for it.
+        const wait = waitMs(options.wait);
+        const answer = await this.#call({
+            method: 'POST',
+            path: '/messages',
+            body,
+            idempotencyKey,
+            ...(wait > 0 ? { timeoutMs: Math.max(this.#timeoutMs, wait + 10_000) } : {}),
+        });
+        return expect(answer, 'POST /messages', message => typeof message.id === 'string');
+    }
+    async #sendFile(kind, to, media, options, caption) {
+        // The options first: a bad one fails before any file is uploaded. A voice note never carries mentions.
+        const common = this.#common(options, { mentions: kind !== 'voice' });
+        let input;
+        if (isRecord(media) && typeof media.url === 'string') {
+            input = { url: media.url };
+            if (typeof media.fileName === 'string')
+                input.fileName = media.fileName;
+            if (typeof media.mime === 'string')
+                input.mime = media.mime;
+        }
+        else if (isRecord(media) && 'file' in media && media.file !== undefined && media.file !== null) {
+            input = { uploadId: await this.#upload(kind, media) };
+        }
+        else {
+            throw localError('MEDIA_INVALID', `send${kind[0]?.toUpperCase()}${kind.slice(1)}() takes { url } or { file }`);
+        }
+        const body = { to, type: kind, media: input, ...common };
+        if (caption !== undefined)
+            body.caption = caption;
+        return this.#send(body, options);
+    }
+    /** `POST /uploads`, then the PUT to storage; resolves the upload id a send takes. */
+    async #upload(kind, media) {
+        const file = await prepareFile(kind, media);
+        const upload = expect(await this.#call({
+            method: 'POST',
+            path: '/uploads',
+            body: { kind, mime: file.mime, size: file.size, name: file.name },
+        }), 'POST /uploads', body => typeof body.uploadId === 'string' && typeof body.url === 'string' && isRecord(body.headers));
+        await putUpload({
+            fetch: this.#fetch(),
+            timers: this.#timers,
+            timeoutMs: this.#timeoutMs,
+            maxRetries: this.#maxRetries,
+            retrySignal: this.#retries.signal,
+        }, upload.url, upload.headers, file);
+        return upload.uploadId;
+    }
+    // Message actions (0.3.0) ---------------------------------------------------------------------
+    /**
+     * Sets this number's reaction to a message (one emoji), replacing its earlier one. Resolves once the server
+     * queued it for the number's connection; a `message.reaction` event with `fromMe: true` follows.
+     */
+    async react(message, emoji) {
+        if (typeof emoji !== 'string' || emoji === '') {
+            throw localError('OPTIONS_INVALID', 'react() takes one emoji; unreact() removes the reaction');
+        }
+        await this.#reaction(messageIdOf(message, 'react'), emoji);
+    }
+    /** Removes this number's reaction to a message. */
+    async unreact(message) {
+        await this.#reaction(messageIdOf(message, 'unreact'), '');
+    }
+    async #reaction(id, emoji) {
+        expect(await this.#call({ method: 'POST', path: `/messages/${segment(id)}/reaction`, body: { emoji } }), 'POST /messages/:messageId/reaction', body => body.accepted === true);
+    }
+    /**
+     * Edits the text or caption of a message this number sent, within WhatsApp's 15 minutes
+     * (EDIT_WINDOW_PASSED after). Refused on a paused number (NUMBER_PAUSED). Resolves the edited message; the
+     * same text without `mentions` resolves it unchanged.
+     */
+    async edit(message, text, options = {}) {
+        const id = messageIdOf(message, 'edit');
+        if (typeof text !== 'string' || text === '')
+            throw localError('OPTIONS_INVALID', 'edit() takes the new text');
+        const body = { text };
+        const mentions = checkMentions(options.mentions, 'mentions');
+        if (mentions !== undefined)
+            body.mentions = mentions;
+        return expect(await this.#call({ method: 'POST', path: `/messages/${segment(id)}/edit`, body }), 'POST /messages/:messageId/edit', answer => typeof answer.id === 'string');
+    }
+    /**
+     * Deletes a message this number sent for everyone, within 2 days (REVOKE_WINDOW_PASSED after). Resolves the
+     * message with `deletedAt` set, also when it was deleted already.
+     */
+    async revoke(message) {
+        const id = messageIdOf(message, 'revoke');
+        return expect(
+        // An empty object: the server takes no body, and every runtime then sends a length.
+        await this.#call({ method: 'POST', path: `/messages/${segment(id)}/revoke`, body: {} }), 'POST /messages/:messageId/revoke', answer => typeof answer.id === 'string');
+    }
+    /**
+     * Marks a chat of this instance's number read (a phone, a `cht_` id or a group JID). Unread is one count per
+     * chat, so this clears it for the panel's members too. `readReceipts` says what happened to the blue ticks:
+     * `queued` (handed to the server, not proof WhatsApp got them), `off` (the number's setting) or `none`
+     * (nothing was unread).
+     */
+    async markRead(chat) {
+        const number = this.#single('markRead');
+        return expect(await this.#call({
+            method: 'POST',
+            path: `/numbers/${segment(number)}/chats/${segment(chat)}/read`,
+            body: {},
+        }), 'POST /numbers/:number/chats/:chat/read', body => isRecord(body.chat) && typeof body.readReceipts === 'string');
+    }
+    /**
+     * Shows "typing..." (or "recording audio..." with `state: 'recording'`) in a chat of this instance's number (a
+     * phone, a `cht_` id or a group JID). The server keeps it up until a message of the number goes out in that chat
+     * (no need to stop before sending), stopTyping(), or 2 minutes from the latest start (call it again to keep
+     * going). Refused on a paused number (NUMBER_PAUSED), in a group the number left (NOT_IN_GROUP) and on a number
+     * that isn't connected or connecting (NUMBER_NOT_CONNECTED).
+     */
+    async startTyping(chat, options = {}) {
+        const number = this.#single('startTyping');
+        const state = options.state ?? 'composing';
+        if (state !== 'composing' && state !== 'recording') {
+            throw localError('OPTIONS_INVALID', "startTyping()'s state must be 'composing' or 'recording'");
+        }
+        const body = { state };
+        return expect(await this.#call({ method: 'POST', path: `/numbers/${segment(number)}/chats/${segment(chat)}/typing`, body }), 'POST /numbers/:number/chats/:chat/typing', answer => typeof answer.state === 'string');
+    }
+    /** Stops this number's typing in a chat at once ("paused"). Safe to call when nothing is typing. */
+    async stopTyping(chat) {
+        const number = this.#single('stopTyping');
+        expect(
+        // An empty object: the server takes no body, and every runtime then sends a length.
+        await this.#call({
+            method: 'POST',
+            path: `/numbers/${segment(number)}/chats/${segment(chat)}/typing/stop`,
+            body: {},
+        }), 'POST /numbers/:number/chats/:chat/typing/stop', answer => answer.state === 'paused');
+    }
+    // Reads ---------------------------------------------------------------------------------------
+    /** Every number of the project, any status. */
+    async numbers() {
+        const list = expect(await this.#call({ method: 'GET', path: '/numbers' }), 'GET /numbers', body => Array.isArray(body.numbers));
+        return list.numbers;
+    }
+    /** One message of the project's numbers; 404 MESSAGE_NOT_FOUND otherwise. */
+    async message(messageId) {
+        return expect(await this.#call({ method: 'GET', path: `/messages/${segment(messageId)}` }), 'GET /messages/:messageId', body => typeof body.id === 'string');
+    }
+    /** What earlier sends with this `reference` made, newest first, at most 50. */
+    async messages(query) {
+        const list = expect(await this.#call({ method: 'GET', path: '/messages', query: { reference: query.reference } }), 'GET /messages', body => Array.isArray(body.messages));
+        return list.messages;
+    }
+    /** Is this phone on WhatsApp, asked through the instance's number. */
+    async check(phone) {
+        const number = this.#single('check');
+        return expect(await this.#call({ method: 'GET', path: `/numbers/${segment(number)}/check/${segment(phone)}` }), 'GET /numbers/:number/check/:phone', body => typeof body.exists === 'boolean');
+    }
+    /** The number's chats, newest activity first. */
+    chats(query = {}) {
+        const number = this.#single('chats');
+        const fetchPage = async (cursor) => {
+            const list = expect(await this.#call({
+                method: 'GET',
+                path: `/numbers/${segment(number)}/chats`,
+                query: { ...query, ...(cursor !== undefined ? { cursor } : {}) },
+            }), 'GET /numbers/:number/chats', body => Array.isArray(body.chats));
+            return { items: list.chats, nextCursor: list.nextCursor ?? null };
+        };
+        return paginate(fetchPage);
+    }
+    /** One chat: a phone, a `cht_` id or a group JID (a merged-away id resolves to the chat it joined). */
+    async chat(chat) {
+        const number = this.#single('chat');
+        return expect(await this.#call({ method: 'GET', path: `/numbers/${segment(number)}/chats/${segment(chat)}` }), 'GET /numbers/:number/chats/:chat', body => typeof body.id === 'string');
+    }
+    /**
+     * 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, query = {}) {
+        const number = this.#single('chatMessages');
+        const direction = query.after !== undefined && query.before === undefined ? 'after' : 'before';
+        const fetchPage = async (cursor) => {
+            const list = expect(await this.#call({
+                method: 'GET',
+                path: `/numbers/${segment(number)}/chats/${segment(chat)}/messages`,
+                query: { ...query, ...(cursor !== undefined ? { [direction]: cursor } : {}) },
+            }), 'GET /numbers/:number/chats/:chat/messages', body => Array.isArray(body.messages));
+            return { items: list.messages, nextCursor: list.nextCursor ?? null };
+        };
+        return paginate(fetchPage);
+    }
+    /**
+     * 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.
+     */
+    async downloadMedia(message, options = {}) {
+        const id = typeof message === 'string' ? message : message?.id;
+        if (typeof id !== 'string' || id === '')
+            throw localError('OPTIONS_INVALID', 'downloadMedia() takes a message or its id');
+        const started = this.#timers.now();
+        let link;
+        for (;;) {
+            try {
+                link = expect(await this.#call({
+                    method: 'GET',
+                    path: `/messages/${segment(id)}/media`,
+                    query: { redirect: '0', variant: options.variant },
+                }), 'GET /messages/:messageId/media', body => typeof body.url === 'string');
+                break;
+            }
+            catch (error) {
+                const pending = error instanceof WhispError && error.code === 'MEDIA_NOT_READY' && error.retryAfter !== null;
+                const waitFor = pending ? Math.max(1, error.retryAfter) * 1_000 : 0;
+                if (!pending || this.#timers.now() - started + waitFor > MEDIA_WAIT_MAX_MS)
+                    throw error;
+                await sleep(this.#timers, waitFor, this.#retries.signal);
+                if (this.#retries.signal.aborted)
+                    throw error;
+            }
+        }
+        let response;
+        try {
+            // A new request: no Authorization, and a redirect is an error rather than a hop.
+            response = await this.#fetch()(link.url, { method: 'GET', redirect: 'error' });
+        }
+        catch (cause) {
+            throw new WhispError({ code: 'MEDIA_DOWNLOAD_FAILED', message: 'The file link could not be fetched', cause });
+        }
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => { });
+            throw new WhispError({
+                code: 'MEDIA_DOWNLOAD_FAILED',
+                status: response.status,
+                message: `The file link answered ${response.status}`,
+            });
+        }
+        return response;
+    }
+    on(event, handler) {
+        if (typeof handler !== 'function')
+            throw localError('OPTIONS_INVALID', `on('${String(event)}') needs a function`);
+        this.#listener.add(event, handler);
+        return () => this.#listener.remove(event, handler);
+    }
+    off(event, handler) {
+        this.#listener.remove(event, handler);
+    }
+    /** Ends the stream, forgets every handler, and stops retries still waiting for their turn. */
+    close() {
+        this.#listener.close();
+        this.#retries.abort();
+        this.#retries = new AbortController();
+    }
+    /** The standalone `verifyWebhook`, for convenience. */
+    verifyWebhook(input) {
+        return verifyWebhook(input);
+    }
+}
+/** A first page fetched at once, awaitable, and iterable across every page. */
+const paginate = (fetchPage) => {
+    const first = fetchPage(undefined);
+    const iterate = async function* () {
+        let page = await first;
+        for (;;) {
+            yield* page.items;
+            if (page.nextCursor === null || page.items.length === 0)
+                return;
+            page = await fetchPage(page.nextCursor);
+        }
+    };
+    return Object.assign(first, { [Symbol.asyncIterator]: iterate });
+};

package/dist/esm/constants.d.ts

@@ -0,0 +1,43 @@
+/** The npm name (16.2 decision 1: `@whisphq/sdk` if the `@whisp` scope isn't the owner's). */
+export declare const SDK_PACKAGE_NAME = "whisp-js";
+/** Where the token is read from when none is passed, on the first call. */
+export declare const API_TOKEN_ENV = "WHISP_API_TOKEN";
+/** Where a different base URL is read from (agent stacks, local tests). */
+export declare const API_URL_ENV = "WHISP_API_URL";
+export declare const DEFAULT_BASE_URL = "https://api.whisp.lue.my";
+/** `whisp-sdk/<version> (<runtime>/<version>)`. */
+export declare const USER_AGENT_PREFIX = "whisp-sdk";
+/** The webhook signature header, lowercase as HTTP header names compare. */
+export declare const SIGNATURE_HEADER = "x-whisp-signature";
+/** Every project token starts with it. */
+export declare const TOKEN_PREFIX = "wsp_live_";
+/** Every webhook signing secret starts with it. */
+export declare const WEBHOOK_SECRET_PREFIX = "wsp_whs_";
+/** An event cursor (the SSE `id:`) starts with it; the rest is opaque. */
+export declare const EVENT_CURSOR_PREFIX = "c_";
+/** How old a webhook signature's timestamp may be, by default (seconds). */
+export declare const SIGNATURE_TOLERANCE_SECONDS = 300;
+/** A project token's whole shape: the prefix, 32 base62 and a 6-character checksum (core's `TOKEN_PATTERN`). */
+export declare const TOKEN_PATTERN: RegExp;
+/** A webhook signing secret's whole shape (core's `WEBHOOK_SECRET_PATTERN`). */
+export declare const WEBHOOK_SECRET_PATTERN: RegExp;
+/** A number id: `num_` and 8 characters of core's base58 id alphabet (no 0, O, I or l). */
+export declare const NUMBER_ID_PATTERN: RegExp;
+/** At most this many numbers in one pool (`from`, PUBLIC_LIMITS.fromMax). */
+export declare const FROM_MAX = 20;
+/** `wait: true` waits this long on the server (PUBLIC_LIMITS.waitDefaultMs). */
+export declare const WAIT_DEFAULT_MS = 15000;
+/** How a pool picks its number (core SEND_STRATEGIES); the first, `healthiest`, is the server's default. */
+export declare const SEND_STRATEGIES: readonly ["healthiest", "random", "round-robin"];
+/** A send's own `dailyCap`: a whole number in this range (core SEND_DAILY_CAP). */
+export declare const DAILY_CAP_MIN = 1;
+export declare const DAILY_CAP_MAX = 10000;
+/** The upload cap of each kind (core's `uploadMaxBytes`); a stream is never read past it. */
+export declare const UPLOAD_MAX_BYTES: {
+    readonly image: number;
+    readonly video: number;
+    readonly voice: number;
+    readonly document: number;
+};
+/** PLAN's twelve, then `message.edited` (0.3.0), in the order the API lists them. */
+export declare const PUBLIC_EVENT_TYPES: readonly ["message.received", "message.sent", "message.status", "message.reaction", "message.deleted", "chat.updated", "presence.updated", "group.updated", "group.participants", "number.status", "number.risk", "call.received", "message.edited"];

package/dist/esm/constants.js

@@ -0,0 +1,57 @@
+/** The npm name (16.2 decision 1: `@whisphq/sdk` if the `@whisp` scope isn't the owner's). */
+export const SDK_PACKAGE_NAME = 'whisp-js';
+/** Where the token is read from when none is passed, on the first call. */
+export const API_TOKEN_ENV = 'WHISP_API_TOKEN';
+/** Where a different base URL is read from (agent stacks, local tests). */
+export const API_URL_ENV = 'WHISP_API_URL';
+export const DEFAULT_BASE_URL = 'https://api.whisp.lue.my';
+/** `whisp-sdk/<version> (<runtime>/<version>)`. */
+export const USER_AGENT_PREFIX = 'whisp-sdk';
+/** The webhook signature header, lowercase as HTTP header names compare. */
+export const SIGNATURE_HEADER = 'x-whisp-signature';
+/** Every project token starts with it. */
+export const TOKEN_PREFIX = 'wsp_live_';
+/** Every webhook signing secret starts with it. */
+export const WEBHOOK_SECRET_PREFIX = 'wsp_whs_';
+/** An event cursor (the SSE `id:`) starts with it; the rest is opaque. */
+export const EVENT_CURSOR_PREFIX = 'c_';
+/** How old a webhook signature's timestamp may be, by default (seconds). */
+export const SIGNATURE_TOLERANCE_SECONDS = 300;
+/** A project token's whole shape: the prefix, 32 base62 and a 6-character checksum (core's `TOKEN_PATTERN`). */
+export const TOKEN_PATTERN = /^wsp_live_[0-9A-Za-z]{38}$/;
+/** A webhook signing secret's whole shape (core's `WEBHOOK_SECRET_PATTERN`). */
+export const WEBHOOK_SECRET_PATTERN = /^wsp_whs_[0-9A-Za-z]{38}$/;
+/** A number id: `num_` and 8 characters of core's base58 id alphabet (no 0, O, I or l). */
+export const NUMBER_ID_PATTERN = /^num_[1-9A-HJ-NP-Za-km-z]{8}$/;
+/** At most this many numbers in one pool (`from`, PUBLIC_LIMITS.fromMax). */
+export const FROM_MAX = 20;
+/** `wait: true` waits this long on the server (PUBLIC_LIMITS.waitDefaultMs). */
+export const WAIT_DEFAULT_MS = 15_000;
+/** How a pool picks its number (core SEND_STRATEGIES); the first, `healthiest`, is the server's default. */
+export const SEND_STRATEGIES = ['healthiest', 'random', 'round-robin'];
+/** A send's own `dailyCap`: a whole number in this range (core SEND_DAILY_CAP). */
+export const DAILY_CAP_MIN = 1;
+export const DAILY_CAP_MAX = 10_000;
+/** The upload cap of each kind (core's `uploadMaxBytes`); a stream is never read past it. */
+export const UPLOAD_MAX_BYTES = {
+    image: 16 * 1024 * 1024,
+    video: 64 * 1024 * 1024,
+    voice: 16 * 1024 * 1024,
+    document: 100 * 1024 * 1024,
+};
+/** PLAN's twelve, then `message.edited` (0.3.0), in the order the API lists them. */
+export const PUBLIC_EVENT_TYPES = [
+    'message.received',
+    'message.sent',
+    'message.status',
+    'message.reaction',
+    'message.deleted',
+    'chat.updated',
+    'presence.updated',
+    'group.updated',
+    'group.participants',
+    'number.status',
+    'number.risk',
+    'call.received',
+    'message.edited',
+];