How sohunn/whatsbulk works
Project Type & Purpose
• The project is a simple Node.js library written in TypeScript. Its purpose is to automate the process of sending bulk messages on WhatsApp by simulating the WhatsApp web interface.
• The README makes it clear that it is designed to be used as a library—not a full-stack application—with a focus on automating WhatsApp web actions using a provided HTML selector.
Analyzing the File Structure
• The project files include key configuration files for linting (.eslintrc, .eslintignore), TypeScript (tsconfig.json), and package management (package.json, package-lock.json).
• The source code in the src/ directory includes:
• BulkMessenger.ts – likely contains the core logic for sending messages in bulk.
• index.ts – probably exposed as the main entry point when the package is required.
• types.ts – defines TypeScript types such as BulkMessengerConfig and BulkMessengerResults.
• The file structure indicates a small, tightly focused library with clearly defined responsibilities.
Extracting Architectural Insights from the README
• The README explains that the BulkMessenger library provides a configuration-driven API, where you pass in an array of phone numbers, a message, and an HTML selector.
• The library initiates by opening a WhatsApp web session (requiring an initial QR-based login) and then iterates over the phone numbers.
• It fires events (message, error, end) to notify the calling code about the success or failure of each messaging attempt.
• The library uses timing configurations (intervals and selector wait timeouts) to control interactions.
Main Components
a. User Application Code:
• Represents the code that imports and uses the BulkMessenger library.
• Shows configuration objects and event listeners (for message, error, end).
b. BulkMessenger Component:
• The core library class (BulkMessenger) encapsulates the business logic.
• It processes the configuration, manages iteration over numbers, and handles delays (via interval and timeout settings).
• Contains an event emitter to signal status updates back to the user code.
c. WhatsApp Web Interface:
• Represents the external WhatsApp web session the library controls.
• Includes a browser automation layer where the library interacts with the WhatsApp webpage (waiting for the provided HTML selector).
• Initial login authentication process (triggered on the first run) and subsequent reuse of class names until logout.
d. Event Manager:
• Although integrated within BulkMessenger, this component is important since it routes events (successful message sending, errors, and completion) to the user-defined callbacks.
Relationships & Data Flow
• The User Application invokes BulkMessenger by passing in a configuration.
• BulkMessenger initiates a WhatsApp web session (if not already logged in) and “watches” for the HTML element (using the provided selector) to ensure that WhatsApp is ready for interaction.
• For each phone number:
• BulkMessenger sends the message.
• Event triggers are emitted: “message” on success, “error” on failure.
• After processing all numbers, an “end” event is emitted with a results object detailing the successes and failures.
Architectural Patterns & Principles
• The library follows an event-driven design, making heavy use of Node.js’s event emitter pattern.
• It abstracts the complexities of web automation within a single component (BulkMessenger), enforcing separation of concerns.
• The design includes configurable timing parameters, displaying a focus on robustness when interfacing with an external service (WhatsApp web).