@wppconnect/wa-js 3.23.4 → 4.0.0

package/CHANGELOG.md

@@ -1,6 +1,3 @@
-## 3.23.4 (2026-04-17)
+## 4.0.0 (2026-04-29)
 
-
-### Bug Fixes
-
-* disconnection after reading qrcode - flushing during sync ([#3409](https://github.com/wppconnect-team/wa-js/issues/3409)) ([428ee01](https://github.com/wppconnect-team/wa-js/commit/428ee012c12dedc663991e8734af67876a9593af))
+* feat: add BackendEventBus and register backend event handling (#3416) ([75ca156033d428784e8bff868e1cead3ae18a8c5](https://github.com/wppconnect-team/wa-js/commit/75ca156033d428784e8bff868e1cead3ae18a8c5)), closes [#3416](https://github.com/wppconnect-team/wa-js/issues/3416)

package/README.md

@@ -35,7 +35,7 @@ After build, this project generates a file `dist/wppconnect-wa.js` to be used fo
 
 Some parts of `WPP` variable:
 
-- `WPP.webpack` - Scripts to export WhatsApp functions.
+- `WPP.loader` - Scripts to export WhatsApp functions.
 - `WPP.whatsapp` - Only exported WhatsApp functions.
 - `WPP.chat` - Chat functions and events.
 - ...
@@ -261,7 +261,7 @@ Basically, you need to inject the `wppconnect-wa.js` file into the browser after
 (function () {
   'use strict';
 
-  WPP.webpack.onReady(function () {
+  WPP.loader.onReady(function () {
     alert('Ready to use WPPConnect WA-JS');
   });
 

package/changelog.config.cjs

@@ -0,0 +1,43 @@
+const TYPE_TITLES = {
+  feat: 'Features',
+  fix: 'Bug Fixes',
+  perf: 'Performance Improvements',
+  revert: 'Reverts',
+  docs: 'Documentation',
+  style: 'Styles',
+  refactor: 'Code Refactoring',
+  test: 'Tests',
+  build: 'Build System',
+  ci: 'Continuous Integration',
+  chore: 'Chores',
+};
+
+function toSection(type) {
+  if (!type) {
+    return 'Other Changes';
+  }
+
+  const normalized = String(type).toLowerCase();
+  if (TYPE_TITLES[normalized]) {
+    return TYPE_TITLES[normalized];
+  }
+
+  return normalized.charAt(0).toUpperCase() + normalized.slice(1);
+}
+
+module.exports = {
+  preset: 'angular',
+  writerOpts: {
+    transform: (commit) => {
+      const nextCommit = { ...commit };
+      nextCommit.type = toSection(nextCommit.type);
+
+      // Keep wildcard scopes from polluting section output.
+      if (nextCommit.scope === '*') {
+        nextCommit.scope = '';
+      }
+
+      return nextCommit;
+    },
+  },
+};

package/dist/conn/events/eventTypes.d.ts

@@ -13,10 +13,26 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { BackendEventName } from '../../whatsapp';
 import { LogoutReason, StreamInfo, StreamMode } from '../../whatsapp/enums';
 import { AuthCode } from '../types';
 export interface ConnEventTypes {
     'conn.auth_code_change': AuthCode | null;
+    /**
+     * Triggered for every event emitted by WhatsApp Web's internal BackendEventBus.
+     * The first argument is the event name (one of the BackendEvent constant values).
+     * Some events carry additional arguments (e.g. set_socket_state passes the new state).
+     *
+     * @example
+     * ```javascript
+     * WPP.on('conn.backend_event', (eventName, ...args) => {
+     *   if (eventName === 'storage_initialization_error') {
+     *     // Browser IndexedDB failed — clear profile and restart to recover
+     *   }
+     * });
+     * ```
+     */
+    'conn.backend_event': (eventName: BackendEventName, ...args: any[]) => void;
     /**
      * Triggered afted a success QR code scan
      *

package/dist/conn/events/index.d.ts

@@ -15,6 +15,7 @@
  */
 import './registerAuthCodeChangeEvent';
 import './registerAuthenticatedEvent';
+import './registerBackendEventBusEvents';
 import './registerLogoutEvent';
 import './registerLogoutReasonEvent';
 import './registerMainInit';

package/dist/conn/events/registerBackendEventBusEvents.d.ts

@@ -0,0 +1,16 @@
+/*!
+ * Copyright 2021 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 {};

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

@@ -20,7 +20,12 @@ export { getPnLidEntry, InvalidWidForGetPnLidEntry, PnLidContactInfo, PnLidEntry
 export { getProfilePictureUrl } from './getProfilePictureUrl';
 export { getStatus } from './getStatus';
 export { ContactListOptions, list } from './list';
-export { queryExists } from './queryExists';
+/**
+ * @deprecated Use queryWidExists instead
+ */
+export { queryExists, QueryExistsResult } from './queryExists';
+export { queryUsernameExists, QueryUsernameExistsKeyRequired, QueryUsernameExistsResult, } from './queryUsernameExists';
+export { queryWidExists, QueryWidExistsResult } from './queryWidExists';
 export { remove } from './remove';
 export { reportContact, ReportContactResult } from './reportContact';
 export { save } from './save';

package/dist/contact/functions/queryExists.d.ts

@@ -13,37 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Wid } from '../../whatsapp';
-export interface QueryExistsResult {
-    wid: Wid;
-    biz: boolean;
-    bizInfo?: {
-        verifiedName?: {
-            isApi: boolean;
-            level: string;
-            name: string;
-            privacyMode: any;
-            serial: string;
-        };
-    };
-    disappearingMode?: {
-        duration: number;
-        settingTimestamp: number;
-    };
-    status?: string;
-    lid?: Wid;
-}
-/**
- * Check if the number exists and what is correct ID
- *
- * This help to identify numbers with nine digit in Brazil
- *
- * @example
- * ```javascript
- * const result = await WPP.contact.queryExists('[number]@c.us');
- * console.log(result.wid); // Correct ID
- * ```
- *
- * @category Contact
- */
-export declare function queryExists(contactId: string | Wid): Promise<QueryExistsResult | null>;
+/** @deprecated Use QueryWidExistsResult instead */
+export type { QueryWidExistsResult as QueryExistsResult } from './queryWidExists';
+/** @deprecated Use queryWidExists instead */
+export { queryWidExists as queryExists } from './queryWidExists';

package/dist/contact/functions/queryUsernameExists.d.ts

@@ -0,0 +1,61 @@
+/*!
+ * 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';
+export interface QueryUsernameExistsResult {
+    wid: Wid;
+    biz: boolean;
+    bizInfo?: {
+        verifiedName?: {
+            isApi: boolean;
+            level: string;
+            name: string;
+            privacyMode: any;
+            serial?: string;
+        };
+    };
+    username?: string;
+    wasUpdated: boolean;
+    isUsernameSearch: true;
+}
+export interface QueryUsernameExistsKeyRequired {
+    keyRequired: true;
+    username?: string;
+    isUsernameSearch: true;
+}
+/**
+ * Check if a WhatsApp username (@username) exists
+ *
+ * Some accounts protect their username with a PIN. When the account has PIN
+ * protection enabled, this function returns `{ keyRequired: true }` instead of
+ * contact info. Pass the numeric PIN as `key` to unlock the result.
+ *
+ * @example
+ * ```javascript
+ * // Basic lookup
+ * const result = await WPP.contact.queryUsernameExists('someusername');
+ * if (result && 'keyRequired' in result) {
+ *   // Username is PIN-protected — prompt the user for the PIN
+ * } else if (result) {
+ *   console.log(result.wid); // The contact's WID
+ * }
+ *
+ * // With PIN
+ * const result = await WPP.contact.queryUsernameExists('someusername', '1234');
+ * ```
+ *
+ * @category Contact
+ */
+export declare function queryUsernameExists(username: string, key?: string): Promise<QueryUsernameExistsResult | QueryUsernameExistsKeyRequired | null>;

package/dist/contact/functions/queryWidExists.d.ts

@@ -0,0 +1,51 @@
+/*!
+ * Copyright 2021 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';
+export interface QueryWidExistsResult {
+    wid: Wid;
+    biz: boolean;
+    bizInfo?: {
+        verifiedName?: {
+            isApi: boolean;
+            level: string;
+            name: string;
+            privacyMode: any;
+            serial?: string;
+        };
+    };
+    disappearingMode?: {
+        duration: number;
+        settingTimestamp: number;
+    };
+    status?: string;
+    lid?: Wid;
+    username?: string;
+}
+/**
+ * Check if the wid (phone number or LID) exists on WhatsApp
+ *
+ * This helps to identify numbers with nine digit in Brazil.
+ * Results are cached via ContactStore (persistent) and a 5-min in-memory cache.
+ *
+ * @example
+ * ```javascript
+ * const result = await WPP.contact.queryWidExists('[number]@c.us');
+ * console.log(result.wid); // Correct ID
+ * ```
+ *
+ * @category Contact
+ */
+export declare function queryWidExists(contactId: string | Wid): Promise<QueryWidExistsResult | null>;

package/dist/eventEmitter/eventTypes.d.ts

@@ -19,16 +19,16 @@ import { ChatEventTypes } from '../chat/events/eventTypes';
 import { ConfigEventTypes } from '../config/eventTypes';
 import { ConnEventTypes } from '../conn/events/eventTypes';
 import { GroupEventTypes } from '../group/events/eventTypes';
+import { LoaderEvents } from '../loader/eventTypes';
 import { OrderEventTypes } from '../order/events/eventTypes';
 import { StatusEventTypes } from '../status/events/eventTypes';
-import { WebpackEvents } from '../webpack/eventTypes';
 export { BlocklistEventTypes } from '../blocklist/events/eventTypes';
 export { CallEventTypes } from '../call/events/eventTypes';
 export { ChatEventTypes } from '../chat/events/eventTypes';
 export { ConfigEventTypes } from '../config/eventTypes';
 export { ConnEventTypes } from '../conn/events/eventTypes';
 export { GroupEventTypes } from '../group/events/eventTypes';
+export { LoaderEvents } from '../loader/eventTypes';
 export { OrderEventTypes } from '../order/events/eventTypes';
 export { StatusEventTypes } from '../status/events/eventTypes';
-export { WebpackEvents } from '../webpack/eventTypes';
-export type EventTypes = BlocklistEventTypes & CallEventTypes & ChatEventTypes & ConfigEventTypes & ConnEventTypes & GroupEventTypes & OrderEventTypes & StatusEventTypes & WebpackEvents;
+export type EventTypes = BlocklistEventTypes & CallEventTypes & ChatEventTypes & ConfigEventTypes & ConnEventTypes & GroupEventTypes & OrderEventTypes & StatusEventTypes & LoaderEvents;