@ezychat/wa 0.0.0-stage → 0.1.38

package/dist/fake/fake-adapter.js

@@ -0,0 +1,198 @@
+import { EventEmitter } from 'node:events';
+import { WaUnavailableError, } from '../types.js';
+const FAKE_ME = { jid: '60000000000@s.whatsapp.net', name: 'Fake' };
+/**
+ * In-memory WaAdapter for tests and `--fake-wa` dev mode. Never touches the network.
+ */
+/** Per-process id prefix, so a restarted dev server never reuses message ids stored in app.db. */
+export const FAKE_RUN = Date.now().toString(36);
+export class FakeWaAdapter extends EventEmitter {
+    _status = { state: 'disconnected', me: null, qr: null, lastError: null };
+    autoOpen;
+    inCounter = 0;
+    outCounter = 0;
+    nextSendError = null;
+    media = new Map();
+    groups = new Map();
+    abouts = new Map();
+    /** Every getGroupInfo / getAbout call, for tests that check caching. */
+    groupInfoCalls = [];
+    aboutCalls = [];
+    sent = [];
+    reads = [];
+    presences = [];
+    constructor(opts) {
+        super();
+        this.autoOpen = opts?.autoOpen ?? true;
+    }
+    get status() {
+        return this._status;
+    }
+    on(ev, fn) {
+        return super.on(ev, fn);
+    }
+    off(ev, fn) {
+        return super.off(ev, fn);
+    }
+    emitTyped(ev, ...args) {
+        this.emit(ev, ...args);
+    }
+    setStatus(patch) {
+        this._status = { ...this._status, ...patch };
+        this.emitTyped('status', this._status);
+    }
+    async connect() {
+        if (this._status.state === 'open' || this._status.state === 'connecting')
+            return;
+        this.setStatus({ state: 'connecting', qr: null, lastError: null });
+        if (this.autoOpen)
+            this.setStatus({ state: 'open', me: { ...FAKE_ME }, qr: null });
+    }
+    async disconnect() {
+        if (this._status.state === 'disconnected')
+            return;
+        this.setStatus({ state: 'disconnected', qr: null });
+    }
+    async logout() {
+        this.setStatus({ state: 'logged_out', me: null, qr: null });
+    }
+    async takeover() {
+        this.setStatus({ state: 'connecting', qr: null, lastError: null });
+        this.setStatus({ state: 'open', me: { ...FAKE_ME }, qr: null });
+    }
+    /** test helper: last phone number a pairing code was requested for */
+    pairingRequests = [];
+    async requestPairingCode(phone) {
+        if (this._status.state === 'open')
+            throw new Error('A WhatsApp number is already linked');
+        this.pairingRequests.push(phone.replace(/\D/g, ''));
+        return 'FAKE1234';
+    }
+    beforeSend() {
+        if (this._status.state !== 'open')
+            throw new WaUnavailableError();
+        if (this.nextSendError) {
+            const err = this.nextSendError;
+            this.nextSendError = null;
+            throw err;
+        }
+    }
+    afterSend(chatJid, id) {
+        const timestamp = Date.now();
+        this.emitTyped('messageStatus', { id, chatJid, status: 'sent' });
+        setImmediate(() => this.emitTyped('messageStatus', { id, chatJid, status: 'delivered' }));
+        return { id, timestamp };
+    }
+    async sendText(chatJid, text, opts) {
+        this.beforeSend();
+        const id = `FAKE-OUT-${FAKE_RUN}-${++this.outCounter}`;
+        this.sent.push({ chatJid, text, id, ...(opts?.quotedId ? { reply: opts } : {}) });
+        return this.afterSend(chatJid, id);
+    }
+    async sendMedia(chatJid, file, opts) {
+        this.beforeSend();
+        const id = `FAKE-OUT-${FAKE_RUN}-${++this.outCounter}`;
+        this.sent.push({ chatJid, file, id, ...(opts?.quotedId ? { reply: opts } : {}) });
+        this.media.set(id, file.buffer);
+        return this.afterSend(chatJid, id);
+    }
+    async markRead(chatJid, messageIds) {
+        this.reads.push({ chatJid, messageIds: [...messageIds] });
+    }
+    async sendPresence(chatJid, presence) {
+        this.presences.push({ chatJid, presence });
+    }
+    async downloadMedia(messageId) {
+        return this.media.get(messageId) ?? null;
+    }
+    async getProfilePicture(_jid) {
+        if (this._status.state !== 'open')
+            throw new WaUnavailableError();
+        return null;
+    }
+    async getContactAliases(_jids) {
+        return [];
+    }
+    async getGroupInfo(groupJid) {
+        if (this._status.state !== 'open')
+            throw new WaUnavailableError();
+        this.groupInfoCalls.push(groupJid);
+        const g = this.groups.get(groupJid);
+        const info = g ?? {
+            jid: groupJid,
+            name: null,
+            description: null,
+            createdAt: null,
+            ownerJid: null,
+            size: 0,
+            participants: [],
+        };
+        return structuredClone(info);
+    }
+    async getAbout(jid) {
+        if (this._status.state !== 'open')
+            throw new WaUnavailableError();
+        this.aboutCalls.push(jid);
+        if (this.aboutFails)
+            throw new Error('About lookup failed');
+        return this.abouts.get(jid) ?? null;
+    }
+    /** Make the next getAbout calls fail, as a WhatsApp request error would. */
+    aboutFails = false;
+    // ---- test helpers ----
+    /** What getGroupInfo returns for this group (members as WhatsApp lists them, no names). */
+    setGroupInfo(info) {
+        this.groups.set(info.jid, structuredClone(info));
+    }
+    /** What getAbout returns for this person. */
+    setAbout(jid, about) {
+        this.abouts.set(jid, about);
+    }
+    /** Emit `groupChanged`, as WhatsApp does when members are added, removed, promoted or demoted. */
+    simulateGroupChanged(groupJid) {
+        this.emitTyped('groupChanged', { groupJid });
+    }
+    /** makes downloadMedia(messageId) return `buffer` */
+    setMedia(messageId, buffer) {
+        this.media.set(messageId, buffer);
+    }
+    /** Emit explicit PN/LID pairs as the adapter does when WhatsApp reveals them. */
+    simulateContactAliases(pairs) {
+        this.emitTyped('contactAliases', pairs.map((p) => ({ ...p })));
+    }
+    /** Emit an incoming live message. Generates id `FAKE-<run>-<n>` unless given. */
+    simulateIncoming(p) {
+        // Unique per process start: a restarted dev server must not reuse ids already stored in app.db.
+        const id = p.id ?? `FAKE-${FAKE_RUN}-${++this.inCounter}`;
+        const isGroup = p.chatJid.endsWith('@g.us');
+        const msg = {
+            id,
+            chatJid: p.chatJid,
+            chatJidAlt: p.chatJidAlt ?? null,
+            senderJid: p.senderJid !== undefined ? p.senderJid : isGroup ? null : p.chatJid,
+            senderJidAlt: p.senderJidAlt ?? null,
+            senderName: p.senderName ?? null,
+            fromMe: p.fromMe ?? false,
+            type: p.type ?? 'text',
+            body: p.body,
+            ...(p.mentionedJids !== undefined ? { mentionedJids: [...p.mentionedJids] } : {}),
+            quotedId: p.quotedId ?? null,
+            timestamp: p.timestamp ?? Date.now(),
+            media: p.media ?? null,
+        };
+        this.emitTyped('message', msg, { source: 'live' });
+        return msg;
+    }
+    simulateStatus(s) {
+        this.setStatus(s);
+    }
+    failNextSend(err = new Error('Fake send failure')) {
+        this.nextSendError = err;
+    }
+    setConnected(connected) {
+        if (connected)
+            this.setStatus({ state: 'open', me: { ...FAKE_ME }, qr: null, lastError: null });
+        else
+            this.setStatus({ state: 'disconnected', qr: null });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { FAKE_RUN, FakeWaAdapter, type FakeSentRecord } from './fake/fake-adapter.js';
+export { createBaileysAdapter } from './baileys/index.js';
+export { readStoredLidMappings } from './baileys/stored-lid-mappings.js';
+export { contactAliasPair, normalizeContactJid } from './baileys/contact-aliases.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { FAKE_RUN, FakeWaAdapter } from './fake/fake-adapter.js';
+export { createBaileysAdapter } from './baileys/index.js';
+export { readStoredLidMappings } from './baileys/stored-lid-mappings.js';
+export { contactAliasPair, normalizeContactJid } from './baileys/contact-aliases.js';

package/dist/types.d.ts

@@ -0,0 +1,163 @@
+import type { Logger } from 'pino';
+import type { MessageType, WaStatus } from '@ezychat/shared';
+export interface WaIncomingMessage {
+    id: string;
+    chatJid: string;
+    /**
+     * DM only: the same person's other address as WhatsApp delivered it (`key.remoteJidAlt`), PN for a
+     * LID chat or the reverse, device suffix stripped. Null/absent for groups or when not provided.
+     */
+    chatJidAlt?: string | null;
+    senderJid: string | null;
+    /** Group sender's explicitly associated alternate phone/LID address. */
+    senderJidAlt?: string | null;
+    senderName: string | null;
+    fromMe: boolean;
+    type: MessageType;
+    body: string | null;
+    /** Explicit mentions from contextInfo; absent only for older adapters/imports. */
+    mentionedJids?: string[];
+    quotedId: string | null;
+    /** epoch ms */
+    timestamp: number;
+    media: null | {
+        mime: string;
+        fileName: string | null;
+        download: () => Promise<Buffer>;
+    };
+}
+export interface WaChatInfo {
+    jid: string;
+    type: 'dm' | 'group';
+    name: string | null;
+}
+export interface WaContactInfo {
+    jid: string;
+    pushName: string | null;
+    savedName: string | null;
+    /** Explicitly associated phone/LID identities, never inferred from names. */
+    aliases?: string[];
+}
+/** Where an explicit PN/LID association was learned (stored in jid_aliases.source). */
+export type WaAliasSource = 'message' | 'history' | 'contacts' | 'lid-mapping' | 'keystore';
+export interface WaContactAlias {
+    jid: string;
+    alias: string;
+    source?: WaAliasSource;
+}
+/** A member of a WhatsApp group, as WhatsApp lists it (names are not part of the list). */
+export interface WaGroupParticipant {
+    /** The member's address as the group lists it: a phone-number JID or a WhatsApp ID (LID). */
+    jid: string;
+    /** Phone-number JID when WhatsApp shares it (`…@s.whatsapp.net`), else null (number hidden). */
+    phoneJid: string | null;
+    /** WhatsApp ID (`…@lid`) when known, else null. */
+    lidJid: string | null;
+    /** WhatsApp username, only when WhatsApp sends it. */
+    username: string | null;
+    role: 'superadmin' | 'admin' | 'member';
+}
+export interface WaGroupInfo {
+    jid: string;
+    name: string | null;
+    description: string | null;
+    /** epoch ms, null when unknown */
+    createdAt: number | null;
+    /** Creator's phone-number JID or WhatsApp ID, when known. */
+    ownerJid: string | null;
+    /** Member count reported by WhatsApp (can exceed participants.length for very large groups). */
+    size: number;
+    participants: WaGroupParticipant[];
+}
+export interface WaMessageStatusUpdate {
+    id: string;
+    chatJid: string;
+    status: 'sent' | 'delivered' | 'read' | 'failed';
+}
+export interface WaAdapterEvents {
+    status: [WaStatus];
+    message: [WaIncomingMessage, {
+        source: 'live' | 'history';
+    }];
+    messageStatus: [WaMessageStatusUpdate];
+    chats: [WaChatInfo[]];
+    contacts: [WaContactInfo[]];
+    contactAliases: [WaContactAlias[]];
+    /** A group's members or settings changed; cached member lists for it are stale. */
+    groupChanged: [{
+        groupJid: string;
+    }];
+}
+/**
+ * Saved copy of a quoted message (from the database). The adapter's live message cache is small and
+ * cleared on reconnect, so a reply to an older message rebuilds the quote from this instead.
+ */
+export interface WaQuotedRef {
+    id: string;
+    fromMe: boolean;
+    /** Group messages: who wrote it (needed so WhatsApp attributes the quote). */
+    senderJid: string | null;
+    type: MessageType;
+    /** Text or caption; null for media without a caption. */
+    text: string | null;
+}
+export interface WaSendOptions {
+    /** Reply to this WhatsApp message id. */
+    quotedId?: string;
+    /** Used when the quoted message is no longer in the adapter's live cache. */
+    quoted?: WaQuotedRef;
+}
+export interface SendResult {
+    id: string;
+    timestamp: number;
+}
+export interface WaSendFile {
+    buffer: Buffer;
+    mime: string;
+    fileName: string;
+    caption?: string;
+    /** Send OGG/Opus audio as a voice note (push-to-talk), with its length and 64-bar waveform (0–100). */
+    voiceNote?: {
+        seconds: number;
+        waveform: Uint8Array;
+    };
+}
+export interface WaAdapter {
+    readonly status: WaStatus;
+    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 */
+    connect(): Promise<void>;
+    /** close socket, keep auth */
+    disconnect(): Promise<void>;
+    /** unlink device + wipe auth */
+    logout(): Promise<void>;
+    /** reconnect after 'replaced' */
+    takeover(): Promise<void>;
+    /** link by phone number: returns the 8-character pairing code to enter on the phone */
+    requestPairingCode(phone: string): Promise<string>;
+    sendText(chatJid: string, text: string, opts?: WaSendOptions): Promise<SendResult>;
+    sendMedia(chatJid: string, file: WaSendFile, opts?: WaSendOptions): Promise<SendResult>;
+    markRead(chatJid: string, messageIds: string[]): Promise<void>;
+    sendPresence(chatJid: string, presence: 'composing' | 'paused'): Promise<void>;
+    /** re-download by id if still cached */
+    downloadMedia(messageId: string): Promise<Buffer | null>;
+    /** Photo URL; null when there is none or it is private. Throws when it cannot be read. */
+    getProfilePicture(jid: string): Promise<string | null>;
+    /** Members and details of a group this number belongs to. Throws WaUnavailableError when offline. */
+    getGroupInfo(groupJid: string): Promise<WaGroupInfo>;
+    /** A person's WhatsApp "About" text; null when hidden or unset. Throws when it cannot be read. */
+    getAbout(jid: string): Promise<string | null>;
+    /** Resolve existing local phone/LID mappings only; must not query WhatsApp. */
+    getContactAliases(jids: string[]): Promise<WaContactAlias[]>;
+}
+export interface WaAdapterOptions {
+    authDir: string;
+    /** days of history to import; a getter is re-read on every (re)connect / history batch */
+    historyDays: number | (() => number);
+    logger?: Logger;
+}
+export declare class WaUnavailableError extends Error {
+    readonly code: "wa_unavailable";
+    constructor(message?: string);
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+export class WaUnavailableError extends Error {
+    code = 'wa_unavailable';
+    constructor(message = 'WhatsApp is not connected') {
+        super(message);
+        this.name = 'WaUnavailableError';
+    }
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@ezychat/wa",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.38",
+  "type": "module",
+  "description": "EzyChat core: WhatsApp adapter interface, Baileys adapter and fake adapter.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ossmalaysia/ezychat-lite.git",
+    "directory": "packages/wa"
+  },
+  "homepage": "https://ezychat.ai/",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "ezychat-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ezychat/shared": "0.1.38",
+    "baileys": "^7.0.0-rc14",
+    "pino": "^10.3.1",
+    "qrcode": "^1.5.4"
+  },
+  "devDependencies": {
+    "@types/qrcode": "^1.5.6"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.