whisp-js 0.0.0-stage → 0.1.0

package/dist/esm/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>;
+}

package/dist/esm/client.js

@@ -0,0 +1,456 @@
+/**
+ * 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.
+ */
+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;
+};
+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 };
+    }
+    #common(options) {
+        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;
+        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.
+        const common = this.#common(options);
+        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;
+    }
+    // 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, 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"];