whisp-js 0.1.0 → 0.3.1

package/dist/esm/client.js

@@ -14,6 +14,11 @@
  * 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';
@@ -80,6 +85,23 @@ const normalizeFrom = (phone) => {
         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}`);
@@ -253,7 +275,8 @@ export class Whisp {
         const cap = checkDailyCap(perCall, 'dailyCap') ?? this.#options.dailyCap;
         return cap === undefined ? {} : { dailyCap: cap };
     }
-    #common(options) {
+    /** 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;
@@ -261,6 +284,9 @@ export class Whisp {
             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) {
@@ -277,8 +303,8 @@ export class Whisp {
         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);
+        // 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 };
@@ -315,6 +341,90 @@ export class Whisp {
         }, 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() {

package/dist/esm/constants.d.ts

@@ -39,5 +39,5 @@ export declare const UPLOAD_MAX_BYTES: {
     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"];
+/** 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

@@ -39,7 +39,7 @@ export const UPLOAD_MAX_BYTES = {
     voice: 16 * 1024 * 1024,
     document: 100 * 1024 * 1024,
 };
-/** PLAN's twelve, in the order the API lists them. */
+/** 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',
@@ -53,4 +53,5 @@ export const PUBLIC_EVENT_TYPES = [
     'number.status',
     'number.risk',
     'call.received',
+    'message.edited',
 ];

package/dist/esm/index.d.ts

@@ -9,7 +9,7 @@
  *   await whisp.send('972521112233', 'Hello from Whisp')
  *   whisp.on('message', msg => console.log(msg.from, msg.text))
  */
-export { DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DownloadOptions, type MessagesQuery, type Page, type PageResult, type SendFileOptions, type SendOptions, type VerifyResult, Whisp, type WhispOptions, } from './client.js';
+export { DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT_MS, type DownloadOptions, type EditOptions, type MessagesQuery, type Page, type PageResult, type SendFileOptions, type SendOptions, type SendVoiceOptions, type VerifyResult, Whisp, type WhispOptions, } from './client.js';
 export { API_TOKEN_ENV, API_URL_ENV, DEFAULT_BASE_URL, EVENT_CURSOR_PREFIX, PUBLIC_EVENT_TYPES, SDK_PACKAGE_NAME, SIGNATURE_HEADER, SIGNATURE_TOLERANCE_SECONDS, TOKEN_PREFIX, USER_AGENT_PREFIX, WEBHOOK_SECRET_PREFIX, } from './constants.js';
 export { type ErrorParams, SDK_ERROR_CODES, type SdkErrorCode, type SignatureFailureReason, WhispConnectionError, WhispError, WhispSignatureError, } from './errors.js';
 export type { AnyListenerEvent, EventHandlers, EventMeta, ListenerEvent, ListenerName, StreamClose, StreamGap, } from './listener.js';

package/dist/esm/listener.d.ts

@@ -28,7 +28,7 @@ export type ListenerEvent<T extends PublicEventType> = Omit<EventData[T], 'numbe
     numberId: string;
     event: EventMeta<T>;
 };
-/** Any of the twelve; `event.event.type` says which. */
+/** Any of the public types; `event.event.type` says which. */
 export type AnyListenerEvent = {
     [T in PublicEventType]: ListenerEvent<T>;
 }[PublicEventType];
@@ -51,7 +51,7 @@ export type EventHandlers = {
 } & {
     /** `message.received`. */
     message: Handler<ListenerEvent<'message.received'>>;
-    /** Every one of the twelve types. */
+    /** Every one of the public types. */
     '*': Handler<AnyListenerEvent>;
     /** A connection reached `ready`. */
     open: Handler<StreamReady>;

package/dist/esm/listener.js

@@ -24,6 +24,7 @@
  *   `'error'` and the stream goes on. The cursor moves when an event's
  *   handlers have settled, and at once for an event nobody listens to.
  */
+import { PUBLIC_EVENT_TYPES } from './constants.js';
 import { localError, readApiError, WhispConnectionError, WhispError } from './errors.js';
 import { sleep } from './runtime.js';
 import { createSseParser } from './sse.js';
@@ -35,20 +36,8 @@ export const WATCHDOG_MS = 45_000;
 /** The wait after a 429 (TOO_MANY_STREAMS or RATE_LIMITED), unless `Retry-After` asks for longer (up to a minute). */
 export const RATE_LIMITED_WAIT_MS = 30_000;
 const RATE_LIMITED_MAX_WAIT_MS = 60_000;
-const KNOWN_TYPES = new Set([
-    'message.received',
-    'message.sent',
-    'message.status',
-    'message.reaction',
-    'message.deleted',
-    'chat.updated',
-    'presence.updated',
-    'group.updated',
-    'group.participants',
-    'number.status',
-    'number.risk',
-    'call.received',
-]);
+/** The types this version delivers; any other is skipped (its cursor still moves). */
+const KNOWN_TYPES = new Set(PUBLIC_EVENT_TYPES);
 const LIFECYCLE = new Set(['open', 'close', 'gap', 'error']);
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const asError = (value) => (value instanceof Error ? value : new Error(String(value)));

package/dist/esm/types.d.ts

@@ -34,8 +34,12 @@ export type ChatChange = 'unread' | 'done' | 'pinned' | 'assignee' | 'labels' |
 export type CursorRejection = 'cursor_unknown' | 'cursor_expired';
 /** Every message type but the inbox's own `waiting` stubs and `system` lines. */
 export type MessageType = 'text' | 'image' | 'video' | 'audio' | 'voice' | 'document' | 'sticker' | 'location' | 'contact' | 'poll' | 'unsupported';
-/** PLAN's twelve public event types (6.1). */
-export type PublicEventType = 'message.received' | 'message.sent' | 'message.status' | 'message.reaction' | 'message.deleted' | 'chat.updated' | 'presence.updated' | 'group.updated' | 'group.participants' | 'number.status' | 'number.risk' | 'call.received';
+/** PLAN's twelve public event types (6.1), then `message.edited` (0.3.0). */
+export type PublicEventType = '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';
+/** What marking a chat read did about read receipts: handed to the server (not delivery), off, or nothing unread. */
+export type ReadReceiptOutcome = 'queued' | 'off' | 'none';
+/** What startTyping shows: `composing` ("typing...") or `recording` ("recording audio..."). */
+export type TypingStartState = 'composing' | 'recording';
 /** Someone on WhatsApp. `phone` is null for a LID-only contact. */
 export type Actor = {
     phone: string | null;
@@ -179,6 +183,11 @@ export type Message = {
     at: string;
     editedAt: string | null;
     deletedAt: string | null;
+    /**
+     * The people the text mentions, in order (0.3.0); `@` and the digits of their `phone` or `lid` mark each in
+     * `text`. Empty for none and for a deleted message.
+     */
+    mentions: Actor[];
 };
 /** The number an event happened on. */
 export type EventNumber = {
@@ -216,6 +225,19 @@ export type MessageDeletedData = {
     reference: string | null;
     at: string;
 };
+/** A message's text or caption changed, by its sender or by us (0.3.0). `at` is the edit's own time. */
+export type MessageEditedData = {
+    messageId: string;
+    waId: string | null;
+    chatId: string;
+    fromMe: boolean;
+    /** The new text or caption. */
+    text: string | null;
+    /** The message's mentions after the edit. */
+    mentions: Actor[];
+    reference: string | null;
+    at: string;
+};
 export type ChatUpdatedData = {
     chat: Chat;
     changes: ChatChange[];
@@ -308,6 +330,7 @@ export type EventData = {
     'number.status': NumberStatusData;
     'number.risk': NumberRiskData;
     'call.received': CallReceivedData;
+    'message.edited': MessageEditedData;
 };
 /** The envelope: the SSE `data:`, an item of `GET /events` and a webhook body are this same object. */
 export type EventOf<T extends PublicEventType> = {
@@ -370,6 +393,7 @@ export type SendMessageBody = {
     dailyCap?: number;
     type?: 'text';
     text: string;
+    mentions?: string[];
     from?: string | string[];
     strategy?: SendStrategy;
     sticky?: boolean;
@@ -382,6 +406,7 @@ export type SendMessageBody = {
     type: 'image' | 'video' | 'document';
     media: MediaInput;
     caption?: string;
+    mentions?: string[];
     from?: string | string[];
     strategy?: SendStrategy;
     sticky?: boolean;
@@ -406,6 +431,7 @@ export type SendFromNumberBody = {
     dailyCap?: number;
     type?: 'text';
     text: string;
+    mentions?: string[];
 } | {
     to: string;
     replyTo?: string;
@@ -415,6 +441,7 @@ export type SendFromNumberBody = {
     type: 'image' | 'video' | 'document';
     media: MediaInput;
     caption?: string;
+    mentions?: string[];
 } | {
     to: string;
     replyTo?: string;
@@ -434,6 +461,7 @@ export type SendMediaFromNumberBody = {
     type: 'image' | 'video' | 'document';
     media: MediaInput;
     caption?: string;
+    mentions?: string[];
 } | {
     to: string;
     replyTo?: string;
@@ -508,6 +536,45 @@ export type Upload = {
     headers: Record<string, string>;
     expiresAt: string;
 };
+/** `POST /messages/:messageId/reaction`: one emoji, or `''` to remove ours. */
+export type ReactionBody = {
+    emoji: string;
+};
+/**
+ * `POST /messages/:messageId/edit`: the new text or caption. `mentions` (phones or `<digits>@lid` JIDs, each
+ * written `@<digits>` in the text) replaces the message's; left out, the ones still named in the text are kept.
+ */
+export type EditMessageBody = {
+    text: string;
+    mentions?: string[];
+};
+/** 202 for a reaction: queued for the number's socket. */
+export type ActionAccepted = {
+    accepted: true;
+};
+/** `POST /numbers/:number/chats/:chat/read`: the chat as it is now, and what happened to read receipts. */
+export type MarkReadResult = {
+    chat: Chat;
+    readReceipts: ReadReceiptOutcome;
+};
+/** `POST /numbers/:number/chats/:chat/typing`: `composing` when left out. */
+export type StartTypingBody = {
+    state?: TypingStartState;
+};
+/** startTyping's options. */
+export interface TypingOptions {
+    /** `composing` (the default): "typing...". `recording`: "recording audio...". */
+    state?: TypingStartState;
+}
+/**
+ * 202 from both typing routes: the state asked for (`paused` for a stop), and when the server stops refreshing it
+ * at the latest (2 minutes after this start). Null for a stop, and while the server's worker is an older build that
+ * shows typing once, with no keep-alive.
+ */
+export type TypingResult = {
+    state: TypingStartState | 'paused';
+    keptUntil: string | null;
+};
 /** Every error the API answers. `code` is stable; `params` carries the values it names. */
 export type ApiError = {
     code: string;

package/dist/esm/version.d.ts

@@ -1,2 +1,2 @@
 /** The package's version: sent in the User-Agent. packages/sdk/test/constants.test.ts keeps it equal to package.json's. */
-export declare const SDK_VERSION = "0.1.0";
+export declare const SDK_VERSION = "0.3.1";

package/dist/esm/version.js

@@ -1,2 +1,2 @@
 /** The package's version: sent in the User-Agent. packages/sdk/test/constants.test.ts keeps it equal to package.json's. */
-export const SDK_VERSION = '0.1.0';
+export const SDK_VERSION = '0.3.1';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "whisp-js",
-	"version": "0.1.0",
+	"version": "0.3.1",
 	"description": "Send WhatsApp messages from your numbers and listen to their events",
 	"license": "MIT",
 	"type": "module",