whatsapp_notifier 0.8.1 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 130b5676184b753e6329f98ead313255db4a16be9393597f4b34f38741ae9c63
-  data.tar.gz: 7c7fe4a7eb0464676d4257443fa3003e80035e938e41d690aee7282787fd962a
+  metadata.gz: 5516496d221334794f99898b801a9277c7e056971198cc7cb6577df6499c0d72
+  data.tar.gz: 2e06a216928933ba02bef20de6be794d089205effcd76ae5784d992776263fa8
 SHA512:
-  metadata.gz: 18e39291eabaa4a61e33a7a9f62a840b233320724147dc24614f740dafaa14151363a2e606943027098b42bed3dbea80db81459d1c73a38d1ad6989d0a1d2104
-  data.tar.gz: 35170c14888aa976a0eb211757e617a2237ab8e442ee75b9e319391d1737bbb75ce81d3a69802b71b9f712ab8d8731e4fd1d243123017cac05c5c686cac9830c
+  metadata.gz: 256eecd211ade964aca1453635dc0ca3a55f9d422473bf9fe26d52f793f429e4d78b6071b9906da749c1c2fd983a4ea3047f58b545a758421d9c819c55b03b4a
+  data.tar.gz: a0f2dca29b80d6d39b9d65ab7b924e31f5e4c39fcfc2ff8f0546514671ae4089e0131b30564338fc0f8dccc3d5ee1af691cf2903d272a7b565fea8fa04894882

data/README.md

