How venomlib/venom works
1. What this repo is
- Venom Bot is a Node.js library for automating WhatsApp Web through Puppeteer.
- The core architecture is split between a Node host process and a browser-injected WhatsApp Web API running inside the page context.
2. Primary runtime boundary
- The Node side owns startup, configuration, session persistence, browser lifecycle, and the public client API.
- The browser side runs a large injected script under src/lib/wapi, which talks directly to WhatsApp Web internals and the page DOM.
- Almost all messaging, chat, group, and event operations ultimately cross this boundary.
3. Public entrypoint and client surface
- The package entry points compile to dist/index.mjs, dist/index.cjs, and dist/index.d.ts.
- Public consumers call create(...), receive a Whatsapp client, and then use methods grouped by capability: sender, retriever, controls, group, profile, UI, and listeners.
- The layered API is intentionally organized so the exported client is assembled from smaller capability layers.
4. Startup and session initialization flow
- src/controllers/initializer.ts, init.ts, browser.ts, and auth.ts form the bootstrap path.
- The flow is: load config → start or connect to Chromium via Puppeteer → validate session/token files → authenticate with QR if needed → initialize WhatsApp context → expose the client.
- QR/login/status callbacks in the README map to this startup pipeline.
5. Session persistence and auth boundaries
- Session state is persisted to token folders managed by config and checked by helpers like check-token-file.
- Authentication artifacts are read/written on the Node side, while WhatsApp login state is observed in the browser context.
- This separation is important for diagramming: token storage is local filesystem state, not a remote backend.
6. Layered API composition
- The main API is built from src/api/layers/host.layer.ts upward through:
- profile.layer.ts
- sender.layer.ts
- listener.layer.ts
- retriever.layer.ts
- controls.layer.ts
- ui.layer.ts
- group.layer.ts
- business.layer.ts
- Each layer adds a domain boundary: device/profile, sending, event subscription, data retrieval, chat controls, UI actions, group operations, then higher-level business methods.
- business.layer.ts is the final exported “full client” shape.
7. Browser-injected WhatsApp API (wapi)
- src/lib/wapi contains the code bundled for injection into WhatsApp Web.
- It includes:
- functions/ for concrete operations such as send message, create group, delete messages, read chats, etc.
- listeners/ for event hooks like new messages, state changes, acknowledgements, reactions, participants, and live location.
- serializers/ for converting raw WhatsApp objects into stable library models.
- helper/ and store/ for page-context utilities and access to WhatsApp’s internal store.
- This subsystem is the “engine” that actually interacts with the WhatsApp page internals.
8. Data flow for sending and retrieval
- Outbound actions usually go: public client method → API layer → helper/serializer/conversion logic → browser-injected WAPI function → WhatsApp Web.
- Media/file operations often pass through helpers such as base64 conversion, filename/mimetype resolution, download/decrypt logic, and file cleanup.
- Inbound data follows the reverse path: WhatsApp Web event → WAPI listener → Node callback layer → typed model objects in src/api/model.
9. Events and real-time listeners
- Event handling is a first-class subsystem: src/api/layers/listener.layer.ts and src/lib/wapi/listeners coordinate message, state, ack, group, and call events.
- These listeners bridge browser events back into Node callbacks such as onMessage, onStateChange, onAck, and group participant events.
- This is effectively the repo’s real-time control plane.
10. Types, models, and contracts
- src/api/model defines the domain objects and enums for chats, messages, contacts, reactions, groups, QR codes, acknowledgements, and connection states.
- These types are shared across layers to keep the Node API, browser serialization, and user-facing callbacks aligned.
- The repo is strongly typed and ships .d.ts files for consumers.
11. Configuration and environment
- src/config holds Puppeteer and runtime options such as headless mode, browser executable path, websocket connection, proxy settings, logging, and QR behavior.
- The configuration layer is what adapts the library to local Chrome, bundled Chromium, Docker, or remote browser sessions.
- External dependencies that materially affect architecture are Node.js 18+, Puppeteer/Chromium, and optionally FFmpeg for media handling.
12. Build and packaging architecture
- The repository produces both CommonJS and ESM builds under dist/cjs and dist/esm, plus top-level package artifacts.
- src/lib/wapi is built separately from the TypeScript source, which is why there are dedicated build scripts and webpack configs under src/lib/wapi and src/lib/middleware.
- This dual-build setup matters for diagramming because there are two compile targets: library API code and browser-injected WAPI code.
13. Testing and examples
- Tests live under test/unit, with mocks for the WAPI store and page context.
- The examples/screenshot app shows a consumer runtime, but it is not the main product boundary.
- The tests validate helper logic, utility functions, and selected WAPI behavior rather than a separate backend service.
14. Architectural summary for a diagram
- Draw the repo as a Node library host that initializes Puppeteer, loads tokens, injects a browser-side WhatsApp API, and then exposes a layered typed client.
- The key boundaries are:
- filesystem session/token storage,
- Node controller/bootstrap logic,
- browser-injected WhatsApp automation engine,
- event/callback return path to the consumer.
- There is no separate server or database; the main external systems are WhatsApp Web and the local browser process.
Main entry points: wapi.js WAPI bundle · sender.layer.ts Sender layer · functions/index.js WAPI functions · listeners/index.js WAPI listeners
Components 23
Node host
Startup, config, browser lifecycle, and public client assembly on the Node.js side.
- Source entry · Primary TypeScript entry that wires the library together.
src/index.ts - Initializer · Top-level bootstrap orchestration for startup and client exposure.
src/controllers/initializer.ts - Init flow · Coordinates startup steps and client creation.
src/controllers/init.ts - Browser control · Launches or connects to Chromium and manages the page context.
src/controllers/browser.ts - Auth · Handles QR login, session checks, and authentication state.
src/controllers/auth.ts - Config builder · Builds runtime and Puppeteer options for the host process.
src/config/create-config.ts
Typed API
Layered client surface and shared domain contracts.
- Host layer · Base client layer that anchors the layered API composition.
src/api/layers/host.layer.ts - Profile layer · Adds host and profile/device capability methods.
src/api/layers/profile.layer.ts - Sender layer · Adds outbound messaging and media sending capabilities.
src/api/layers/sender.layer.ts - Retriever layer · Adds chat, contact, and message retrieval methods.
src/api/layers/retriever.layer.ts - Controls layer · Adds chat state and control operations.
src/api/layers/controls.layer.ts - Group layer · Adds group administration and membership operations.
src/api/layers/group.layer.ts - UI layer · Adds presence, typing, and interface actions.
src/api/layers/ui.layer.ts - Listener layer · Bridges browser events back into Node callbacks.
src/api/layers/listener.layer.ts - Full client · Final exported client shape assembled from all layers.
src/api/layers/business.layer.ts - Models · Shared typed domain objects and enums used across the API.
src/api/model/index.ts
Browser WAPI
Injected WhatsApp Web engine running inside the page context.
- WAPI bundle · Injected browser-side WhatsApp automation bundle.
src/lib/wapi/wapi.js - WAPI functions · Core page-context operations for sending, retrieval, groups, and media.
src/lib/wapi/functions/index.js - WAPI listeners · WhatsApp Web event hooks for messages, acknowledgements, groups, and state.
src/lib/wapi/listeners/index.js - Serializers · Converts raw WhatsApp objects into stable library models.
src/lib/wapi/serializers/index.js - Store access · Reads WhatsApp Web internal store objects in the page context.
src/lib/wapi/store/get-store.js
Build & dist
Packaged entrypoints and generated distribution artifacts.
- Package entry · Published ESM entrypoint for consumers.
dist/index.mjs - Middleware · Runtime middleware used by the packaged browser-side integration.
src/lib/middleware/middleware.ts
Connections 27
- Package entry → Source entry: packages · Published artifact corresponds to the source entry.
- Source entry → Initializer: starts · Entry point hands off to bootstrap orchestration.
- Initializer → Config builder: loads config · Bootstrap builds runtime configuration first.
- Initializer → Init flow: orchestrates · Initializer coordinates the main startup flow.
- Init flow → Browser control: opens browser · Startup launches or connects to Chromium through Puppeteer.
- Init flow → Auth: authenticates · Session validation and QR/login flow happen here.
- Browser control → WAPI bundle: injects · Browser controller loads the WhatsApp automation bundle into the page.
- Auth → WAPI listeners: observes state · Login/session state is confirmed from the browser context.
- Host layer → Profile layer: extends · Base layer is augmented by profile/device capability.
- Profile layer → Sender layer: extends · Layering continues into sending capabilities.
- Sender layer → Listener layer: pairs with · Outbound methods share the client surface with event subscriptions.
- Sender layer → Retriever layer: composes · Retrieval and messaging build on the same client base.
- Retriever layer → Controls layer: composes · Chat controls extend the read/query surface.
- Controls layer → UI layer: composes · Presence and interface actions sit above chat controls.
- UI layer → Group layer: composes · Group operations are layered into the full client.
- Group layer → Full client: finalizes · Business layer is the exported full client shape.
- Full client → Models: typed by · Public API methods and callbacks use shared domain contracts.
- Sender layer → WAPI functions: invokes · Outbound calls cross into browser-side WAPI functions.
- Retriever layer → WAPI functions: queries · Read operations are executed inside the injected page engine.
- Listener layer → WAPI listeners: subscribes · Node callbacks are driven by browser event hooks.
- WAPI bundle → WAPI functions: bundles · The injected bundle includes the concrete page operations.
- WAPI bundle → WAPI listeners: bundles · The injected bundle includes event listeners.
- WAPI bundle → Serializers: bundles · Serialization helpers travel with the browser engine.
- WAPI bundle → Store access: bundles · Store access helpers are part of the page-context engine.
- WAPI functions → Store access: reads · Functions depend on WhatsApp Web internal store objects.
- WAPI listeners → Serializers: emits models · Events are normalized before crossing back to Node.
- Middleware → WAPI bundle: bridges · Packaged middleware supports the browser-side integration path.