whalibmob 5.5.56 → 5.5.59

package/README.md

@@ -3,9 +3,35 @@
 
 ##
 
+> [!IMPORTANT]
+> new repository whalibmob It will be maintained at the https://github.com/Kunboruto50/whalibmob.git Since I lost the Kunboruto20 account, whalibmob will be maintained and rewritten by me soon because I know that many functions in whalibmob no longer work after the WhatsApp mobile protocol change, these days I will take care of whalibmob, all good friends Fun enjoyable for all c
+
+
+CONTACT ME ON TELEGRAM  IF YOU WANT TO WORK WITH ME AND IF YOU HAVE PROBLEM WITH WHALIBMOB : @borutokun240
+
+TELEGRAM NEW WHALIBMOB CHANNEL JOIN HERE https://t.me/+jWzq-I9o0Xc1Mzc8
+
+
+
+
+
 > [!CAUTION]
 > Use a dedicated phone number with this library. Connecting with a number that is already active on a real device will cause WhatsApp to log that device out.
 
+> [!CAUTION] 
+> Whalibmob now It needs to be rewritten because WhatsApp mobile and has changed the protocol lately and now whalibmob is in testing and some updates by Me Any pull request is accepted. 
+
+
+> [!IMPORTANT] 
+> If you like what I do and want to support me I can leave you here my Crypto usdc address for any donation and support any Small donation is accepted because the WhatsApp protocol changes very often : "0x8AD64F47a715eC24DeF193FBb9aC64d4E857f0f3"
+ 
+Usdc ethereum network.
+
+
+
+
+
+
 > [!IMPORTANT]
 > This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp or any of its subsidiaries or affiliates. "WhatsApp" and related names are registered trademarks of their respective owners. Use at your own discretion.
 
