baileys-antiban 3.8.5 → 3.8.7

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.7] - 2026-05-14
+
+### Added
+- **`baileys-antiban patch` CLI command** — for frameworks that create the Baileys socket internally (OpenClaw `@openclaw/whatsapp`, custom ESM loaders) and don't expose a `socket:ready` hook. Automatically locates the Baileys install, detects CJS vs ESM output format, backs up the original file, and injects a `wrapSocket()` call around `makeWASocket`. Idempotent — safe to re-run after plugin updates. Pairs with a `postinstall` npm script for zero-maintenance re-patching.
+  - Auto-discovers Baileys in `node_modules/@openclaw/whatsapp/node_modules/baileys`, `node_modules/baileys`, `node_modules/@whiskeysockets/baileys`, and parent directories.
+  - `--path <dir>` — explicit Baileys directory override.
+  - `--preset conservative|moderate|aggressive` — antiban profile (default: `conservative`).
+  - `--min-delay` / `--max-delay` — override delay range in ms (default 1500–4000).
+  - `--no-typing` — disable typing indicators.
+  - `--dry-run` — preview without writing files.
+  - `--force` — re-patch even if already patched.
+  - Runtime config via env: `ANTIBAN_PRESET`, `ANTIBAN_MIN_DELAY`, `ANTIBAN_MAX_DELAY`, `ANTIBAN_TYPING`.
+- **`baileys-antiban unpatch` CLI command** — restores a patched file from its `.antiban-backup` or strips the patch block in-place if backup is missing.
+
+## [3.8.6] - 2026-05-14
+
+### Fixed
+- **CJS build for NestJS / CommonJS consumers.** Adds `dist/cjs/` output compiled with `module: CommonJS`, a `{"type":"commonjs"}` package marker injected at build time, and an `exports["require"]` condition so `require('baileys-antiban')` now resolves cleanly. Previously CommonJS callers hit `ERR_PACKAGE_PATH_NOT_EXPORTED` or `ERR_REQUIRE_ESM`.
+- **`messageRecovery` persistence load in ESM context.** `loadPersistence()` previously called `require('fs')` which is not defined in native ESM scope, throwing `ReferenceError` at runtime whenever `persistPath` was configured. Fixed by using static `import { existsSync, readFileSync } from 'node:fs'` at module top level.
+- **`messageRecovery` doc comment.** Placeholder `issues/XXX` issue reference updated to `issues/2491` (deaf-session / silent message loss tracker).
+
+### Changed
+- Removed unused `jest`, `@types/jest`, and `ts-jest` devDependencies (test runner uses `tsx` directly; `vitest` retained as future framework).
+- **Docs: ESM plugin-framework integration.** Added troubleshooting section to README covering `wrapSocket()` as the correct integration point for OpenClaw, custom ESM loaders, and other plugin frameworks that use native ESM. Documents why `Module._load` interception does not work with ESM and how to set up `ev.process` + `ev.on` fallback correctly.
+
 ## [3.8.5] - 2026-05-09
 
 ### Added

package/README.md

@@ -1045,6 +1045,84 @@ const antiban = new AntiBan({
 });
 ```
 
+### Using inside a plugin framework (OpenClaw, custom ESM loaders, etc.)
+
+`baileys-antiban` is a **pure ESM package**. `wrapSocket()` is the correct integration point — it works in any ESM or CJS context without patching Baileys directly.
+
+If your framework (e.g. OpenClaw's WhatsApp plugin) uses native ESM, **do not attempt `Module._load` interception** — it only intercepts CJS modules and silently does nothing for ESM imports.
+
+Correct approach — wrap the socket after it's created, regardless of how it was imported:
+
+```typescript
+import { makeWASocket } from 'baileys';        // or however your framework exposes it
+import { wrapSocket } from 'baileys-antiban';
+
+const rawSock = makeWASocket({ ... });
+const sock = wrapSocket(rawSock);              // drop-in — use sock everywhere
+```
+
+If your framework creates the socket internally and only exposes it via a callback or event, wrap it at that point:
+
+```typescript
+// OpenClaw / plugin pattern
+framework.on('socket', (rawSock) => {
+  const sock = wrapSocket(rawSock);
+  // use sock from here on
+});
+```
+
+**If your framework creates the socket with no event or callback exposed** (common in tightly-integrated plugins), use the `patch` CLI command — see [CLI: patch command](#cli-patch-command) below.
+
+> **Note:** If you install/update the Baileys package or plugin via a package manager, `wrapSocket()` survives the update untouched. Patching Baileys source directly (as a workaround) will be reset by any reinstall — use the `patch` command to automate re-patching.
+
+---
+
+### CLI: patch command
+
+For plugin frameworks where `makeWASocket` is called internally and no socket hook is exposed (e.g. OpenClaw `@openclaw/whatsapp`), the `patch` command modifies the installed Baileys package to inject `wrapSocket()` automatically.
+
+```bash
+# Auto-detect Baileys location + apply patch
+npx baileys-antiban patch
+
+# OpenClaw: Baileys is nested inside the plugin
+npx baileys-antiban patch --path ./node_modules/@openclaw/whatsapp/node_modules/baileys
+
+# Custom profile
+npx baileys-antiban patch --preset moderate --min-delay 1000 --max-delay 3000
+
+# Preview without writing (dry run)
+npx baileys-antiban patch --dry-run
+
+# Restore original
+npx baileys-antiban unpatch --file ./node_modules/baileys/lib/socket/index.js
+```
+
+The patch is **idempotent** — re-running it on an already-patched file is a no-op. A `.antiban-backup` file is kept alongside the patched file for safe restoration.
+
+**Auto re-patch after plugin updates** — add a `postinstall` script to your project's `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "npx baileys-antiban patch --path ./node_modules/@openclaw/whatsapp/node_modules/baileys"
+  }
+}
+```
+
+Now every `npm install` / `openclaw plugins install @openclaw/whatsapp` automatically re-applies the patch.
+
+**Runtime config via environment variables** (no re-patch needed to change settings):
+
+| Variable | Default | Description |
+|---|---|---|
+| `ANTIBAN_PRESET` | `conservative` | `conservative`, `moderate`, or `aggressive` |
+| `ANTIBAN_MIN_DELAY` | `1500` | Minimum delay between messages (ms) |
+| `ANTIBAN_MAX_DELAY` | `4000` | Maximum delay between messages (ms) |
+| `ANTIBAN_TYPING` | `true` | Enable typing indicators (`false` to disable) |
+
+---
+
 ### State not persisting across restarts
 
 Use the FileStateAdapter: