ab-ecosystem-cpass 1.0.0 → 1.0.6

package/dist/realtime/client.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxClient = void 0;
+const socket_io_client_1 = require("socket.io-client");
+const errors_1 = require("../errors");
+const DEFAULT_TIMEOUT = 20_000;
+/**
+ * The live-chat inbox over a socket.
+ *
+ * Requests are promises: each emit carries an acknowledgement callback, so two
+ * concurrent reads of different threads cannot be confused for one another. The
+ * server also emits replies under the request's own event name for older clients
+ * -- {@link InboxClient.on} sees those too, which is why a handler for
+ * `chat.action` receives both your own actions and other agents'.
+ *
+ * Credentials travel in `auth`, not in a header: a browser cannot set headers on
+ * a WebSocket upgrade, so a header-based handshake only works for as long as the
+ * connection stays on long-polling.
+ */
+class InboxClient {
+    options;
+    socket;
+    timeout;
+    /**
+     * The uploader this client was built with, if any.
+     *
+     * Read by `messages.sendMedia` when it is handed a file rather than a link.
+     */
+    get uploadMedia() {
+        return this.options.uploadMedia;
+    }
+    constructor(options) {
+        this.options = options;
+        if (!options.url)
+            throw new errors_1.CrmConfigError('An inbox socket url is required');
+        if (!options.clientId)
+            throw new errors_1.CrmConfigError('A clientId is required');
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.socket = (0, socket_io_client_1.io)(options.url, {
+            path: options.path ?? '/socket.io',
+            autoConnect: options.autoConnect ?? true,
+            transports: ['websocket', 'polling'],
+            auth: (cb) => {
+                void this.credentials().then(cb);
+            },
+            ...options.socketOptions,
+        });
+    }
+    /** Resolved per connect, so a reconnect never reuses an expired token. */
+    async credentials() {
+        const token = typeof this.options.token === 'function' ? await this.options.token() : this.options.token;
+        return { token, client_id: this.options.clientId };
+    }
+    /** The underlying socket, for lifecycle events and anything not wrapped here. */
+    get raw() {
+        return this.socket;
+    }
+    get connected() {
+        return this.socket.connected;
+    }
+    connect() {
+        this.socket.connect();
+        return this;
+    }
+    disconnect() {
+        this.socket.disconnect();
+        return this;
+    }
+    /** Resolves once connected, or rejects with the handshake's reason. */
+    ready() {
+        if (this.socket.connected)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const onConnect = () => {
+                this.socket.off('connect_error', onError);
+                resolve();
+            };
+            const onError = (err) => {
+                this.socket.off('connect', onConnect);
+                reject(new errors_1.CrmApiError(401, 'unauthorized', err.message));
+            };
+            this.socket.once('connect', onConnect);
+            this.socket.once('connect_error', onError);
+        });
+    }
+    /**
+     * Sends one request and waits for its answer.
+     *
+     * A refusal rejects with a {@link CrmApiError} carrying the same code and status
+     * the REST API would have returned, so one error path covers both transports.
+     */
+    request(event, payload) {
+        return new Promise((resolve, reject) => {
+            this.socket
+                .timeout(this.timeout)
+                .emit(event, payload, (err, ack) => {
+                if (err) {
+                    reject(new errors_1.CrmApiError(504, 'timeout', `${event} did not answer in ${this.timeout}ms`));
+                    return;
+                }
+                if (!ack?.ok) {
+                    const error = ack?.error;
+                    reject(new errors_1.CrmApiError(error?.status ?? 500, error?.code ?? 'internal_error', error?.message ?? `${event} failed`, error?.details));
+                    return;
+                }
+                resolve(ack.data);
+            });
+        });
+    }
+    /**
+     * Listens for a pushed event. Returns the unsubscribe function, so a component
+     * can tear its own listener down without knowing what else is attached.
+     */
+    on(event, handler) {
+        this.socket.on(event, handler);
+        return () => {
+            this.socket.off(event, handler);
+        };
+    }
+    /** Fires once, then unsubscribes. */
+    once(event, handler) {
+        this.socket.once(event, handler);
+    }
+}
+exports.InboxClient = InboxClient;
+//# sourceMappingURL=client.js.map

