whisp-js 0.0.0-stage → 0.1.0

package/dist/cjs/errors.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.localError = exports.readApiError = exports.WhispSignatureError = exports.WhispConnectionError = exports.WhispError = exports.SDK_ERROR_CODES = void 0;
+/** Codes the SDK makes itself. Everything else comes from the API as it sent it. */
+exports.SDK_ERROR_CODES = {
+    /** No `token` was passed and WHISP_API_TOKEN is not set. Nothing was sent. */
+    TOKEN_MISSING: 'TOKEN_MISSING',
+    /** The token isn't shaped like a project token (`wsp_live_…`). Nothing was sent. The API uses the same code. */
+    TOKEN_INVALID: 'TOKEN_INVALID',
+    /** The SDK was created in a browser without `dangerouslyAllowBrowser`. The API uses the same code. */
+    TOKEN_IN_BROWSER: 'TOKEN_IN_BROWSER',
+    /** A `phone` (or `number(...)`) that is neither a phone in international form nor a `num_` id. */
+    PHONE_INVALID: 'PHONE_INVALID',
+    /** A read that needs one number (`chats`, `chat`, `chatMessages`, `check`) on a pool or whole-project instance. */
+    NUMBER_REQUIRED: 'NUMBER_REQUIRED',
+    /** An option or argument the SDK can tell is wrong without asking the API (`baseUrl`, `timeoutMs`, ...). */
+    OPTIONS_INVALID: 'OPTIONS_INVALID',
+    /** A file to send that can't be uploaded as given (no bytes, no type, too big). Nothing was sent. */
+    MEDIA_INVALID: 'MEDIA_INVALID',
+    /** The presigned upload (the PUT to storage) failed. */
+    UPLOAD_FAILED: 'UPLOAD_FAILED',
+    /** The signed file link answered an error (`downloadMedia`). */
+    MEDIA_DOWNLOAD_FAILED: 'MEDIA_DOWNLOAD_FAILED',
+    /** A 2xx whose body wasn't what the API documents, or a redirect the SDK refused to follow. */
+    INVALID_RESPONSE: 'INVALID_RESPONSE',
+    /** No HTTP answer: DNS, connection refused or reset, TLS. */
+    NETWORK_ERROR: 'NETWORK_ERROR',
+    /** An attempt ran past `timeoutMs`, or the event stream sent nothing for 45 s. */
+    TIMEOUT: 'TIMEOUT',
+    /** `verifyWebhook` got no secret (an unset env variable, usually). */
+    SECRET_MISSING: 'SECRET_MISSING',
+    /** `verifyWebhook` got a secret that isn't a webhook signing secret (`wsp_whs_…`). */
+    SECRET_INVALID: 'SECRET_INVALID',
+    /** `verifyWebhook` refused the request; `reason` says why. */
+    SIGNATURE_INVALID: 'SIGNATURE_INVALID',
+    /** This runtime has no Web Crypto (`crypto.subtle`), which `verifyWebhook` needs. */
+    CRYPTO_UNAVAILABLE: 'CRYPTO_UNAVAILABLE',
+};
+class WhispError extends Error {
+    name = 'WhispError';
+    /** Stable: `NUMBER_NOT_IN_PROJECT`, `RATE_LIMITED`, `TOKEN_MISSING`, ... */
+    code;
+    /** The HTTP status when the API answered; null when nothing was answered. */
+    status;
+    /** The values the code names (`number`, `total`, `reason`, ...), or null. */
+    params;
+    requestId;
+    /** Seconds the API asked to wait (`Retry-After`), or null. */
+    retryAfter;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.code = init.code;
+        this.status = init.status ?? null;
+        this.params = init.params ?? null;
+        this.requestId = init.requestId ?? null;
+        this.retryAfter = init.retryAfter ?? null;
+    }
+}
+exports.WhispError = WhispError;
+/** No HTTP answer after every retry. `cause` is the runtime's own error. */
+class WhispConnectionError extends WhispError {
+    name = 'WhispConnectionError';
+    constructor(code, message, cause) {
+        super({ code, message, cause });
+    }
+}
+exports.WhispConnectionError = WhispConnectionError;
+const SIGNATURE_MESSAGES = {
+    missing: 'The request has no X-Whisp-Signature header',
+    malformed: 'The X-Whisp-Signature header or the body is not in the expected format',
+    timestamp: "The signature's timestamp is outside the tolerance (an old or replayed request, or a wrong clock)",
+    mismatch: 'No signature matches the body with this secret (a changed body, another secret, or a parsed body)',
+};
+class WhispSignatureError extends WhispError {
+    name = 'WhispSignatureError';
+    reason;
+    constructor(reason, message = SIGNATURE_MESSAGES[reason]) {
+        super({ code: exports.SDK_ERROR_CODES.SIGNATURE_INVALID, message, params: { reason } });
+        this.reason = reason;
+    }
+}
+exports.WhispSignatureError = WhispSignatureError;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** `{ code, message, params? }` out of an API body (5.12), or null when it isn't one. */
+const readApiError = (body) => {
+    if (!isRecord(body) || typeof body.code !== 'string' || typeof body.message !== 'string')
+        return null;
+    let params = null;
+    if (isRecord(body.params)) {
+        params = {};
+        for (const [key, value] of Object.entries(body.params)) {
+            if (typeof value === 'string' || typeof value === 'number')
+                params[key] = value;
+        }
+    }
+    return { code: body.code, message: body.message, params };
+};
+exports.readApiError = readApiError;
+/** A local check failed; nothing was sent. */
+const localError = (code, message, params) => new WhispError({ code, message, params: params ?? null });
+exports.localError = localError;