@@ -100,11 +126,24 @@ npm install -g whalibmob
 - [Library API](#library-api)
   - [Connecting Account](#connecting-account)
     - [Register a New Number](#register-a-new-number)
+    - [Device Attestation with Frida (optional)](#device-attestation-with-frida-optional)
     - [Connect](#connect)
   - [Saving & Restoring Sessions](#saving--restoring-sessions)
+  - [Signal Store Utilities](#signal-store-utilities)
+    - [makeCacheableSignalKeyStore](#makecacheablesignalkeystore)
+    - [addTransactionCapability](#addtransactioncapability)
+    - [assertMeId](#assertmeid)
+    - [initAuthCreds](#initauthcreds)
   - [Handling Events](#handling-events)
     - [Example to Start](#example-to-start)
     - [All Events](#all-events)
+  - [History Sync](#history-sync)
+    - [How It Works](#how-history-sync-works)
+    - [Listening to History Sync Events](#listening-to-history-sync-events)
+    - [Persistent Files Written to Disk](#persistent-files-written-to-disk)
+    - [Reading the History Store](#reading-the-history-store)
+    - [tcToken — Error 463 Defense](#tctoken--error-463-defense)
+    - [What Is Automatic vs What You Need to Do](#what-is-automatic-vs-what-you-need-to-do)
   - [Receiving Media](#receiving-media)
   - [Sending Messages](#sending-messages)
     - [Text Message](#text-message)
@@ -234,33 +273,112 @@ if (result.status === 'ok') {
 }
 ```
 
-#### Device attestation (Frida)
+### Device Attestation with Frida (optional)
 
-WhatsApp gates registration behind **device attestation** — a Google **Play
-Integrity** verdict on Android and Apple **App Attest** on iOS. Those tokens can
-only be minted on a genuine device, which is why datacenter registrations are
-often refused.
+WhatsApp's registration servers score every `/code` and `/register` request on how
+much it looks like a genuine phone. A real device proves itself with a hardware
+attestation token — **Play Integrity** plus a **Keystore**-signed request on
+Android, **App Attest** on iOS. whalibmob sends these fields on every registration
+request, but it can only fill them with real values if it can talk to an actual
+device.
 
-whalibmob ships the same Frida middleware [Auties00/Cobalt](https://github.com/Auties00/Cobalt)
-uses, under [`frida/`](frida/README.md). The scripts run on a rooted/jailbroken
-device and expose a local HTTP server (port `1119` = WhatsApp, `1120` = Business);
-whalibmob then attaches `gpia` (Play Integrity), the `H=` Keystore signature and
-the `Authorization` certificate chain to every `/exist`, `/code` and `/register`
-request — exactly like a real device.
+This repository ships a **`frida/` folder** containing the on-device scripts that
+produce those tokens. It is entirely **optional**: with no device attached,
+whalibmob sends the same empty attestation fields a real phone sends when its
+integrity check fails, and registration still works. Attaching a device raises the
+trust score, which helps when you keep hitting `no_routes` or block screens.
 
-It is **off by default**. Enable it once the device server is reachable:
+> Requires a **rooted Android phone** or a **jailbroken iPhone** with the official
+> WhatsApp app installed from the Play Store / App Store. Sideloaded APKs do not
+> work — the attestation is bound to the store-signed build.
+
+#### What's in the folder
+
+```
+frida/
+  android/     Play Integrity + Keystore attestation server  (/integrity, /cert, /info)
+  ios/         App Attest attestation server                 (/integrity)
+```
+
+Each platform folder has its own `README.md` with the full device prerequisites.
+
+#### 1. Build the script
+
+Install [Frida](https://frida.re) on your computer, then build the bundle for your
+platform:
+
+```bash
+cd frida/android      # or: cd frida/ios
+npm install
+npm run build         # produces server_with_dependencies.js
+```
+
+#### 2. Run it on the device
+
+Make sure the Frida server is running on the phone, then attach to WhatsApp:
+
+```bash
+# Android — open WhatsApp and reach the "register a number" screen FIRST,
+# otherwise the integrity components are not loaded yet
+frida -U "WhatsApp" -l server_with_dependencies.js
+
+# iOS
+frida -U -l server_with_dependencies.js -f "net.whatsapp.WhatsApp"
+```
+
+The script starts a small HTTP server **on the phone**, listening on port `1119`
+(or `1120` if you attached to WhatsApp Business). Wait for:
+
+```
+[*] Server ready on port 1119
+```
+
+#### 3. Make the port reachable
+
+whalibmob talks to that server over plain HTTP, so the port has to be reachable
+from the machine running your bot. Over USB, forward it with adb:
+
+```bash
+adb forward tcp:1119 tcp:1119     # Android
+iproxy 1119 1119                  # iOS (libimobiledevice)
+```
+
+Alternatively, if the phone is on the same Wi-Fi, use its LAN IP directly.
+
+#### 4. Point whalibmob at it
+
+Set the host — and the port, if it isn't the default `1119`:
+
+```bash
+WA_FRIDA_HOST=127.0.0.1
+WA_FRIDA_PORT=1119        # optional; use 1120 for WhatsApp Business
+```
+
+Or in `.env`:
 
-```sh
-# .env
-WA_FRIDA_ATTESTATION=1
-WA_FRIDA_HOST=127.0.0.1        # e.g. after: adb forward tcp:1119 tcp:1119
-WA_FRIDA_PORT=1119            # 1119 WhatsApp, 1120 Business
-# WA_FRIDA_OPTIONAL=1          # don't fail a request if the server is down
 ```
+WA_FRIDA_HOST=127.0.0.1
+WA_FRIDA_PORT=1119
+```
+
+That is the whole integration. On the next `requestSmsCode()` / `verifyCode()`
+call, whalibmob queries the device automatically and attaches the attestation to
+the request:
+
+| Platform | Fields it fills                                                    |
+|----------|--------------------------------------------------------------------|
+| Android  | `gpia` (Play Integrity) in the body, plus a Keystore signature and certificate chain on the request |
+| iOS      | An App Attest assertion and attestation on the request              |
 
-See [`frida/README.md`](frida/README.md) for the full device setup. When the flag
-is unset, `requestSmsCode` / `verifyCode` behave exactly as before and never
-contact the device.
+Keep the Frida session open while you register. When you unset `WA_FRIDA_HOST`,
+whalibmob silently goes back to the empty-attestation path — no code changes, and
+nothing else in your bot is affected.
+
+> **Troubleshooting.** If the fields come back empty, check in this order: the
+> Frida session is still attached, the port is forwarded, and — on Android — that
+> you opened WhatsApp's registration screen at least once before attaching, since
+> the integrity components are lazy-loaded. whalibmob never fails a registration
+> because attestation is unavailable; it just falls back to empty values.
 
 ### Connect
 
@@ -295,6 +413,138 @@ await client.init('919634847671')
 > [!NOTE]
 > Each phone number uses its own session file. The library handles Signal Protocol key persistence automatically.
 
+## Signal Store Utilities
+
+`auth-utils` is a collection of optional helpers for power users who manage their own `SignalStore` instances directly (e.g. custom storage backends, multi-account servers).
+
+```js
+const {
+  makeCacheableSignalKeyStore,
+  addTransactionCapability,
+  assertMeId,
+  initAuthCreds
+} = require('whalibmob')
+```
+
+### `makeCacheableSignalKeyStore`
+
+Wraps a `SignalStore` with an in-memory NodeCache layer (5-minute TTL). All `get` calls for `sessions`, `preKeys`, `signedPreKeys`, and `identities` are served from cache on subsequent accesses. Writes invalidate the cache automatically.
+
+`useClones` is set to `false` so that `SessionRecord` objects — which carry internal state and methods — are returned by reference and never deep-cloned.
+
+The wrapper also forwards `transaction()` and `isInTransaction()` calls to the underlying store when present, making it safe to stack with `addTransactionCapability`.
+
+```js
+const { SignalStore } = require('whalibmob')
+const { makeCacheableSignalKeyStore } = require('whalibmob')
+
+const store  = new SignalStore(/* ... */)
+const cached = makeCacheableSignalKeyStore(store)
+
+// reads hit cache after first access
+const session = await cached.getSession('919634847671@s.whatsapp.net:0')
+```
+
+**When to use:** whenever your `SignalStore` is backed by a remote or disk-based store (database, Redis, file system) and you want to reduce repeated lookups for sessions that haven't changed between sends.
+
+### `addTransactionCapability`
+
+Wraps a `SignalStore` with batched-write (transaction) semantics. During a transaction all writes are buffered in memory; they are flushed to the underlying store atomically when `commit()` is called at the end of the transaction.
+
+Uses `AsyncLocalStorage` to propagate transaction context across async call chains, and a per-key-type `Mutex` with reference-counting to serialize concurrent writers safely.
+
+```js
+const { addTransactionCapability, makeCacheableSignalKeyStore } = require('whalibmob')
+
+// recommended: cache first, then transactions on top
+const base        = new SignalStore(/* ... */)
+const cached      = makeCacheableSignalKeyStore(base)
+const txnStore    = addTransactionCapability(cached)
+
+// inside a send flow
+await txnStore.transaction(async () => {
+  // all writes are buffered
+  await txnStore.setSession('919634847671@s.whatsapp.net:0', sessionRecord)
+  await txnStore.setPreKey(1, preKeyPair)
+  // commit is called automatically at the end of the transaction callback
+})
+```
+
+Stacking order matters: put `makeCacheableSignalKeyStore` below `addTransactionCapability` so that the cache always sees the committed state.
+
+**When to use:** for high-throughput servers that send to many recipients concurrently and need to batch Signal key writes into a single atomic flush per message.
+
+### `assertMeId`
+
+Validates that a store object has a registered phone number and returns the canonical `@s.whatsapp.net` JID. Throws an `Error` if the store lacks a `phoneNumber` or has `registered !== true`.
+
+```js
+const { assertMeId } = require('whalibmob')
+
+const store = loadStore(sessFile)
+
+try {
+  const jid = assertMeId(store)
+  // jid === '919634847671@s.whatsapp.net'
+  console.log('account JID:', jid)
+} catch (err) {
+  console.error('store is not registered:', err.message)
+}
+```
+
+**When to use:** as a guard before calling `client.init()` to give a clear error message when a corrupted or unregistered session file is accidentally loaded.
+
+### `initAuthCreds`
+
+Creates a fresh credential store for the given phone number. Functionally equivalent to `createNewStore` but also initialises the Baileys-compatible extra fields that the library expects for account sync: `nextPreKeyId`, `firstUnuploadedPreKeyId`, `accountSyncCounter`, `accountSettings`, and `advSecretKey`.
+
+```js
+const { initAuthCreds, saveStore } = require('whalibmob')
+const path = require('path')
+const fs   = require('fs')
+
+const phone    = '919634847671'
+const sessDir  = path.join(process.env.HOME, '.waSession')
+const sessFile = path.join(sessDir, phone + '.json')
+
+fs.mkdirSync(sessDir, { recursive: true })
+
+const store = initAuthCreds(phone)
+saveStore(store, sessFile)
+```
+
+This is the function used internally by the CLI for all new session creation. Prefer it over `createNewStore` for forward compatibility.
+
+> [!NOTE]
+> `initAuthCreds` and `createNewStore` produce equivalent stores for all current library operations. The additional fields from `initAuthCreds` are there for future-proofing and interoperability.
+
+### Recommended Stacking Pattern
+
+For a production multi-account server:
+
+```js
+const {
+  SignalStore,
+  makeCacheableSignalKeyStore,
+  addTransactionCapability,
+  initAuthCreds,
+  saveStore,
+  loadStore
+} = require('whalibmob')
+
+// 1. load or create the credential store
+let store = loadStore(sessFile) || initAuthCreds(phone)
+
+// 2. build the layered Signal key store
+const signalStore = new SignalStore(store)
+const cachedStore = makeCacheableSignalKeyStore(signalStore)
+const txnStore    = addTransactionCapability(cachedStore)
+
+// 3. pass to the client (advanced usage — most users should use WhalibmobClient directly)
+```
+
+For standard usage, `WhalibmobClient` handles all of this internally. These helpers are for advanced scenarios where you need direct control over Signal key storage.
+
 ## Handling Events
 
 whalibmob uses the EventEmitter syntax for events.
@@ -421,6 +671,261 @@ The `decoded` object shape per message type:
 { type: 'protocol', subtype: string }
 ```
 
+---
+
+## History Sync
+
+### How History Sync Works
+
+When whalibmob connects, WhatsApp automatically sends the account's chat history to the client.
+The library handles the entire pipeline **without any code from you** — you only need to listen
+to the events if you want to use the data.
+
+The full internal flow:
+
+1. WhatsApp server sends an encrypted `ProtocolMessage` (type 6) containing a `HistorySyncNotification`.
+2. The library decrypts it via Signal Protocol.
+3. `HistorySyncHandler` downloads the encrypted blob from WhatsApp's CDN (`mmg.whatsapp.net`), or reads the inline payload if the server embedded it directly.
+4. The blob is decrypted with **AES-256-CBC** using an HKDF key derived from `"WhatsApp History Keys"`.
+5. The result is decompressed with **zlib** and decoded from **protobuf** (WAProto v2.3000.x — field numbers verified against the official proto definition).
+6. Chats, contacts, push names, LID↔PN mappings, and **tcTokens** are merged into the disk store.
+7. tcTokens from history are seeded into `TcTokenStore` in memory so the first outbound DM after reconnect already carries a valid `<tctoken>` node (prevents error 463 on cold start).
+8. The `history_sync` event fires with a summary of what was received.
+
+History arrives in **multiple chunks**. Each chunk fires one `history_sync` event. The first chunk (sync type `INITIAL_BOOTSTRAP`) is usually the largest and carries the most recent conversations.
+
+### Listening to History Sync Events
+
+```js
+const { WhalibmobClient } = require('whalibmob')
+const path = require('path')
+
+const client = new WhalibmobClient({
+  sessionDir: path.join(process.env.HOME, '.waSession')
+})
+
+// history_sync fires once per history chunk — may fire multiple times on first connect
+client.on('history_sync', result => {
+  console.log('History sync chunk received:')
+  console.log('  type    :', result.syncTypeName)   // e.g. 'INITIAL_BOOTSTRAP', 'RECENT', 'FULL'
+  console.log('  progress:', result.progress)        // 0-100 server-reported
+  console.log('  chunk   :', result.chunkOrder)
+  console.log('  chats   :', result.chats.length)
+  console.log('  contacts:', result.contacts.length)
+  console.log('  pushNames:', (result.pushNames || []).length)
+})
+
+// history_sync_error fires if a chunk fails to download or decrypt
+client.on('history_sync_error', ({ err, notification }) => {
+  console.error('History sync failed:', err.message)
+  console.error('  syncType:', notification.syncType)
+})
+
+await client.init('919634847671')
+```
+
+The `result` object shape emitted by `history_sync`:
+
+```js
+{
+  syncType:      number,   // HistorySyncType enum value
+  syncTypeName:  string,   // 'INITIAL_BOOTSTRAP' | 'RECENT' | 'FULL' | 'PUSH_NAME' | 'NON_BLOCKING_DATA' | 'ON_DEMAND'
+  progress:      number,   // 0-100, server-reported progress
+  chunkOrder:    number,   // chunk sequence number
+  chats: [                 // one entry per conversation in this chunk
+    {
+      id:               string,   // chat JID e.g. '919634847671@s.whatsapp.net' or '120363...@g.us'
+      name:             string,   // display name (may be undefined for unknown contacts)
+      unreadCount:      number,
+      lastMsgTimestamp: number,   // Unix seconds
+      messageCount:     number    // number of messages in this chunk for this chat
+    }
+  ],
+  contacts: [              // one entry per contact discovered in this chunk
+    {
+      id:       string,
+      name:     string,
+      username: string,    // WhatsApp username if set
+      pnJid:    string,    // phone-number JID e.g. '919634847671@s.whatsapp.net'
+      lidJid:   string     // LID JID e.g. '112345678901234@lid'
+    }
+  ],
+  pushNames:     Array,    // push-name entries { id, pushname }
+  lidPnMappings: Array,    // LID<->PN mapping entries { lidJid, pnJid }
+  merged:        object    // raw merged history store (see Reading the History Store below)
+}
+```
+
+Sync type values:
+
+| `syncTypeName` | When it fires |
+|---|---|
+| `INITIAL_BOOTSTRAP` | First connect — most recent conversations |
+| `RECENT` | Reconnect after a short offline period |
+| `FULL` | Full historical sync (older messages) |
+| `PUSH_NAME` | Contact name updates only |
+| `NON_BLOCKING_DATA` | Background low-priority data |
+| `ON_DEMAND` | Explicitly requested by the client |
+
+### Persistent Files Written to Disk
+
+The library automatically writes these files to `sessionDir` per account. You do not need to create or manage them.
+
+| File | Contents |
+|---|---|
+| `<phone>.history.json` | Chats, contacts, push names, LID↔PN mappings, tcTokens |
+| `<phone>.messages.json` | Flat map of `msgId → message metadata` |
+| `<phone>.appStateKeys.json` | App-state sync keys (used for app-state patch decryption) |
+| `<phone>.tctoken.json` | Trusted-contact token store (tcToken per contact JID) |
+
+### Reading the History Store
+
+After history sync completes you can read the on-disk files directly:
+
+```js
+const fs   = require('fs')
+const path = require('path')
+
+const sessDir = path.join(process.env.HOME, '.waSession')
+const phone   = '919634847671'
+
+// ── Read chats ────────────────────────────────────────────────────────────────
+const histPath = path.join(sessDir, phone + '.history.json')
+const hist     = JSON.parse(fs.readFileSync(histPath, 'utf8'))
+
+// List all chats sorted by last message time
+const chats = Object.values(hist.chats)
+  .sort((a, b) => (b.lastMsgTimestamp || 0) - (a.lastMsgTimestamp || 0))
+
+for (const chat of chats.slice(0, 10)) {
+  console.log(chat.id, '|', chat.name || '(unknown)', '|', chat.unreadCount, 'unread')
+}
+
+// ── LID ↔ PN lookup ───────────────────────────────────────────────────────────
+// Look up LID JID from phone number JID
+const myLid = hist.pnLidMap['919634847671@s.whatsapp.net']
+console.log('LID:', myLid)   // e.g. '112345678901234@lid'
+
+// Reverse: phone number JID from LID
+const myPn = hist.lidPnMap[myLid]
+console.log('PN:', myPn)
+
+// ── Read message metadata ─────────────────────────────────────────────────────
+const msgPath = path.join(sessDir, phone + '.messages.json')
+const msgs    = JSON.parse(fs.readFileSync(msgPath, 'utf8'))
+const msgList = Object.values(msgs).sort((a, b) => (b.timestamp || 0) - (a.timestamp || 0))
+console.log('Total messages indexed:', msgList.length)
+console.log('Latest:', msgList[0])
+```
+
+`hist.chats` schema per chat entry:
+
+```js
+{
+  id:                     string,   // JID
+  name:                   string,
+  displayName:            string,
+  unreadCount:            number,
+  lastMsgTimestamp:       number,   // Unix seconds
+  messageCount:           number,   // total messages indexed from history
+  ephemeralExpiry:        number,   // disappearing messages timer in seconds, if set
+  archived:               boolean,
+  pinned:                 number,   // pin sort order (0 = not pinned)
+  tcToken:                string,   // base64 — trusted-contact token (used internally by the library)
+  tcTokenTimestamp:       number,   // Unix seconds — when the token was issued by the server
+  tcTokenSenderTimestamp: number    // Unix seconds — sender-side issuance timestamp for 7-day bucket dedup
+}
+```
+
+`msgs` schema per message entry:
+
+```js
+{
+  id:        string,   // WhatsApp message ID
+  chatId:    string,   // JID of the conversation
+  fromMe:    boolean,
+  fromJid:   string,   // sender JID
+  timestamp: number,   // Unix seconds
+  pushName:  string,   // display name of sender at send time
+  status:    number    // 0=error 1=pending 2=server 3=delivered 4=read 5=played
+}
+```
+
+### tcToken — Error 463 Defense
+
+> [!IMPORTANT]
+> This section is informational. The entire tcToken lifecycle is **fully automatic**.
+> You do not need to write any code for it.
+
+WhatsApp counts every outbound DM sent **without** a `<tctoken>` node as an anonymous "reach-out" event. Once enough such events accumulate the server enforces a time-based **Reach-out Time-lock** and returns error `463` (`NackCallerReachoutTimelocked`), blocking all outbound messages and calls for a period.
+
+whalibmob implements the full lifecycle to prevent this:
+
+| Step | What the library does automatically |
+|---|---|
+| **History seed** | On every history sync chunk, `tcToken` bytes are extracted from each conversation in the protobuf and loaded into `TcTokenStore` in memory. The first send after reconnect already has a valid token ready — no 463 risk on cold start. |
+| **Attach on send** | Before dispatching any DM, `MessageSender` looks up the token for the recipient JID, checks it has not expired (28-day rolling window), and pushes a `<tctoken>` child node into the message stanza. |
+| **Proactive issuance** | After each successful DM send, the library fires a `<iq type='set' xmlns='privacy'>` requesting a fresh token for that JID from the server — once per 7-day bucket, deduplicated in-flight. |
+| **Incoming notification** | When a contact starts a new conversation, WhatsApp pushes a `<notification type='privacy_token'>`. The library catches it in `_handlePrivacyTokenNotification` and stores the token immediately. |
+| **Identity change re-issue** | When decrypting a `pkmsg` (new Signal session from peer), the library calls `_reissueTcTokenAfterIdentityChange` to re-issue the token for the new session. |
+| **Error 463 recovery** | If a send fails with error 463, the library issues a fresh token, waits for the server response, and automatically retries the same message with the new token attached. |
+| **Expiry** | Tokens use a 4-bucket rolling window (4 × 7 days = 28-day TTL). Expired tokens are cleared before the send and a fresh one is requested proactively. |
+
+Token storage uses the **LID JID** of the contact (e.g. `112345678901234@lid`) as the key — never the phone-number JID — matching WhatsApp's internal convention.
+
+### What Is Automatic vs What You Need to Do
+
+**Everything in the "Automatic" column requires zero code from you.**
+
+| Feature | Automatic | Notes |
+|---|---|---|
+| Download history blob from CDN | ✅ | |
+| Decrypt history blob (AES-256-CBC + HKDF) | ✅ | |
+| Decompress zlib | ✅ | |
+| Decode protobuf (WAProto v2.3000.x) | ✅ | Field numbers verified against official proto |
+| Persist chats / contacts / push names | ✅ | Written to `<phone>.history.json` |
+| Persist message metadata | ✅ | Written to `<phone>.messages.json` |
+| Persist app-state sync keys | ✅ | Written to `<phone>.appStateKeys.json` |
+| Seed tcTokens into memory on connect | ✅ | Prevents error 463 on first send after reconnect |
+| Attach tcToken to every outbound DM | ✅ | |
+| Issue fresh tcTokens after each send | ✅ | Once per 7-day bucket per contact |
+| Handle incoming `privacy_token` notifications | ✅ | |
+| Re-issue tcToken after peer identity change | ✅ | |
+| Recover from error 463 with automatic retry | ✅ | |
+| Populate in-memory LID↔PN maps | ✅ | |
+| Listen to `history_sync` event | 🔵 Optional | Only if your app needs to react to history data |
+| Read `<phone>.history.json` | 🔵 Optional | Only if your app needs chat/contact data at rest |
+| Read `<phone>.messages.json` | 🔵 Optional | Only if your app indexes messages |
+
+**Minimum working integration — history sync, tcTokens, and error-463 defense all active with zero extra code:**
+
+```js
+const { WhalibmobClient } = require('whalibmob')
+const path = require('path')
+
+const client = new WhalibmobClient({
+  sessionDir: path.join(process.env.HOME, '.waSession')
+})
+
+// History sync, tcToken seeding, error-463 defense, and all disk persistence
+// happen automatically. Add the listeners below only if your app needs the data.
+
+client.on('history_sync', result => {
+  // Optional — fires once per chunk (multiple times on first connect)
+  console.log('[', result.syncTypeName, ']',
+    result.chats.length, 'chats,',
+    result.contacts.length, 'contacts')
+})
+
+client.on('history_sync_error', ({ err }) => {
+  // Optional — log failures (library continues working even if a chunk fails)
+  console.error('History chunk failed:', err.message)
+})
+
+await client.init('919634847671')
+```
+
+
 ## Receiving Media
 
 When a media message arrives, `msg.decoded` contains a CDN `url` and a `mediaKey`.
@@ -2317,43 +2822,6 @@ These variables override individual fields on top of the selected profile:
 | `WA_VERSION` | Pin the WhatsApp version (e.g. `2.24.13.80`). Skips the live store fetch. |
 | `WA_STATIC_TOKEN` | Override the static token used in registration token computation. |
 
-### SIM & Locale Overrides
-
-During registration the library derives `sim_mcc`, `sim_mnc`, `lg` and `lc` from the
-country code of the number being registered, so the request looks like a SIM from
-that country. Override them when the guessed operator is wrong for your number
-(MVNOs, ported numbers, VoIP ranges):
-
-| Variable | Description |
-|---|---|
-| `WA_SIM_MCC` | Mobile Country Code (e.g. `262` for Germany) |
-| `WA_SIM_MNC` | Mobile Network Code (e.g. `01` for Telekom) |
-| `WA_LG` | Language tag, ISO 639-1 (e.g. `de`) |
-| `WA_LC` | Country tag, ISO 3166-1 alpha-2 (e.g. `DE`) |
-| `WA_PUSH_TOKEN` | APNS/FCM push token to include on the `/code` request. Only sent when set. |
-| `WA_PUSH_CODE` | Silent-push verification code to include on the `/code` request. Only sent when set. |
-
-### Proxy (SOCKS5 / Tor)
-
-WhatsApp routinely refuses registration from datacenter and VPS IPs — that is the
-most common cause of `reason: "no_routes"` and of security blocks. Route
-registration traffic through a residential or mobile proxy:
-
-```sh
-npm install socks
-export TOR_PROXY=socks5://127.0.0.1:9050
-# with credentials:
-export TOR_PROXY=socks5://user:pass@proxy.example.com:1080
-```
-
-| Variable | Description |
-|---|---|
-| `TOR_PROXY` | SOCKS4/SOCKS5 proxy URL for registration traffic. Supports `user:pass@`. |
-| `SOCKS_PROXY` | Alias for `TOR_PROXY`. |
-
-`socks` is an optional dependency: it is only required when one of these variables
-is set, so installs without a proxy are unaffected.
-
 ## License
 
 MIT