package/dist/realtime/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/realtime/client.ts"],"names":[],"mappings":";;;AAAA,uDAAmD;AACnD,sCAAwD;AAuCxD,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B;;;;;;;;;;;;GAYG;AACH,MAAa,WAAW;IAaO;IAZZ,MAAM,CAAS;IACf,OAAO,CAAS;IAEjC;;;;OAIG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;IAClC,CAAC;IAED,YAA6B,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;QACtD,IAAI,CAAC,OAAO,CAAC,GAAG;YAAE,MAAM,IAAI,uBAAc,CAAC,iCAAiC,CAAC,CAAC;QAC9E,IAAI,CAAC,OAAO,CAAC,QAAQ;YAAE,MAAM,IAAI,uBAAc,CAAC,wBAAwB,CAAC,CAAC;QAE1E,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,eAAe,CAAC;QAElD,IAAI,CAAC,MAAM,GAAG,IAAA,qBAAE,EAAC,OAAO,CAAC,GAAG,EAAE;YAC5B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,YAAY;YAClC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;YACxC,UAAU,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC;YACpC,IAAI,EAAE,CAAC,EAA2C,EAAE,EAAE;gBACpD,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnC,CAAC;YACD,GAAG,OAAO,CAAC,aAAa;SACzB,CAAC,CAAC;IACL,CAAC;IAED,0EAA0E;IAClE,KAAK,CAAC,WAAW;QACvB,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;QACzG,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACrD,CAAC;IAED,iFAAiF;IACjF,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;IAC/B,CAAC;IAED,OAAO;QACL,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,UAAU;QACR,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,uEAAuE;IACvE,KAAK;QACH,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS;YAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAEpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,SAAS,GAAG,GAAG,EAAE;gBACrB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;gBAC1C,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;YACF,MAAM,OAAO,GAAG,CAAC,GAAU,EAAE,EAAE;gBAC7B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;gBACtC,MAAM,CAAC,IAAI,oBAAW,CAAC,GAAG,EAAE,cAAc,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5D,CAAC,CAAC;YAEF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YACvC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,OAAO,CACL,KAAQ,EACR,OAAoC;QAEpC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,MAAM;iBACR,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;iBACrB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,GAAiB,EAAE,GAAyC,EAAE,EAAE;gBACrF,IAAI,GAAG,EAAE,CAAC;oBACR,MAAM,CAAC,IAAI,oBAAW,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,KAAK,sBAAsB,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC;oBACxF,OAAO;gBACT,CAAC;gBAED,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC;oBACb,MAAM,KAAK,GAAG,GAAG,EAAE,KAAK,CAAC;oBACzB,MAAM,CACJ,IAAI,oBAAW,CACb,KAAK,EAAE,MAAM,IAAI,GAAG,EACpB,KAAK,EAAE,IAAI,IAAI,gBAAgB,EAC/B,KAAK,EAAE,OAAO,IAAI,GAAG,KAAK,SAAS,EACnC,KAAK,EAAE,OAAO,CACf,CACF,CAAC;oBACF,OAAO;gBACT,CAAC;gBAED,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACpB,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,EAAE,CAA0B,KAAQ,EAAE,OAA0C;QAC9E,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,KAAe,EAAE,OAAuC,CAAC,CAAC;QACzE,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAe,EAAE,OAAuC,CAAC,CAAC;QAC5E,CAAC,CAAC;IACJ,CAAC;IAED,qCAAqC;IACrC,IAAI,CAA0B,KAAQ,EAAE,OAA0C;QAChF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAe,EAAE,OAAuC,CAAC,CAAC;IAC7E,CAAC;CACF;AA9HD,kCA8HC"}

package/dist/realtime/events.d.ts