package/dist/cjs/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Whisp SDK (phase2-design 12): send WhatsApp messages from your
+ * project's numbers, read their chats, listen to their events, and check
+ * webhook signatures, from Node 22.12+ or Bun. Zero runtime dependencies:
+ * `fetch`, Web Streams and Web Crypto only.
+ *
+ *   import { Whisp } from 'whisp-js'
+ *   const whisp = new Whisp({ phone: '972501234567' }) // WHISP_API_TOKEN from the environment
+ *   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 { 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';
+export type { MediaFile, MediaSource, MediaUrl } from './media.js';
+export type * from './types.js';
+export { SDK_VERSION } from './version.js';
+export { type VerifyWebhookInput, verifyWebhook } from './webhook.js';

package/dist/cjs/index.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhook = exports.SDK_VERSION = exports.WhispSignatureError = exports.WhispError = exports.WhispConnectionError = exports.SDK_ERROR_CODES = exports.WEBHOOK_SECRET_PREFIX = exports.USER_AGENT_PREFIX = exports.TOKEN_PREFIX = exports.SIGNATURE_TOLERANCE_SECONDS = exports.SIGNATURE_HEADER = exports.SDK_PACKAGE_NAME = exports.PUBLIC_EVENT_TYPES = exports.EVENT_CURSOR_PREFIX = exports.DEFAULT_BASE_URL = exports.API_URL_ENV = exports.API_TOKEN_ENV = exports.Whisp = exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_MAX_RETRIES = void 0;
+/**
+ * The Whisp SDK (phase2-design 12): send WhatsApp messages from your
+ * project's numbers, read their chats, listen to their events, and check
+ * webhook signatures, from Node 22.12+ or Bun. Zero runtime dependencies:
+ * `fetch`, Web Streams and Web Crypto only.
+ *
+ *   import { Whisp } from 'whisp-js'
+ *   const whisp = new Whisp({ phone: '972501234567' }) // WHISP_API_TOKEN from the environment
+ *   await whisp.send('972521112233', 'Hello from Whisp')
+ *   whisp.on('message', msg => console.log(msg.from, msg.text))
+ */
+var client_ts_1 = require("./client.js");
+Object.defineProperty(exports, "DEFAULT_MAX_RETRIES", { enumerable: true, get: function () { return client_ts_1.DEFAULT_MAX_RETRIES; } });
+Object.defineProperty(exports, "DEFAULT_TIMEOUT_MS", { enumerable: true, get: function () { return client_ts_1.DEFAULT_TIMEOUT_MS; } });
+Object.defineProperty(exports, "Whisp", { enumerable: true, get: function () { return client_ts_1.Whisp; } });
+var constants_ts_1 = require("./constants.js");
+Object.defineProperty(exports, "API_TOKEN_ENV", { enumerable: true, get: function () { return constants_ts_1.API_TOKEN_ENV; } });
+Object.defineProperty(exports, "API_URL_ENV", { enumerable: true, get: function () { return constants_ts_1.API_URL_ENV; } });
+Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return constants_ts_1.DEFAULT_BASE_URL; } });
+Object.defineProperty(exports, "EVENT_CURSOR_PREFIX", { enumerable: true, get: function () { return constants_ts_1.EVENT_CURSOR_PREFIX; } });
+Object.defineProperty(exports, "PUBLIC_EVENT_TYPES", { enumerable: true, get: function () { return constants_ts_1.PUBLIC_EVENT_TYPES; } });
+Object.defineProperty(exports, "SDK_PACKAGE_NAME", { enumerable: true, get: function () { return constants_ts_1.SDK_PACKAGE_NAME; } });
+Object.defineProperty(exports, "SIGNATURE_HEADER", { enumerable: true, get: function () { return constants_ts_1.SIGNATURE_HEADER; } });
+Object.defineProperty(exports, "SIGNATURE_TOLERANCE_SECONDS", { enumerable: true, get: function () { return constants_ts_1.SIGNATURE_TOLERANCE_SECONDS; } });
+Object.defineProperty(exports, "TOKEN_PREFIX", { enumerable: true, get: function () { return constants_ts_1.TOKEN_PREFIX; } });
+Object.defineProperty(exports, "USER_AGENT_PREFIX", { enumerable: true, get: function () { return constants_ts_1.USER_AGENT_PREFIX; } });
+Object.defineProperty(exports, "WEBHOOK_SECRET_PREFIX", { enumerable: true, get: function () { return constants_ts_1.WEBHOOK_SECRET_PREFIX; } });
+var errors_ts_1 = require("./errors.js");
+Object.defineProperty(exports, "SDK_ERROR_CODES", { enumerable: true, get: function () { return errors_ts_1.SDK_ERROR_CODES; } });
+Object.defineProperty(exports, "WhispConnectionError", { enumerable: true, get: function () { return errors_ts_1.WhispConnectionError; } });
+Object.defineProperty(exports, "WhispError", { enumerable: true, get: function () { return errors_ts_1.WhispError; } });
+Object.defineProperty(exports, "WhispSignatureError", { enumerable: true, get: function () { return errors_ts_1.WhispSignatureError; } });
+var version_ts_1 = require("./version.js");
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return version_ts_1.SDK_VERSION; } });
+var webhook_ts_1 = require("./webhook.js");
+Object.defineProperty(exports, "verifyWebhook", { enumerable: true, get: function () { return webhook_ts_1.verifyWebhook; } });