@@ -1,88 +1,246 @@
-# WhatsAppNotifier
+# whatsapp_notifier
+
+[![Gem Version](https://img.shields.io/gem/v/whatsapp_notifier.svg)](https://rubygems.org/gems/whatsapp_notifier)
+[![CI](https://github.com/kshtzkr/whatsapp_notifier/actions/workflows/ci.yml/badge.svg)](https://github.com/kshtzkr/whatsapp_notifier/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.6-CC342D.svg)](whatsapp_notifier.gemspec)
+
+Add WhatsApp messaging to a Rails app with one install generator and one service
+command.
+
+The gem gives you a small Ruby API (`WhatsAppNotifier.deliver`, mailer-style
+notification classes, and paced bulk delivery) plus a bundled Bun service that
+holds the WhatsApp Web session. No Meta developer account, app review, or webhook
+configuration is required, because messages go through a linked WhatsApp Web
+session rather than the official Business API.
+
+That trade-off matters: this drives an unofficial WhatsApp Web automation
+session, so use it for consent-based, low-volume messaging and read
+[docs/bulk_messaging_policy.md](docs/bulk_messaging_policy.md) before you send at
+scale. See [How it works](#how-it-works) for the service boundary.
+
+## Table of contents
+
+- [Requirements](#requirements)
+- [How it works](#how-it-works)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Connecting a number](#connecting-a-number)
+- [Sending a message](#sending-a-message)
+- [Notification classes](#notification-classes)
+- [Bulk delivery](#bulk-delivery)
+- [Receiving messages and media](#receiving-messages-and-media)
+- [Command line](#command-line)
+- [Mounted engine routes](#mounted-engine-routes)
+- [Configuration](#configuration)
+- [Logging out](#logging-out)
+- [Testing](#testing)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Security](#security)
+- [Versioning](#versioning)
+- [License](#license)
+
+## Requirements
+
+- Ruby 2.6 or newer (the gemspec sets `required_ruby_version >= 2.6.0`; CI runs
+  on 3.2, 3.3, and 3.4).
+- Runtime gem dependencies: `logger >= 1.5` and `thor >= 1.0`.
+- Rails for the mountable engine and the install generators. The engine
+  registers a Zeitwerk inflection, so it needs Rails 6 or newer. The plain Ruby
+  API (`WhatsAppNotifier.deliver`, notification classes, bulk delivery) works
+  without Rails.
+- [Bun](https://bun.sh) to run the bundled WhatsApp Web service.
+- Chromium or Chrome reachable by the service. Puppeteer drives it; set
+  `PUPPETEER_EXECUTABLE_PATH` if the binary is not on a standard path.
+
+## How it works
+
+Two processes cooperate:
+
+1. Your Ruby or Rails app, using this gem. `WhatsAppNotifier::WebAdapter` speaks
+   JSON over HTTP to the service (default `http://127.0.0.1:3001`).
+2. The bundled service under `lib/whatsapp_notifier/services/web_automation`. It
+   runs on Bun (Hono + `whatsapp-web.js`) and drives a headless Chromium against
+   `web.whatsapp.com`. It keeps one WhatsApp Web client per `user_id` and
+   persists each session on disk so restarts reconnect without a new QR.
+
+Nothing here touches the official WhatsApp Business API. The service pairs like
+WhatsApp Web on a laptop, which is why setup needs no Meta account, and why the
+bulk-delivery guardrails exist. Point the gem at a remote service with
+`WHATSAPP_NOTIFIER_SERVICE_URL` (or `WHATSAPP_SERVICE_URL`); `https://` URLs are
+honored natively.
 
-`whatsapp_notifier` is production-ready WhatsApp messaging for Rails.
-Set it up in minutes with one install generator and one service command.
+## Installation
 
-No official WhatsApp API setup, app review, or Meta webhook configuration is required.
+Add the gem:
 
-## What You Get
+```ruby
+# Gemfile
+gem "whatsapp_notifier"
+```
 
-- Bun-powered lightweight WhatsApp Web service (embedded in the gem)
-- QR scanning and connection status APIs
-- Single message and bulk message delivery APIs
-- Mailer-like notification classes with `deliver_now` / `deliver_later`
-- Multi-user session support via `metadata[:user_id]`
+```bash
+bundle install
+```
 
-## Quick Start (60 seconds)
+Then run the install generator:
 
 ```bash
-bundle add whatsapp_notifier
 bin/rails g whatsapp_notifier:install
-bin/dev
 ```
 
-Then:
+The generator:
+
+- writes `config/initializers/whatsapp_notifier.rb`,
+- mounts the engine with `mount WhatsAppNotifier::Engine, at: "/whatsapp"`,
+- adds `whatsapp: bundle exec whatsapp_notifier service` to `Procfile.dev`,
+- adds session and service paths to `.gitignore`,
+- runs `whatsapp_notifier doctor` to check your setup.
 
-- open `/dashboard/whatsapp/qr`
-- scan QR
-- send a test message
+The gem ships no migrations, so there is no `db:migrate` step.
 
-If setup fails, run:
+Start the service alongside your app. With the `Procfile.dev` entry above,
+`bin/dev` runs it; on its own:
 
 ```bash
-bundle exec whatsapp_notifier doctor
+bundle exec whatsapp_notifier service
 ```
 
-## Installation
+The first run installs the service's dependencies with `bun install`, then
+launches it on port 3001.
+
+## Quick start
+
+```bash
+bundle add whatsapp_notifier
+bin/rails g whatsapp_notifier:install
+bin/dev
+```
+
+With the service running, connect a number (see below), then send:
 
 ```ruby
-gem "whatsapp_notifier"
+result = WhatsAppNotifier.deliver(
+  to: "+919999999999",
+  body: "Booking confirmed",
+  metadata: { user_id: current_user.id }
+)
+
+result.success? # => true
 ```
 
+If setup fails, run the diagnostics:
+
 ```bash
-bundle install
-bin/rails g whatsapp_notifier:install
+bundle exec whatsapp_notifier doctor
 ```
 
-## Scan QR and check status
+## Connecting a number
+
+Each linked number is a session keyed by `metadata[:user_id]`. Omit the key to
+use a single shared `default` session; pass `current_user.id` (or any stable id)
+for per-user sessions.
+
+Fetch the current QR and render it. The service returns a `data:` PNG URL, or
+`nil` while the client is still booting:
 
 ```ruby
-# Use current_user.id for multi-user apps; omit metadata for a default shared session.
 qr_data_url = WhatsAppNotifier.scan_qr(metadata: { user_id: current_user.id })
+# => "data:image/png;base64,..." or nil
+```
+
+Show that image, scan it from the phone (WhatsApp, Linked devices, Link a
+device), then poll the connection status until it reports authenticated:
 
+```ruby
 status = WhatsAppNotifier.connection_status(metadata: { user_id: current_user.id })
-# => { state: "...", authenticated: true/false, has_qr: true/false }
+# => { state: "AUTHENTICATED", authenticated: true, has_qr: false }
 ```
 
-## Log out (disconnect + clear session)
+The QR rotates every ~20 seconds, so re-fetch it while `has_qr` is true. Once a
+session authenticates it persists on the service, so later sends reconnect
+without a new scan.
 
-Explicitly disconnects the user and wipes their saved WhatsApp session from the
-service — including any downloaded inbound media and queued replies, which
-belong to the old pairing — so the next connect starts fresh with a new QR.
-Call this from a user-initiated "Log out WhatsApp" action — NOT from your
-app's sign-out, which should leave the WhatsApp session intact for the next
-login.
+Before sending, `session_ready?` answers the only question a sender actually
+has. It is `connection_status` reduced to a boolean, with transport failures
+treated as not-ready — an unreachable status endpoint means the service is down,
+so the send could not have succeeded either:
 
 ```ruby
-WhatsAppNotifier.logout(metadata: { user_id: current_user.id })
-# => { success: true }
+WhatsAppNotifier.session_ready?(user_id: current_user.id)
+# => true / false, never raises on a network error
 ```
 
-The mounted engine also exposes `DELETE /whatsapp/logout` for the same effect.
+A `ConfigurationError` still raises: that is a mistake in your setup, and
+answering `false` would quietly park every send behind a "session down" retry.
+
+The mounted engine exposes the same two steps as JSON endpoints
+(`GET /whatsapp/qr` and `GET /whatsapp/status`) if you prefer to build the
+pairing screen in your front end.
 
-## Send a message
+## Sending a message
 
 ```ruby
 result = WhatsAppNotifier.deliver(
   to: "+919999999999",
-  body: "Booking confirmed",
+  body: "Payment received",
   metadata: { user_id: current_user.id }
 )
+```
 
-result.success?
+`deliver` returns a `WhatsAppNotifier::Result`:
+
+| Method | Meaning |
+| --- | --- |
+| `success?` / `failure?` | delivery outcome |
+| `message_id` | WhatsApp message id from the service (a local fallback id on older services) |
+| `error_code` | machine-readable failure class on failure, `nil` on success |
+| `error_message` | human-readable failure reason |
+| `wait_seconds` | provider-requested backoff, honored by bulk delivery |
+| `metadata` | provider metadata hash |
+
+### Failure codes
+
+`error_code` is a stable symbol you can branch on. The important distinction is
+whether the message could already be on its way: retrying a send whose outcome
+is unknown may message someone twice.
+
+| Code | Meaning | Did the message go out? |
+| --- | --- | --- |
+| `:auth_required` | session logged out, or the service refused upfront | no |
+| `:not_on_whatsapp` | the number has no WhatsApp account | no |
+| `:invalid_phone` | the number is malformed | no |
+| `:recipient_unresolved` | the service could not resolve the recipient id (wedged session) | no |
+| `:service_unreachable` | the connection never opened | no |
+| `:timeout` | the request went out, the answer never came | **unknown** |
+| `:rate_limited` | the service throttled the send | **unknown** |
+| `:delivery_exception` | unclassified | **unknown** |
+
+`:delivery_exception` is the catch-all and the pre-0.9.0 value for every
+failure, so code that already keys on it keeps working. `error_message` is
+unchanged too — including the `"service request failed (401): ..."` wording —
+so a host can migrate off text fingerprints at its own pace.
+
+To attach a file, pass its URL as `metadata[:media_url]`:
+
+```ruby
+WhatsAppNotifier.deliver(
+  to: "+919999999999",
+  body: "Here is your invoice",
+  metadata: { user_id: current_user.id, media_url: invoice_url }
+)
 ```
 
-## Notifications API
+The engine also exposes `POST /whatsapp/send` with `to` (or `phone`), `message`,
+and optional `media_url`.
+
+## Notification classes
+
+Model messages as mailer-style classes. Define `#message` (and `#to`), or use a
+class-level template.
+
+Method style:
 
 ```ruby
 class LeadWhatsappNotification < WhatsAppNotifier::Notification
@@ -98,13 +256,35 @@ class LeadWhatsappNotification < WhatsAppNotifier::Notification
     { user_id: params[:user].id }
   end
 end
+
+LeadWhatsappNotification.with(lead: @lead, user: current_user).deliver_later
 ```
 
+Template style. Template variables come from the nested `params:` hash and fill
+`{{placeholders}}`:
+
 ```ruby
-LeadWhatsappNotification.with(lead: @lead, user: current_user).deliver_later
+class PaymentAlertNotification < WhatsAppNotifier::Notification
+  to "+919999999999"
+  provider :web_automation
+  template :payment_alert, "Hi {{name}}, payment {{amount}} received."
+
+  def metadata
+    { user_id: params[:user_id] }
+  end
+end
+
+PaymentAlertNotification.deliver_now(
+  params: { name: "Riya", amount: "INR 1500" },
+  user_id: 42
+)
 ```
 
-## Bulk Messaging
+`deliver_later` runs through ActiveJob (queue `:default`) when it is available in
+the host app. Without ActiveJob loaded it falls back to running inline, so the
+call still delivers.
+
+## Bulk delivery
 
 ```ruby
 messages = [
@@ -113,78 +293,187 @@ messages = [
 ]
 
 summary = WhatsAppNotifier.deliver_bulk(messages)
-summary[:success]
+# => { total: 2, success: 2, failed: 0, results: [#<Result>, #<Result>] }
 ```
 
-## Generators
+Each message accepts `to`, `body`, `metadata`, and an optional
+`idempotency_key`. The dispatcher:
+
+- paces sends with `bulk_base_delay_seconds` plus up to `bulk_jitter_seconds` of
+  random jitter,
+- rejects a batch larger than `bulk_max_recipients`,
+- retries a failed send up to `bulk_max_attempts` times, but only when its
+  `error_code` is in `bulk_retryable_error_codes`,
+- sleeps for `wait_seconds` when a result asks for backoff,
+- skips a repeated `idempotency_key` within the same run.
+
+See [docs/bulk_messaging_policy.md](docs/bulk_messaging_policy.md) for the
+guardrails and recommended limits.
+
+## Receiving messages and media
+
+The service captures both sides of each 1:1 conversation and buffers inbound
+messages per user. Drain them (at-least-once; dedupe on `message_id`):
+
+```ruby
+WhatsAppNotifier.fetch_inbound(metadata: { user_id: current_user.id })
+# => [{ from:, body:, message_id:, timestamp:, type:, ... }]
+```
 
-Install everything with one command:
+Related helpers, each keyed by the same `metadata`:
+
+- `WhatsAppNotifier.fetch_media(message_id:, metadata:)` returns
+  `{ body:, mime:, filename:, size: }`, or `nil` when the service has no copy.
+- `WhatsAppNotifier.refetch_media(message_id:, chat_id:, metadata:)` re-downloads
+  one message's media on demand.
+- `WhatsAppNotifier.delete_media(message_id:, metadata:)` drops the service's
+  copy after you have stored the bytes.
+- `WhatsAppNotifier.list_chats(metadata:)` lists the paired number's 1:1 chats.
+- `WhatsAppNotifier.fetch_history(chat_id:, limit: 50, metadata:)` replays one
+  chat's recent history.
+
+The engine also exposes `GET /whatsapp/inbound` for host apps that would rather
+pull through Rails. The `CHANGELOG.md` records when each capability landed and
+the wire-compatibility rules between gem and service versions.
+
+## Command line
+
+The `whatsapp_notifier` executable (Thor) has two commands.
 
 ```bash
-rails generate whatsapp_notifier:install
+# Start the bundled WhatsApp Web service (Bun). --port overrides the default 3001.
+bundle exec whatsapp_notifier service [--port 3001]
+
+# Validate local setup and print exact fixes.
+bundle exec whatsapp_notifier doctor
 ```
 
-If you want to eject Bun service files into your app:
+`doctor` checks that Bun is installed, that a Chromium-compatible browser is
+found (or `PUPPETEER_EXECUTABLE_PATH` is set), that the session directory is
+writable, and that the service URL is well-formed. It exits non-zero and prints
+a fix for each failed check.
+
+`service` sets `PORT`, defaults `WHATSAPP_SESSION_DIR` to a writable path under
+the app, autodetects Chromium, installs the service's dependencies on first run,
+then execs `bun index.ts`.
+
+## Mounted engine routes
+
+`whatsapp_notifier:install` mounts the engine at `/whatsapp`. Every action
+returns JSON.
+
+| Method | Path | Action | Purpose |
+| --- | --- | --- | --- |
+| GET | `/whatsapp/status` | `sessions#show` | connection state for the current user |
+| GET | `/whatsapp/qr` | `sessions#qr` | latest QR (`nil` while initializing) |
+| DELETE | `/whatsapp/logout` | `sessions#destroy` | disconnect and clear the session |
+| POST | `/whatsapp/send` | `messages#create` | send one message |
+| GET | `/whatsapp/inbound` | `messages#inbound` | drain pending inbound messages |
+
+The engine resolves the current user through
+`config.current_user_id_resolver` and can run an auth hook through
+`config.authenticate_with` (see [Configuration](#configuration)). To eject the
+Bun service source into your app instead of running it from the gem:
 
 ```bash
 rails generate whatsapp_notifier:install_service
 ```
 
-This copies the service to `whatsapp_service/` and updates `.gitignore`.
-
-## Service health probe
-
-The Bun service exposes `GET /health` for load balancer / platform probes
-(Azure, Kubernetes, uptime checks). It reads only in-memory state — it never
-creates a WhatsApp client — so it is safe to poll every few seconds:
-
-```json
-{ "ok": true, "uptime_s": 4242, "sessions": 3, "ready": 2 }
-```
-
-`sessions` is the number of clients held in memory; `ready` is how many of
-those have a fully hydrated WhatsApp Web store. Prometheus metrics live at
-`GET /metrics`.
-
-## Upgrading to 0.7.0
-
-- **If your app monkey-patches `WhatsAppNotifier::WebAdapter#request`** (a
-  common trick to bolt TLS onto the service URL): the shared JSON path now
-  also carries `DELETE` (`delete_media`) and attaches `X-WA-Token` when
-  `WHATSAPP_WEBHOOK_TOKEN` is set. A patch that only routes `POST`/`GET` or
-  drops headers will break the new media calls. Prefer retiring the patch
-  entirely — the adapter now honors `https://` service URLs natively on both
-  the JSON control plane and the binary media path (`use_ssl` follows the URL
-  scheme), so TLS no longer needs a patch.
-- **Logout now wipes stored media**: `POST /logout` removes the user's
-  downloaded inbound media along with the session dir and queued replies.
-  Fetch (and ideally `delete_media`) anything you want to keep before logging
-  a user out.
-
-## Notes
-
-- This gem uses WhatsApp Web automation. Use responsibly and follow WhatsApp policies.
-- Keep Chromium available in your runtime (or set `PUPPETEER_EXECUTABLE_PATH`).
-- Session profiles persist under `WHATSAPP_SESSION_DIR`. Careful: the
-  `whatsapp_notifier service` CLI launcher defaults it to
-  `./tmp/whatsapp_notifier/.wwebjs_auth` **relative to the current working
-  directory** (only the bare Bun service falls back to `/whatsapp_data`).
-  Production must set `WHATSAPP_SESSION_DIR` explicitly to a durable mount
-  (e.g. `/whatsapp_data`) so logins survive restarts and redeploys; the
-  service clears stale Chromium `SingletonLock` files on each launch so an
-  unclean exit can't wedge it.
-- Resilience knobs: `WHATSAPP_INIT_TIMEOUT_MS` (default 90000) recycles a client
-  that never reaches QR/READY; `WHATSAPP_UNREADY_REAP_MS` (default 1800000)
-  destroys non-ready clients idle that long (abandoned pairing screens; the
-  cleanup sweep runs every 5 minutes, so reaping lands within ~5 minutes of
-  the limit) —
-  sessions that authenticated at least once keep their on-disk dir for
-  reconnect, while a pairing that never authenticated has its credential-less
-  dir removed too, so it cannot pass the paired-session gate later; set
-  `WWEBJS_WEB_VERSION` (e.g. `2.3000.1023204887`,
-  optionally `WWEBJS_WEB_VERSION_CACHE_URL`) to pin the WhatsApp Web build so a
-  live web.whatsapp.com change can't silently break the client.
+This copies the service files to `whatsapp_service/` and updates `.gitignore`.
+
+## Configuration
+
+Configure the gem in `config/initializers/whatsapp_notifier.rb`:
+
+```ruby
+WhatsAppNotifier.configure do |config|
+  config.provider = :web_automation
+  config.web_automation_enabled = true
+  config.bulk_base_delay_seconds = 1.2
+  config.bulk_jitter_seconds = 0.4
+  config.bulk_max_recipients = 300
+end
+```
+
+The most common options and their defaults:
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `provider` | `:web_automation` | messaging backend; only `:web_automation` is supported |
+| `web_session_path` | `"tmp/whatsapp_notifier/session.json"` | where the gem stores session pointers |
+| `bulk_base_delay_seconds` | `1.0` | base pause between bulk sends |
+| `bulk_jitter_seconds` | `0.3` | random jitter added to each bulk pause |
+| `bulk_max_recipients` | `500` | largest batch `deliver_bulk` accepts |
+| `bulk_max_attempts` | `3` | attempts per message in bulk retries |
+| `authenticate_with` | `nil` | callable run as a `before_action` in the engine |
+| `current_user_id_resolver` | resolves `current_user.id` | how the engine identifies the user |
+
+The full reference (every configuration option and every service environment
+variable, with types and defaults) is in
+[docs/CONFIGURATION.md](docs/CONFIGURATION.md). For a longer Rails walk-through,
+see [docs/rails_setup.md](docs/rails_setup.md).
+
+## Logging out
+
+`logout` disconnects the user and wipes their saved WhatsApp session on the
+service, including downloaded inbound media and queued replies, so the next
+connect starts fresh with a new QR:
+
+```ruby
+WhatsAppNotifier.logout(metadata: { user_id: current_user.id })
+# => { success: true }
+```
+
+Call this from a user-initiated "Log out WhatsApp" action, not from your app's
+sign-out, which should leave the session intact for the next login. The engine
+exposes `DELETE /whatsapp/logout` for the same effect.
+
+## Testing
+
+Run the Ruby suite (SimpleCov enforces 100% line coverage):
+
+```bash
+bundle exec rspec
+```
+
+The bundled service has its own tests:
+
+```bash
+cd lib/whatsapp_notifier/services/web_automation
+bun install
+bun test
+```
+
+CI runs both jobs (`.github/workflows/ci.yml`): RSpec on Ruby 3.2–3.4 and the
+Bun service tests.
+
+## Development
+
+```bash
+git clone https://github.com/kshtzkr/whatsapp_notifier.git
+cd whatsapp_notifier
+bundle install
+bundle exec rspec
+```
+
+The gemspec requires MFA for RubyGems pushes (`rubygems_mfa_required`).
+
+## Contributing
+
+Bug reports and pull requests are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for setup, the branch and PR flow, and the
+commit style. By participating you agree to the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+Please report vulnerabilities privately. See [SECURITY.md](SECURITY.md) for how.
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org). Notable changes
+are recorded in [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
-MIT. See `LICENSE.txt`.
+Released under the MIT License. See [LICENSE.txt](LICENSE.txt).