@@ -0,0 +1,147 @@
+import type { AssignBotPayload, BulkTransferResult, Chat, ChatActionPayload, ChatActionResult, ChatList, ChatSession, CtwaReferral, DeleteMessagePayload, FetchMessagePayload, ListChatsPayload, Message, MessageDeleteResult, MessageStatusUpdate, RetryDownloadPayload, SendMessagePayload, UpdateChatPayload, UpdateChatResult } from '../types/inbox';
+/** What a rejected event sends back. The HTTP error body, field for field. */
+export interface InboxError {
+    /** The event that failed. */
+    event: string;
+    code: string;
+    message: string;
+    status: number;
+    details?: unknown;
+    requestId: string;
+}
+/** The acknowledgement a request-style event resolves with. */
+export type InboxAck<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: InboxError;
+};
+/**
+ * Every event the client sends, with its payload and what it answers.
+ *
+ * The server replies two ways, so both generations of client work: through the
+ * acknowledgement callback when one is passed, and by emitting the same event
+ * name back, which is what the original inbox listens for.
+ */
+export interface InboxRequests {
+    ping: {
+        payload: unknown;
+        result: unknown;
+    };
+    'contact.list': {
+        payload: ListChatsPayload;
+        result: ChatList;
+    };
+    'contact.fetch': {
+        payload: {
+            id: string;
+        };
+        result: Chat;
+    };
+    'contact.update': {
+        payload: UpdateChatPayload;
+        result: UpdateChatResult;
+    };
+    'contact.done': {
+        payload: {
+            id: string;
+            isEnded?: boolean;
+        };
+        result: ChatActionResult;
+    };
+    'contact.bot_assign': {
+        payload: AssignBotPayload;
+        result: {
+            success: boolean;
+            id: string;
+        };
+    };
+    'chat.action': {
+        payload: ChatActionPayload;
+        result: ChatActionResult | BulkTransferResult;
+    };
+    'message.list': {
+        payload: {
+            id: string;
+            limit?: number;
+            last_message_id?: string;
+        };
+        result: Message[];
+    };
+    'message.fetch': {
+        payload: FetchMessagePayload;
+        result: Message;
+    };
+    'message.send': {
+        payload: SendMessagePayload;
+        result: Message;
+    };
+    'message.delete': {
+        payload: DeleteMessagePayload;
+        result: MessageDeleteResult;
+    };
+    'message.retry_download': {
+        payload: RetryDownloadPayload;
+        result: Message;
+    };
+    'ctwa.list': {
+        payload: {
+            id: string;
+            limit?: number;
+        };
+        result: CtwaReferral[];
+    };
+    'chat_session.list': {
+        payload: {
+            id: string;
+            channel?: string;
+        };
+        result: ChatSession[];
+    };
+}
+export type InboxRequestName = keyof InboxRequests;
+/**
+ * Events the server pushes without being asked.
+ *
+ * `chat.action` and the `message.*` names appear here as well as in the request
+ * map on purpose: an archive performed by another agent arrives under the same
+ * name and shape as one you asked for, so a client needs only one handler per
+ * kind of change rather than one per cause.
+ */
+export interface InboxPushes {
+    /**
+     * A message arrived, or one that was sent now exists as a stored row.
+     *
+     * The second case is how an optimistic bubble is replaced: `message.send`
+     * answered with a queue id, and this carries the same message with the
+     * provider's real `message_id`.
+     */
+    'message.received': Message;
+    /**
+     * The same row as `message.received`, in the shape it is stored in.
+     *
+     * Kept because the inbox this replaced listened for one name, `message.send`,
+     * for both its own reply and the row that followed. New clients should use
+     * `message.received`, which is mapped; this one carries `_id` and `user` as the
+     * database holds them.
+     */
+    'message.send': Record<string, unknown>;
+    /** A delivery state moved: sent, delivered, read, failed. */
+    'message.status': MessageStatusUpdate;
+    /** A chat changed: unread count, assignment, automation, tags. */
+    'chat.action': ChatActionResult;
+    /**
+     * A contact wrote in for the first time, so a chat row appeared.
+     *
+     * The stored contact document, not a mapped `Chat` -- it comes from the service
+     * that created it.
+     */
+    'contact.received': Record<string, unknown>;
+    'message.delete': MessageDeleteResult;
+    'message.retry_download': Message;
+    'contact.done': ChatActionResult;
+    /** An event was refused. Carries the event name that failed. */
+    error: InboxError;
+}
+export type InboxPushName = keyof InboxPushes;

package/dist/realtime/events.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=events.js.map

package/dist/realtime/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/realtime/events.ts"],"names":[],"mappings":""}

package/dist/realtime/inbox.d.ts