package/dist/cjs/listener.d.ts

@@ -0,0 +1,93 @@
+import { type Timers } from './runtime.js';
+import { type FetchLike } from './transport.js';
+import type { CursorRejection, EventData, PublicEvent, PublicEventType, StreamReady } from './types.js';
+/** Wait before reconnect attempt N (0-based); the last value repeats. */
+export declare const RECONNECT_DELAYS_MS: readonly [1000, 2000, 4000, 8000, 15000];
+/** No byte for this long and the connection is dropped (the server pings every 20 s). */
+export declare const WATCHDOG_MS = 45000;
+/** The wait after a 429 (TOO_MANY_STREAMS or RATE_LIMITED), unless `Retry-After` asks for longer (up to a minute). */
+export declare const RATE_LIMITED_WAIT_MS = 30000;
+/** Where the event came from, for logging and dedupe: `id` is the dedupe key, `cursor` the resume point. */
+export interface EventMeta<T extends PublicEventType = PublicEventType> {
+    /** The event id (`evt_…`): the same event can arrive twice across a restart, never with another id. */
+    id: string;
+    type: T;
+    /** When the change committed. */
+    createdAt: string;
+    /** Save it and pass it as `cursor` to resume after this event. */
+    cursor: string;
+}
+/**
+ * What a handler gets (12.4): the event's `data` with the envelope folded in,
+ * so `msg.from`, `msg.text` and `msg.number` read directly, and
+ * `e.number`, `e.status` for `number.status`. `number` is the Whisp number's
+ * phone, `numberId` its id.
+ */
+export type ListenerEvent<T extends PublicEventType> = Omit<EventData[T], 'number' | 'numberId' | 'event'> & {
+    number: string;
+    numberId: string;
+    event: EventMeta<T>;
+};
+/** Any of the twelve; `event.event.type` says which. */
+export type AnyListenerEvent = {
+    [T in PublicEventType]: ListenerEvent<T>;
+}[PublicEventType];
+/** `'gap'`: a resume was asked and the server couldn't honour it; reconcile with reads. */
+export interface StreamGap {
+    reason: CursorRejection;
+    /** The cursor that was sent. */
+    cursor: string;
+}
+/** `'close'`: a connection ended. `reconnect` is false once the listener has stopped. */
+export interface StreamClose {
+    reconnect: boolean;
+    /** Why it ended, when it wasn't `close()`. */
+    error?: Error;
+}
+export type Handler<A> = (arg: A) => unknown;
+/** Every name `on()` takes and what its handler receives. */
+export type EventHandlers = {
+    [T in PublicEventType]: Handler<ListenerEvent<T>>;
+} & {
+    /** `message.received`. */
+    message: Handler<ListenerEvent<'message.received'>>;
+    /** Every one of the twelve types. */
+    '*': Handler<AnyListenerEvent>;
+    /** A connection reached `ready`. */
+    open: Handler<StreamReady>;
+    close: Handler<StreamClose>;
+    gap: Handler<StreamGap>;
+    /** A handler threw (with the event it was given), the server sent `error`, or the listener stopped for good. */
+    error: (error: Error, event?: AnyListenerEvent) => unknown;
+};
+export type ListenerName = keyof EventHandlers;
+export interface StreamTarget {
+    baseUrl: string;
+    token: string;
+    fetch: FetchLike;
+    userAgent: string;
+}
+export interface ListenerConfig {
+    /** The connection's target, resolved per connection; throws a WhispError (TOKEN_MISSING) to stop. */
+    resolve: () => StreamTarget;
+    /** The instance's numbers (`numbers=`), or null for the whole project. */
+    numbers: readonly string[] | null;
+    cursor: string | null;
+    /** How long to wait for the answer's headers. */
+    connectTimeoutMs: number;
+    timers: Timers;
+    /** Where an error goes when nobody listens to `'error'`. */
+    report: (error: Error) => void;
+}
+/** The handler's argument: `data` plus the envelope (12.4). */
+export declare const toListenerEvent: (envelope: PublicEvent, cursor: string) => AnyListenerEvent;
+export declare class Listener {
+    #private;
+    constructor(config: ListenerConfig);
+    get cursor(): string | null;
+    get running(): boolean;
+    add(name: string, handler: Handler<never>): void;
+    remove(name: string, handler: Handler<never>): void;
+    /** Ends the stream and its reconnects, and forgets every handler; a later `on()` starts again from the cursor. */
+    close(): void;
+}