whisp-js 0.0.0-stage → 0.1.0

package/dist/cjs/client.js

@@ -0,0 +1,460 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Whisp = exports.MEDIA_WAIT_MAX_MS = exports.DEFAULT_MAX_RETRIES = exports.DEFAULT_TIMEOUT_MS = void 0;
+/**
+ * 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.
+ */
+const constants_ts_1 = require("./constants.js");
+const errors_ts_1 = require("./errors.js");
+const listener_ts_1 = require("./listener.js");
+const media_ts_1 = require("./media.js");
+const refs_ts_1 = require("./refs.js");
+const runtime_ts_1 = require("./runtime.js");
+const transport_ts_1 = require("./transport.js");
+const webhook_ts_1 = require("./webhook.js");
+exports.DEFAULT_TIMEOUT_MS = 30_000;
+exports.DEFAULT_MAX_RETRIES = 2;
+/** `downloadMedia` waits for a file being prepared at most this long. */
+exports.MEDIA_WAIT_MAX_MS = 60_000;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const invalidResponse = (what) => new errors_ts_1.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 (0, errors_ts_1.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 < constants_ts_1.DAILY_CAP_MIN || value > constants_ts_1.DAILY_CAP_MAX) {
+        throw (0, errors_ts_1.localError)('OPTIONS_INVALID', `${name} must be a whole number from ${constants_ts_1.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 (0, errors_ts_1.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 (0, refs_ts_1.requireNumberRef)(phone, 'phone');
+    if (!Array.isArray(phone))
+        throw (0, errors_ts_1.localError)('OPTIONS_INVALID', 'phone must be a string or an array of strings');
+    if (phone.length === 0)
+        throw (0, errors_ts_1.localError)('OPTIONS_INVALID', 'phone is an empty list; leave it out to use the whole project');
+    const refs = [...new Set(phone.map(ref => (0, refs_ts_1.requireNumberRef)(ref, 'phone')))];
+    if (refs.length > constants_ts_1.FROM_MAX)
+        throw (0, errors_ts_1.localError)('OPTIONS_INVALID', `A pool has at most ${constants_ts_1.FROM_MAX} numbers`);
+    return refs;
+};
+const waitMs = (wait) => wait === true ? constants_ts_1.WAIT_DEFAULT_MS : typeof wait === 'number' && Number.isFinite(wait) ? wait : 0;
+const defaultReport = (error) => {
+    console.error(`[whisp-sdk] ${error.name}: ${error.message}`);
+};
+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 ((0, runtime_ts_1.isBrowser)() && options.dangerouslyAllowBrowser !== true) {
+            throw (0, errors_ts_1.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 && !constants_ts_1.SEND_STRATEGIES.includes(options.strategy)) {
+            throw (0, errors_ts_1.localError)('OPTIONS_INVALID', "strategy must be 'healthiest', 'random' or 'round-robin'");
+        }
+        if (options.sticky !== undefined && typeof options.sticky !== 'boolean') {
+            throw (0, errors_ts_1.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 (0, errors_ts_1.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, exports.DEFAULT_TIMEOUT_MS, 'timeoutMs', 1, 600_000);
+        this.#maxRetries = positiveInt(options.maxRetries, exports.DEFAULT_MAX_RETRIES, 'maxRetries', 0, 10);
+        this.#timers = internal.timers ?? runtime_ts_1.realTimers;
+        const numbers = this.#scope.from === null ? null : [this.#scope.from].flat();
+        this.#listener = new listener_ts_1.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 = (0, refs_ts_1.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() || (0, runtime_ts_1.readEnv)(constants_ts_1.API_TOKEN_ENV);
+        if (!token) {
+            throw (0, errors_ts_1.localError)('TOKEN_MISSING', `No token: pass { token } or set ${constants_ts_1.API_TOKEN_ENV} (the project's API & SDK tab)`);
+        }
+        if (!constants_ts_1.TOKEN_PATTERN.test(token)) {
+            throw (0, errors_ts_1.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 ?? (0, runtime_ts_1.readEnv)(constants_ts_1.API_URL_ENV) ?? constants_ts_1.DEFAULT_BASE_URL;
+        return {
+            token,
+            baseUrl: checkBaseUrl(baseUrl, this.#options.baseUrl !== undefined ? 'baseUrl' : constants_ts_1.API_URL_ENV),
+            fetch: this.#fetch(),
+            userAgent: (0, runtime_ts_1.userAgent)(),
+        };
+    }
+    #transport() {
+        return {
+            ...this.#target(),
+            timeoutMs: this.#timeoutMs,
+            maxRetries: this.#maxRetries,
+            timers: this.#timers,
+            retrySignal: this.#retries.signal,
+        };
+    }
+    async #call(call) {
+        return (await (0, transport_ts_1.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 (0, errors_ts_1.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 errors_ts_1.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 ?? (0, runtime_ts_1.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 (0, errors_ts_1.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 (0, media_ts_1.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 (0, media_ts_1.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 (0, errors_ts_1.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 errors_ts_1.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 > exports.MEDIA_WAIT_MAX_MS)
+                    throw error;
+                await (0, runtime_ts_1.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 errors_ts_1.WhispError({ code: 'MEDIA_DOWNLOAD_FAILED', message: 'The file link could not be fetched', cause });
+        }
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => { });
+            throw new errors_ts_1.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 (0, errors_ts_1.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 (0, webhook_ts_1.verifyWebhook)(input);
+    }
+}
+exports.Whisp = Whisp;
+/** 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/cjs/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"];

package/dist/cjs/constants.js

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

package/dist/cjs/errors.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The SDK's errors (phase2-design 12.3, 12.5). Every one is a `WhispError`,
+ * so one `instanceof` check catches them all and `code` says what happened:
+ *
+ * - `WhispError`: the API answered with an error (`status` is the HTTP
+ *   status, `code` the API's stable code), or a local check failed before
+ *   anything was sent (`status` is null).
+ * - `WhispConnectionError`: no HTTP answer after every retry (network error
+ *   or timeout).
+ * - `WhispSignatureError`: `verifyWebhook` refused a request.
+ *
+ * Messages are English and safe to log: they never contain the token or a
+ * webhook secret.
+ */
+/** Codes the SDK makes itself. Everything else comes from the API as it sent it. */
+export declare const SDK_ERROR_CODES: {
+    /** No `token` was passed and WHISP_API_TOKEN is not set. Nothing was sent. */
+    readonly TOKEN_MISSING: 'TOKEN_MISSING';
+    /** The token isn't shaped like a project token (`wsp_live_…`). Nothing was sent. The API uses the same code. */
+    readonly TOKEN_INVALID: 'TOKEN_INVALID';
+    /** The SDK was created in a browser without `dangerouslyAllowBrowser`. The API uses the same code. */
+    readonly TOKEN_IN_BROWSER: 'TOKEN_IN_BROWSER';
+    /** A `phone` (or `number(...)`) that is neither a phone in international form nor a `num_` id. */
+    readonly PHONE_INVALID: 'PHONE_INVALID';
+    /** A read that needs one number (`chats`, `chat`, `chatMessages`, `check`) on a pool or whole-project instance. */
+    readonly NUMBER_REQUIRED: 'NUMBER_REQUIRED';
+    /** An option or argument the SDK can tell is wrong without asking the API (`baseUrl`, `timeoutMs`, ...). */
+    readonly OPTIONS_INVALID: 'OPTIONS_INVALID';
+    /** A file to send that can't be uploaded as given (no bytes, no type, too big). Nothing was sent. */
+    readonly MEDIA_INVALID: 'MEDIA_INVALID';
+    /** The presigned upload (the PUT to storage) failed. */
+    readonly UPLOAD_FAILED: 'UPLOAD_FAILED';
+    /** The signed file link answered an error (`downloadMedia`). */
+    readonly MEDIA_DOWNLOAD_FAILED: 'MEDIA_DOWNLOAD_FAILED';
+    /** A 2xx whose body wasn't what the API documents, or a redirect the SDK refused to follow. */
+    readonly INVALID_RESPONSE: 'INVALID_RESPONSE';
+    /** No HTTP answer: DNS, connection refused or reset, TLS. */
+    readonly NETWORK_ERROR: 'NETWORK_ERROR';
+    /** An attempt ran past `timeoutMs`, or the event stream sent nothing for 45 s. */
+    readonly TIMEOUT: 'TIMEOUT';
+    /** `verifyWebhook` got no secret (an unset env variable, usually). */
+    readonly SECRET_MISSING: 'SECRET_MISSING';
+    /** `verifyWebhook` got a secret that isn't a webhook signing secret (`wsp_whs_…`). */
+    readonly SECRET_INVALID: 'SECRET_INVALID';
+    /** `verifyWebhook` refused the request; `reason` says why. */
+    readonly SIGNATURE_INVALID: 'SIGNATURE_INVALID';
+    /** This runtime has no Web Crypto (`crypto.subtle`), which `verifyWebhook` needs. */
+    readonly CRYPTO_UNAVAILABLE: 'CRYPTO_UNAVAILABLE';
+};
+export type SdkErrorCode = (typeof SDK_ERROR_CODES)[keyof typeof SDK_ERROR_CODES];
+export type ErrorParams = Record<string, string | number>;
+export interface WhispErrorInit {
+    code: string;
+    message: string;
+    /** The HTTP status when the API answered; null for local checks and connection failures. */
+    status?: number | null;
+    params?: ErrorParams | null;
+    /** The API's `X-Request-Id`, for support. */
+    requestId?: string | null;
+    /** Seconds from `Retry-After`, when the API sent one. */
+    retryAfter?: number | null;
+    cause?: unknown;
+}
+export declare class WhispError extends Error {
+    readonly name: string;
+    /** Stable: `NUMBER_NOT_IN_PROJECT`, `RATE_LIMITED`, `TOKEN_MISSING`, ... */
+    readonly code: string;
+    /** The HTTP status when the API answered; null when nothing was answered. */
+    readonly status: number | null;
+    /** The values the code names (`number`, `total`, `reason`, ...), or null. */
+    readonly params: ErrorParams | null;
+    readonly requestId: string | null;
+    /** Seconds the API asked to wait (`Retry-After`), or null. */
+    readonly retryAfter: number | null;
+    constructor(init: WhispErrorInit);
+}
+/** No HTTP answer after every retry. `cause` is the runtime's own error. */
+export declare class WhispConnectionError extends WhispError {
+    readonly name: string;
+    constructor(code: 'NETWORK_ERROR' | 'TIMEOUT', message: string, cause?: unknown);
+}
+/** Why `verifyWebhook` refused a request (12.5). */
+export type SignatureFailureReason = 'missing' | 'malformed' | 'timestamp' | 'mismatch';
+export declare class WhispSignatureError extends WhispError {
+    readonly name: string;
+    readonly reason: SignatureFailureReason;
+    constructor(reason: SignatureFailureReason, message?: string);
+}
+/** `{ code, message, params? }` out of an API body (5.12), or null when it isn't one. */
+export declare const readApiError: (body: unknown) => {
+    code: string;
+    message: string;
+    params: ErrorParams | null;
+} | null;
+/** A local check failed; nothing was sent. */
+export declare const localError: (code: SdkErrorCode, message: string, params?: ErrorParams) => WhispError;