@@ -0,0 +1,173 @@
+import type { AssignBotPayload, BulkTransferResult, Chat, ChatActionPayload, ChatActionResult, ChatBlockUpdate, ChatList, ChatSession, CtwaReferral, ListChatsPayload, Message, MessageDeleteResult, SendMediaPayload, SendMessagePayload, UpdateChatPayload, UpdateChatResult } from '../types/inbox';
+import { InboxClient, type InboxClientOptions } from './client';
+/** The chat list and the thirteen actions that change one. */
+export declare class InboxChats {
+    private readonly client;
+    constructor(client: InboxClient);
+    /**
+     * One page of the inbox, ordered by last activity.
+     *
+     * `contact.list` · scope `contacts:read`
+     *
+     * The reply's `filter` is the filter that was *applied* -- a team member
+     * without the unassigned permission asking for `all` is narrowed to `me` -- and
+     * `nextPage` is the cursor for the page after this one, or `null` at the end.
+     */
+    list(payload?: ListChatsPayload): Promise<ChatList>;
+    /**
+     * One chat, and a subscription to it: messages and state changes for this
+     * thread reach the socket from here on without asking again.
+     *
+     * `contact.fetch` · scope `contacts:read`
+     */
+    get(id: string): Promise<Chat>;
+    /** Any action, for callers holding a payload they built elsewhere. */
+    act(payload: ChatActionPayload): Promise<ChatActionResult | BulkTransferResult>;
+    /** Trashes the chat. It leaves every inbox view; the contact row stays. */
+    delete(chat: string): Promise<ChatActionResult>;
+    /** Assigns the chat to one member and flags it unread for them. */
+    transfer(chat: string, member: string): Promise<ChatActionResult>;
+    archive(chat: string): Promise<ChatActionResult>;
+    unarchive(chat: string): Promise<ChatActionResult>;
+    /** Flips one or more block flags. Flags left out keep their current value. */
+    block(chat: string, update: ChatBlockUpdate): Promise<ChatActionResult>;
+    /** Clears the unread counter and the by-hand unread flag. */
+    markAsRead(chat: string): Promise<ChatActionResult>;
+    markAsUnread(chat: string): Promise<ChatActionResult>;
+    /** Detaches the flow and holds automation for `chat_metadata.pause_duration`. */
+    pauseAutomation(chat: string): Promise<ChatActionResult>;
+    resumeAutomation(chat: string): Promise<ChatActionResult>;
+    /** Closes the chat and detaches the flow, leaving the assignment alone. */
+    close(chat: string): Promise<ChatActionResult>;
+    /** Marks the chat done, unassigns it and detaches the flow. */
+    done(chat: string, isEnded?: boolean): Promise<ChatActionResult>;
+    /** Re-arms the automation pause with a new duration, in seconds. */
+    pauseTimer(chat: string, duration: number): Promise<ChatActionResult>;
+    /** Replaces the chat's tags outright. */
+    updateTags(chat: string, tags: string[]): Promise<ChatActionResult>;
+    /**
+     * Moves every chat held by one member -- or the unassigned queue -- to another
+     * member or a team. Capped at 500 chats per call; each moved chat is broadcast
+     * individually as a `transfer`.
+     */
+    bulkTransfer(payload: Omit<Extract<ChatActionPayload, {
+        action: 'bulk_transfer';
+    }>, 'action'>): Promise<BulkTransferResult>;
+    /** The narrower action set, answering with the metadata alone. */
+    update(payload: UpdateChatPayload): Promise<UpdateChatResult>;
+    /**
+     * Attaches a flow to the chat, or hands the chat to the bot server to place.
+     *
+     * `contact.bot_assign` · scope `contacts:write`
+     */
+    assignBot(payload: AssignBotPayload): Promise<{
+        success: boolean;
+        id: string;
+    }>;
+    private single;
+}
+/** Reading, sending and removing messages in one thread. */
+export declare class InboxMessages {
+    private readonly client;
+    constructor(client: InboxClient);
+    /**
+     * One page of a thread, oldest-first, and a subscription to it.
+     *
+     * `message.list` · scope `messages:read`
+     *
+     * Pass the `id` of the oldest message you hold as `last_message_id` to walk
+     * backwards through the history.
+     */
+    list<C extends Message['content'] = Message['content']>(id: string, options?: {
+        limit?: number;
+        last_message_id?: string;
+    }): Promise<Message<C>[]>;
+    /** One message by its provider id -- a `wamid`, not the document id. */
+    get<C extends Message['content'] = Message['content']>(messageId: string): Promise<Message<C>>;
+    /**
+     * Sends a message and gets the bubble to draw back immediately.
+     *
+     * `message.send` · scope `messages:write`
+     *
+     * The returned message carries a queue id in `message_id`, not a provider id:
+     * nothing has been written yet. The stored row arrives moments later as a
+     * `message.received` push, with the provider's id in its place -- correlate on
+     * the queue id you got back here, not on the final `message_id`.
+     *
+     * Sending by hand also takes the conversation off its bot, which arrives as a
+     * `chat.action` with `action: 'pause_automation'`.
+     */
+    send<C extends Message['content'] = Message['content']>(payload: SendMessagePayload): Promise<Message<C>>;
+    /**
+     * Sends media, uploading it first if you hand over a file.
+     *
+     * `message.send` · scope `messages:write`
+     *
+     * Two ways in. With a `link` -- from `crm.inboxMedia.upload()`, or any publicly
+     * fetchable URL -- this is `send()` with the content assembled for you:
+     *
+     * ```ts
+     * const link = await crm.inboxMedia.upload(file, { kind: 'image' });
+     * await inbox.messages.sendMedia({ channel, contact, kind: 'image', link, caption: 'Your order' });
+     * ```
+     *
+     * With a `file`, it uploads and sends in one call -- which needs an uploader,
+     * because a socket cannot presign. Pass `uploadMedia` when constructing the
+     * `Inbox`:
+     *
+     * ```ts
+     * const inbox = new Inbox({ url, clientId, token, uploadMedia: crm.inboxMedia.upload.bind(crm.inboxMedia) });
+     * await inbox.messages.sendMedia({ channel, contact, kind: 'image', file, caption: 'Your order' });
+     * ```
+     *
+     * The link is what gets stored on the message, and it does not expire, so the
+     * thread still renders the media months later.
+     *
+     * `filename` is worth setting on a `document`: it is what the recipient sees in
+     * their chat, where a bare key would otherwise appear.
+     */
+    sendMedia<C extends Message['content'] = Message['content']>(payload: SendMediaPayload): Promise<Message<C>>;
+    /** Uploads a file through the hook the client was given, or explains its absence. */
+    private resolve;
+    /** Removes one message from a thread, for everyone with it open. */
+    delete(contactId: string, messageId: string): Promise<MessageDeleteResult>;
+    /**
+     * Re-fetches media whose first download failed. Inbound media only -- an
+     * outbound attachment was ours to begin with.
+     *
+     * `message.retry_download` · scope `messages:write`
+     */
+    retryDownload<C extends Message['content'] = Message['content']>(messageId: string): Promise<Message<C>>;
+}
+/**
+ * The live-chat inbox.
+ *
+ * ```ts
+ * const inbox = new Inbox({ url: 'https://inbox.example.com', clientId, token });
+ * await inbox.ready();
+ *
+ * const { contacts } = await inbox.chats.list({ filter: { assignment: 'me', unread: 'unread' } });
+ * inbox.on('message.received', (message) => append(message));
+ * ```
+ */
+export declare class Inbox extends InboxClient {
+    readonly chats: InboxChats;
+    readonly messages: InboxMessages;
+    constructor(options: InboxClientOptions);
+    /**
+     * Where a lead came from: the click-to-WhatsApp ad payloads on one contact.
+     *
+     * `ctwa.list` · scope `contacts:read`
+     */
+    referrals(contactId: string, limit?: number): Promise<CtwaReferral[]>;
+    /**
+     * A contact's reply windows, one per channel they have written from. Read these
+     * to tell whether a free-form reply is still allowed on a channel or whether
+     * the agent has to start from a template.
+     *
+     * `chat_session.list` · scope `contacts:read`
+     */
+    sessions(contactId: string, channel?: string): Promise<ChatSession[]>;
+    /** Round-trips the payload. Useful for checking the connection is live. */
+    ping<T>(payload: T): Promise<T>;
+}