@wppconnect/wa-js 4.2.0 → 4.3.1-alpha.0

package/CHANGELOG.md

@@ -1,3 +1,3 @@
-## 4.2.0 (2026-05-15)
+## <small>4.3.1-alpha.0 (2026-06-04)</small>
 
-* fix: remove outdated pre-lid release patches (#3425) ([aadc862253d4c4989d6a9e404c349889d55fa0d1](https://github.com/wppconnect-team/wa-js/commit/aadc862253d4c4989d6a9e404c349889d55fa0d1)), closes [#3425](https://github.com/wppconnect-team/wa-js/issues/3425)
+* fix: unknown on chat list ([a8bd92d2b381d56ca5b96c392f71aa81d7ff0c70](https://github.com/wppconnect-team/wa-js/commit/a8bd92d2b381d56ca5b96c392f71aa81d7ff0c70))

package/CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+WA-JS (`@wppconnect/wa-js`) is a browser injection library that extracts and wraps WhatsApp Web's internal functions, exposing them as a stable public API (`window.WPP`). It is bundled as a UMD library and injected into the WhatsApp Web page at runtime.
+
+## Commands
+
+```bash
+# Build
+npm run build:prd        # Production build (minified) → dist/wppconnect-wa.js
+npm run build:dev        # Development build (inline source maps)
+npm run build:watch      # Watch mode
+
+# Lint
+npm run lint             # ESLint + Prettier check
+
+# Docs
+npm run docs:build       # Generate TypeDoc API docs
+
+# Local development
+npm run build:dev && WA_VERSION=latest npm run launch:local
+npm run build:dev && WA_VERSION=<version> npm run launch:local
+# Available versions listed in node_modules/@wppconnect/wa-version/html/
+
+# WA source — download bundles (alpha included)
+npm run wa-source:populate                          # latest 20 versions (default)
+npm run wa-source:populate -- --all                # all versions
+npm run wa-source:populate -- --version <version>  # single version
+npm run wa-source:populate -- --force              # re-download existing
+
+# WA source — format before debugging internals (see Debugging section)
+npm run wa-source:format <version>
+```
+
+Available versions (alpha included) are listed in `node_modules/@wppconnect/wa-version/html/`.
+
+## Architecture
+
+### Loader System
+
+The most critical piece. `src/loader/` detects which WhatsApp module system is active and exposes WhatsApp's internal modules to the rest of WA-JS:
+
+- **Meta loader** (WA >= 2.3000.0): Uses `global.require()` with `ErrorGuard.skipGuardGlobal()`
+- **Webpack loader** (legacy): Intercepts webpack chunk callbacks at startup
+
+All `src/whatsapp/` imports resolve through this loader system at runtime.
+
+### Module Layout
+
+`src/index.ts` is the entry point and re-exports all feature modules. Each feature module (e.g. `src/chat/`, `src/group/`) follows this internal pattern:
+
+```
+<feature>/
+├── index.ts          # Re-exports functions and registers patches/events
+├── types.ts          # TypeScript types for the feature
+├── patch.ts          # Monkey-patches WhatsApp internals (if needed)
+├── functions/        # One file per exported function
+└── events/           # Event registration and re-emission
+```
+
+### `src/whatsapp/`
+
+Low-level bindings to WhatsApp Web's internals, organized by type:
+- `models/` — WhatsApp data model classes (Chat, Message, Contact, etc.)
+- `collections/` — Backbone-style collections of models
+- `stores/` — Singleton global collection instances
+- `functions/` — Raw WhatsApp functions extracted from the bundle
+- `enums/` — WhatsApp enumerations
+- `multidevice/` — Multi-device protocol
+- `websocket/` — WebSocket layer
+
+These are **not part of the public API**. Feature modules in `src/<feature>/` wrap them.
+
+### Build Output
+
+Webpack bundles everything into a single UMD file (`dist/wppconnect-wa.js`) exposing the global `WPP`. The `src/tools/` directory contains development utilities (not included in the bundle).
+
+## Debugging WhatsApp Internals
+
+When a WA-JS function breaks after a WhatsApp Web update, the root cause is almost always one of:
+
+- A function was **moved to a different internal module**
+- A function was **renamed**
+- Arguments changed from **positional to named params** (or vice versa)
+
+### Workflow
+
+**Before inspecting any WhatsApp source**, the bundles must be downloaded and formatted:
+
+1. Download bundles for the target version (if not already done). The default run fetches the latest 20 versions; for an older one pass `--version`:
+   ```bash
+   npm run wa-source:populate                          # latest 20 (usually sufficient)
+   npm run wa-source:populate -- --version <version>  # specific older version
+   ```
+2. Format so identifiers and structure are readable:
+   ```bash
+   npm run wa-source:format <version>
+   ```
+
+> **Fresh debug session:** If you haven't worked on this WA version before, confirm with the user that they have run both commands above for that version before proceeding. Do not attempt to read `wa-source/<version>/` without the formatted source in place.
+
+Once formatted, search the WA source for the function or module in question, compare old vs. new signatures, and update the corresponding binding in `src/whatsapp/`.
+
+## Version Compatibility
+
+Fixes must support both the new WhatsApp Web version and older versions still listed in `node_modules/@wppconnect/wa-version/html/`.
+
+If a workaround is only needed for older versions, mark it with a TODO so it gets cleaned up once those versions are no longer available:
+
+```ts
+// TODO: remove when <version> is no longer available in wa-version/html
+```
+
+## Code Conventions
+
+- Node version: 24 (see `.nvmrc`)
+- TypeScript strict mode enabled; decorators enabled
+- ESLint enforces import ordering (`simple-import-sort`) and file headers
+- Prettier: single quotes, trailing commas (ES5)
+- Commit messages follow Conventional Commits (enforced by commitlint)
+- Pre-commit: lint-staged runs ESLint on staged files

package/README.md

@@ -320,6 +320,37 @@ For the most up-to-date list of available functions, launch the project locally
 
 `Object.keys(WPP.privacy).sort()`
 
+### Labels vs Lists
+
+WhatsApp has two separate chat-organization features that share the same internal infrastructure but serve different purposes:
+
+| | `WPP.labels` | `WPP.lists` |
+|---|---|---|
+| **Account** | Business only | Personal + Business |
+| **Purpose** | Tag chats for CRM workflows (e.g. "New lead", "Pending") | Group chats into named tabs (e.g. "Family", "Work") |
+| **Visible as** | Colored label chips on chats | Tabs at the top of the chat list |
+| **API guard** | `assertIsBusiness()` — throws on personal accounts | No business check |
+
+Use `WPP.labels` for business label management. Use `WPP.lists` to create and manage chat grouping lists on any account type.
+
+#### Lists Functions
+
+`WPP.lists.create` - Create a new list
+
+`WPP.lists.list` - Get all custom lists
+
+`WPP.lists.addChats` - Add chats to a list
+
+`WPP.lists.removeChats` - Remove chats from a list
+
+`WPP.lists.rename` - Rename a list
+
+`WPP.lists.remove` - Delete a list
+
+For the most up-to-date list of available functions, launch the project locally and run this in your browser console:
+
+`Object.keys(WPP.lists).sort()`
+
 ### Events
 
 #### Connection Events
@@ -452,6 +483,90 @@ This is useful for:
 - Identifying when function signatures changed
 - Finding new or removed modules
 
+## Building with a custom global variable name
+
+If you are developing an extension or automation tool that may run on the same WhatsApp Web page alongside other WA-JS-based projects, you can compile your own build of this library under a different global variable name to avoid conflicts.
+
+### When to do this
+
+By default, WA-JS exposes itself as `window.WPP`. If two tools built on WA-JS are injected into the same page using the default name, they will overwrite each other. Building under a custom name (e.g. `window.MYWPP`) ensures each tool owns its own isolated global.
+
+### Steps
+
+**1. Clone the repository and install dependencies**
+
+```bash
+git clone https://github.com/wppconnect-team/wa-js.git
+cd wa-js
+npm install
+```
+
+**2. Change the global variable name in `webpack.config.js`**
+
+Find the `output.library` block and replace `'WPP'` with your chosen name:
+
+```js
+// webpack.config.js
+output: {
+  filename: 'wppconnect-wa.js',
+  path: path.resolve(__dirname, 'dist'),
+  library: {
+    name: 'MYWPP', // <-- your custom global variable name
+    type: 'global',
+  },
+},
+```
+
+**3. Update the pre-injection config key in `src/config/index.ts`**
+
+Replace every occurrence of `WPPConfig` with `<YOURNAME>Config` (e.g. `MYWPPConfig`). There are three occurrences in that file:
+
+```ts
+// Before
+interface Window { WPPConfig: Config; }
+const setted = window.WPPConfig || {};
+window.WPPConfig = config;
+
+// After (using MYWPP as example)
+interface Window { MYWPPConfig: Config; }
+const setted = window.MYWPPConfig || {};
+window.MYWPPConfig = config;
+```
+
+**4. Build the production bundle**
+
+```bash
+npm run build:prd
+```
+
+The compiled file will be available at:
+
+```
+dist/wppconnect-wa.js
+```
+
+### Result
+
+When your custom build is injected into WhatsApp Web:
+
+- The library is available as **`window.MYWPP`** (your chosen name).
+- **`window.WPP` is not set** — there is no conflict with other WA-JS builds on the same page.
+- Pre-injection configuration is read from **`window.MYWPPConfig`** instead of `window.WPPConfig`.
+
+**Pre-injection usage example:**
+
+```javascript
+// Set this before injecting your custom build
+window.MYWPPConfig = {
+  deviceName: 'My Extension',
+};
+
+// After injection, use your custom global
+window.MYWPP.loader.onReady(function () {
+  console.log('My extension is ready');
+});
+```
+
 ## How to use this project
 
 Basically, you need to inject the `wppconnect-wa.js` file into the browser after WhatsApp page load.

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export { isFullReady, isInjected, isReady } from './loader';
 export { loader };
 export { config, Config } from './config';
 export * as blocklist from './blocklist';
+export * as lists from './lists';
 export * as call from './call';
 export * as cart from './cart';
 export * as catalog from './catalog';

package/dist/lists/functions/addChats.d.ts

@@ -0,0 +1,27 @@
+/*!
+ * Copyright 2026 WPPConnect Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Wid } from '../../whatsapp';
+/**
+ * Add chats to an existing list
+ *
+ * @example
+ * ```javascript
+ * await WPP.lists.addChats('42', ['number@c.us', 'number2@c.us']);
+ * ```
+ *
+ * @category Lists
+ */
+export declare function addChats(listId: string, chatIds: (string | Wid)[]): Promise<void>;

package/dist/lists/functions/create.d.ts

@@ -0,0 +1,29 @@
+/*!
+ * Copyright 2026 WPPConnect Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Wid } from '../../whatsapp';
+/**
+ * Create a new list and optionally add chats to it.
+ * Works for both personal and business accounts.
+ *
+ * @example
+ * ```javascript
+ * const id = await WPP.lists.create('Family', ['number@c.us', 'number2@c.us']);
+ * console.log(id); // '42'
+ * ```
+ *
+ * @category Lists
+ */
+export declare function create(name: string, chatIds?: (string | Wid)[], colorIndex?: number): Promise<string>;

package/dist/lists/functions/index.d.ts

@@ -0,0 +1,21 @@
+/*!
+ * Copyright 2026 WPPConnect Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export { addChats } from './addChats';
+export { create } from './create';
+export { list, ListInfo } from './list';
+export { remove } from './remove';
+export { removeChats } from './removeChats';
+export { rename } from './rename';

package/dist/lists/functions/list.d.ts

@@ -0,0 +1,34 @@
+/*!
+ * Copyright 2026 WPPConnect Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export interface ListInfo {
+    id: string;
+    name: string;
+    colorIndex: number;
+}
+/**
+ * Return all custom lists (personal account lists)
+ *
+ * @example
+ * ```javascript
+ * const lists = WPP.lists.list();
+ * for (const l of lists) {
+ *   console.log(l.id, l.name);
+ * }
+ * ```
+ *
+ * @category Lists
+ */
+export declare function list(): ListInfo[];

package/dist/lists/functions/remove.d.ts

@@ -0,0 +1,26 @@
+/*!
+ * Copyright 2026 WPPConnect Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Delete a list by ID
+ *
+ * @example
+ * ```javascript
+ * await WPP.lists.remove('42');
+ * ```
+ *
+ * @category Lists
+ */
+export declare function remove(listId: string): Promise<void>;

package/dist/lists/functions/removeChats.d.ts

@@ -0,0 +1,27 @@
+/*!
+ * Copyright 2026 WPPConnect Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Wid } from '../../whatsapp';
+/**
+ * Remove chats from a list
+ *
+ * @example
+ * ```javascript
+ * await WPP.lists.removeChats('42', ['number@c.us']);
+ * ```
+ *
+ * @category Lists
+ */
+export declare function removeChats(listId: string, chatIds: (string | Wid)[]): Promise<void>;

package/dist/lists/functions/rename.d.ts

@@ -0,0 +1,26 @@
+/*!
+ * Copyright 2026 WPPConnect Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Rename a list
+ *
+ * @example
+ * ```javascript
+ * await WPP.lists.rename('42', 'New Name');
+ * ```
+ *
+ * @category Lists
+ */
+export declare function rename(listId: string, newName: string): Promise<void>;

package/dist/lists/index.d.ts

@@ -0,0 +1,16 @@
+/*!
+ * Copyright 2026 WPPConnect Team
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export * from './functions';

package/dist/whatsapp/collections/ButtonCollection.d.ts

@@ -15,7 +15,9 @@
  */
 import { ReplyButtonModel } from '../models';
 import { BaseCollection } from './BaseCollection';
-/** @whatsapp 47688 */
+/** @whatsapp 47688
+ * @whatsapp WAWebButtonCollection >= 2.3000.1039447205
+ */
 export declare class ButtonCollection extends BaseCollection<ReplyButtonModel> {
     static model: ReplyButtonModel;
     static comparator(): any;

package/dist/whatsapp/functions/subscribePresence.d.ts

@@ -18,3 +18,17 @@ import { Wid } from '..';
  * @whatsapp WAWebContactPresenceBridge
  */
 export declare function subscribePresence(id: Wid, tcToken?: any): Promise<any>;
+/**
+ * Subscribe user presence (individual contact).
+ * Replaces subscribePresence in WAWebContactPresenceBridge >= ~2.3000.1039447205
+ *
+ * @whatsapp WAWebContactPresenceBridge >= 2.3000.1039447205
+ */
+export declare function subscribeUserPresence(id: Wid): Promise<any>;
+/**
+ * Subscribe group presence.
+ * Added in WAWebContactPresenceBridge >= ~2.3000.1039447205
+ *
+ * @whatsapp WAWebContactPresenceBridge >= 2.3000.1039447205
+ */
+export declare function subscribeGroupPresence(id: Wid): void;

package/dist/whatsapp/models/CallModel.d.ts

@@ -34,13 +34,15 @@ interface Session {
 }
 interface Derived {
 }
-/** @whatsapp 36473
+/** @whatsapp WAWebCallModel >= 2.3000.0
+ * @whatsapp 36473
  * @whatsapp 40122 >= 2.2204.13
  * @whatsapp 736473 >= 2.2222.8
  */
 export declare interface CallModel extends ModelProxy<Props, Session, Derived> {
 }
-/** @whatsapp 36473
+/** @whatsapp WAWebCallModel >= 2.3000.0
+ * @whatsapp 36473
  * @whatsapp 40122 >= 2.2204.13
  * @whatsapp 736473 >= 2.2222.8
  */

package/dist/whatsapp/models/ChatModel.d.ts

@@ -39,6 +39,8 @@ interface Props extends PropsChatBase {
     unreadMentionsOfMe?: any;
     msgUnsyncedButtonReplyMsgs?: any;
     endOfHistoryTransferType?: any;
+    /** Contact LID for PnLess protocol (Phone Number-less) */
+    accountLid?: Wid;
 }
 interface Session extends SessionChatBase {
     stale?: any;

package/dist/whatsapp/models/LabelModel.d.ts

@@ -20,6 +20,8 @@ interface Props {
     colorIndex?: number;
     color?: number;
     count?: any;
+    type?: number;
+    predefinedId?: number;
 }
 interface Session {
     stale?: any;