whisp-js 0.0.0-stage → 0.3.0

package/dist/cjs/client.d.ts

@@ -0,0 +1,213 @@
+import { type EventHandlers } from './listener.js';
+import { type MediaSource } from './media.js';
+import { type Timers } from './runtime.js';
+import type { Chat, ChatListQuery, ChatMessagesQuery, MarkReadResult, Message, PhoneCheck, ProjectInfo, PublicEventType, SendMessageBody, SendStrategy, TypingOptions, TypingResult, 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;
+    /**
+     * Phones or `<digits>@lid` JIDs to mention (0.3.0), each written `@<digits>` in the text or caption. Groups
+     * only; at most 50.
+     */
+    mentions?: string[];
+}
+export interface SendFileOptions extends SendOptions {
+    caption?: string;
+}
+/** A voice note has no text to carry `@<digits>`, so it takes no `mentions`. */
+export type SendVoiceOptions = Omit<SendOptions, 'mentions'>;
+export interface EditOptions {
+    /**
+     * Replaces the message's mentions (phones or `<digits>@lid` JIDs, each written `@<digits>` in `text`). Left
+     * out, the mentions still named in the new text are kept.
+     */
+    mentions?: 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?: SendVoiceOptions): 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>;
+    /**
+     * 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.
+     */
+    react(message: Message | string, emoji: string): Promise<void>;
+    /** Removes this number's reaction to a message. */
+    unreact(message: Message | string): Promise<void>;
+    /**
+     * 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.
+     */
+    edit(message: Message | string, text: string, options?: EditOptions): Promise<Message>;
+    /**
+     * 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.
+     */
+    revoke(message: Message | string): Promise<Message>;
+    /**
+     * 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).
+     */
+    markRead(chat: string): Promise<MarkReadResult>;
+    /**
+     * 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).
+     */
+    startTyping(chat: string, options?: TypingOptions): Promise<TypingResult>;
+    /** Stops this number's typing in a chat at once ("paused"). Safe to call when nothing is typing. */
+    stopTyping(chat: string): Promise<void>;
+    /** 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 public
+     * 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>;
+}