@ezychat/wa 0.1.56 → 0.1.57

package/dist/fake/fake-adapter.d.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import type { WaStatus } from '@ezychat/shared';
-import { type SendResult, type WaAdapter, type WaAdapterEvents, type WaContactAlias, type WaGroupInfo, type WaIncomingMessage, type WaReaction, type WaReactionTarget, type WaSendFile, type WaSendOptions } from '../types.js';
+import { type SendResult, type WaAdapter, type WaAdapterEvents, type WaCapabilities, type WaContactAlias, type WaGroupInfo, type WaIncomingMessage, type WaReaction, type WaReactionTarget, type WaSendFile, type WaSendOptions, type WaTemplate, type WaTemplateSend } from '../types.js';
 export interface FakeSentRecord {
     chatJid: string;
     text?: string;
@@ -44,11 +44,29 @@ export declare class FakeWaAdapter extends EventEmitter implements WaAdapter {
         chatJid: string;
         presence: 'composing' | 'paused';
     }>;
+    /** Every template sent (adapters given `templates`). */
+    readonly templateSends: Array<{
+        chatJid: string;
+        template: WaTemplateSend;
+        id: string;
+    }>;
+    /** What this fake connection can do; absent (a linked phone) unless given. */
+    readonly capabilities?: WaCapabilities;
+    /** Set when `templates` is given: the approved templates (offline → WaUnavailableError). */
+    readonly listTemplates?: () => Promise<WaTemplate[]>;
+    /** Set when `templates` is given: records the send like `sendText`. */
+    readonly sendTemplate?: (chatJid: string, template: WaTemplateSend) => Promise<SendResult>;
+    /** The templates `listTemplates` answers (tests may change them). */
+    templates: WaTemplate[];
+    /** Number of listTemplates calls, for tests that check caching. */
+    templateListCalls: number;
     /**
      * `me`: the linked account (default the fake number 60000000000); `idPrefix`: start of every
      * message id (default `FAKE`), so adapters of different inboxes never share an id.
      * `awaitScan`: a phone that was never linked — `connect()` shows a QR code and stays there
      * until `setConnected(true)` (the dev stand-in for the scan).
+     * `capabilities`: what the connection reports (e.g. a Business API stand-in); `templates`: its
+     * approved templates, which also turn on `listTemplates`/`sendTemplate`.
      */
     constructor(opts?: {
         autoOpen?: boolean;
@@ -58,6 +76,8 @@ export declare class FakeWaAdapter extends EventEmitter implements WaAdapter {
         };
         idPrefix?: string;
         awaitScan?: boolean;
+        capabilities?: WaCapabilities;
+        templates?: WaTemplate[];
     });
     get status(): WaStatus;
     on<K extends keyof WaAdapterEvents>(ev: K, fn: (...a: WaAdapterEvents[K]) => void): this;

package/dist/fake/fake-adapter.js

@@ -26,14 +26,49 @@ export class FakeWaAdapter extends EventEmitter {
     reactions = [];
     reads = [];
     presences = [];
+    /** Every template sent (adapters given `templates`). */
+    templateSends = [];
+    /** What this fake connection can do; absent (a linked phone) unless given. */
+    capabilities;
+    /** Set when `templates` is given: the approved templates (offline → WaUnavailableError). */
+    listTemplates;
+    /** Set when `templates` is given: records the send like `sendText`. */
+    sendTemplate;
+    /** The templates `listTemplates` answers (tests may change them). */
+    templates = [];
+    /** Number of listTemplates calls, for tests that check caching. */
+    templateListCalls = 0;
     /**
      * `me`: the linked account (default the fake number 60000000000); `idPrefix`: start of every
      * message id (default `FAKE`), so adapters of different inboxes never share an id.
      * `awaitScan`: a phone that was never linked — `connect()` shows a QR code and stays there
      * until `setConnected(true)` (the dev stand-in for the scan).
+     * `capabilities`: what the connection reports (e.g. a Business API stand-in); `templates`: its
+     * approved templates, which also turn on `listTemplates`/`sendTemplate`.
      */
     constructor(opts) {
         super();
+        if (opts?.capabilities)
+            this.capabilities = { ...opts.capabilities };
+        if (opts?.templates) {
+            this.templates = opts.templates.map((t) => ({ ...t, examples: [...t.examples] }));
+            this.listTemplates = async () => {
+                if (this._status.state !== 'open')
+                    throw new WaUnavailableError();
+                this.templateListCalls++;
+                return this.templates.map((t) => ({ ...t, examples: [...t.examples] }));
+            };
+            this.sendTemplate = async (chatJid, template) => {
+                this.beforeSend();
+                const id = `${this.idPrefix}-OUT-${FAKE_RUN}-${++this.outCounter}`;
+                this.templateSends.push({
+                    chatJid,
+                    template: { ...template, params: [...template.params] },
+                    id,
+                });
+                return this.afterSend(chatJid, id);
+            };
+        }
         this.autoOpen = opts?.autoOpen ?? true;
         this.awaitScan = opts?.awaitScan ?? false;
         this.me = { ...(opts?.me ?? FAKE_ME) };

package/dist/types.d.ts

@@ -159,8 +159,57 @@ export interface WaSendFile {
         waveform: Uint8Array;
     };
 }
+/**
+ * What a connection type can do, so the core shows only what works (never by type name). An adapter
+ * without `capabilities` is a linked phone: QR/pairing, history import, groups, no reply window.
+ */
+export interface WaCapabilities {
+    /** Linked by a QR scan or a pairing code (`requestPairingCode`). */
+    qrLink: boolean;
+    /** Imports recent history when linked. */
+    history: boolean;
+    /** Takes part in groups. */
+    groups: boolean;
+    /**
+     * Free-form messages only within this many hours of the customer's last message (WhatsApp
+     * Business API: 24); after that only an approved template (`sendTemplate`). null: no window.
+     */
+    replyWindowHours: number | null;
+    /** Lists and sends approved message templates (`listTemplates`, `sendTemplate`). */
+    templates: boolean;
+    /** Receives messages at a public https address (a webhook over Phone access / the tunnel). */
+    needsPublicUrl: boolean;
+}
+/** The capabilities of an adapter that declares none: a phone linked by QR (Baileys, the fake). */
+export declare const LINKED_PHONE_CAPABILITIES: WaCapabilities;
+/** An approved message template of the number's business account. */
+export interface WaTemplate {
+    name: string;
+    /** Meta language code, e.g. `en`, `ms`, `zh_CN`. */
+    language: string;
+    category: 'utility' | 'marketing' | 'authentication';
+    /** Body text with {{1}}, {{2}} … variables. */
+    body: string;
+    /** Example value for each body variable, in order (may be shorter than the variable count). */
+    examples: string[];
+    /** A media header (image/document/video) or buttons: listed, not sent by EzyChat (v1). */
+    header: 'text' | 'image' | 'document' | 'video' | null;
+    buttons: boolean;
+}
+/** One template message to send: the template and its body variable values, in order. */
+export interface WaTemplateSend {
+    name: string;
+    language: string;
+    params: string[];
+}
 export interface WaAdapter {
     readonly status: WaStatus;
+    /** What this connection can do; absent: a linked phone (`LINKED_PHONE_CAPABILITIES`). */
+    readonly capabilities?: WaCapabilities;
+    /** Approved templates (adapters with `capabilities.templates`). Throws WaUnavailableError offline. */
+    listTemplates?(): Promise<WaTemplate[]>;
+    /** Sends a template message (adapters with `capabilities.templates`). */
+    sendTemplate?(chatJid: string, template: WaTemplateSend): Promise<SendResult>;
     on<K extends keyof WaAdapterEvents>(ev: K, fn: (...a: WaAdapterEvents[K]) => void): this;
     off<K extends keyof WaAdapterEvents>(ev: K, fn: (...a: WaAdapterEvents[K]) => void): this;
     /** idempotent */

package/dist/types.js

@@ -1,3 +1,12 @@
+/** The capabilities of an adapter that declares none: a phone linked by QR (Baileys, the fake). */
+export const LINKED_PHONE_CAPABILITIES = Object.freeze({
+    qrLink: true,
+    history: true,
+    groups: true,
+    replyWindowHours: null,
+    templates: false,
+    needsPublicUrl: false,
+});
 export class WaUnavailableError extends Error {
     code = 'wa_unavailable';
     constructor(message = 'WhatsApp is not connected') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ezychat/wa",
-  "version": "0.1.56",
+  "version": "0.1.57",
   "type": "module",
   "description": "EzyChat core: WhatsApp adapter interface, Baileys adapter and fake adapter.",
   "license": "MIT",
@@ -37,7 +37,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ezychat/shared": "0.1.56",
+    "@ezychat/shared": "0.1.57",
     "baileys": "^7.0.0-rc14",
     "pino": "^10.4.0",
     "qrcode": "^1.5.4"