whatsapp_notifier 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '039a2704065400307efc4ba87239421078f1b63f97055c025ec226c6d26d907a'
+  data.tar.gz: 1af1676a7258d3c34e63d4fd2a6f7ab5ddb0158f78403c8d9ea65f2ccc54eda2
+SHA512:
+  metadata.gz: e7d97f32003bbdcd29e05a59857a1fc5e33c980b78a9aa6b4c0fa7398e44ce508ca629ad27ba8066759b538e4044a47904dfedfd9e74749a11dedc8de5fb0e4a
+  data.tar.gz: 4832f03b7c735afc1d735ff3ad1cfbd9717912a63e06defddbe3d0a7f4a1954b49e4e811b6597fcc61b573556e6cec636e572f5014beae7355aa578c6d2c2d7b

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.13"
+gem "simplecov", "~> 0.22", require: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kshitiz Sinha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,126 @@
+# WhatsAppNotifier
+
+`whatsapp_notifier` is a Rails-friendly gem for WhatsApp Web automation.
+It is intentionally simple: run the bundled Bun service, scan a QR code, and send messages.
+
+No official WhatsApp API setup, app review, or Meta webhook configuration is required.
+
+## What You Get
+
+- 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]`
+
+## Quick Start (60 seconds)
+
+```bash
+bundle add whatsapp_notifier
+bin/rails g whatsapp_notifier:install
+bin/dev
+```
+
+Then:
+
+- open `/dashboard/whatsapp/qr`
+- scan QR
+- send a test message
+
+If setup fails, run:
+
+```bash
+bundle exec whatsapp_notifier doctor
+```
+
+## Installation
+
+```ruby
+gem "whatsapp_notifier"
+```
+
+```bash
+bundle install
+bin/rails g whatsapp_notifier:install
+```
+
+## Scan QR and check status
+
+```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 })
+
+status = WhatsAppNotifier.connection_status(metadata: { user_id: current_user.id })
+# => { state: "...", authenticated: true/false, has_qr: true/false }
+```
+
+## Send a message
+
+```ruby
+result = WhatsAppNotifier.deliver(
+  to: "+919999999999",
+  body: "Booking confirmed",
+  metadata: { user_id: current_user.id }
+)
+
+result.success?
+```
+
+## Notifications API
+
+```ruby
+class LeadWhatsappNotification < WhatsAppNotifier::Notification
+  def to
+    params[:lead].phone_number
+  end
+
+  def message
+    "Hi #{params[:lead].name}, we are working on your itinerary."
+  end
+
+  def metadata
+    { user_id: params[:user].id }
+  end
+end
+```
+
+```ruby
+LeadWhatsappNotification.with(lead: @lead, user: current_user).deliver_later
+```
+
+## Bulk Messaging
+
+```ruby
+messages = [
+  { to: "+919999999991", body: "Hello A", metadata: { user_id: current_user.id } },
+  { to: "+919999999992", body: "Hello B", metadata: { user_id: current_user.id } }
+]
+
+summary = WhatsAppNotifier.deliver_bulk(messages)
+summary[:success]
+```
+
+## Generators
+
+Install everything with one command:
+
+```bash
+rails generate whatsapp_notifier:install
+```
+
+If you want to eject Bun service files into your app:
+
+```bash
+rails generate whatsapp_notifier:install_service
+```
+
+This copies the service to `whatsapp_service/` and updates `.gitignore`.
+
+## Notes
+
+- This gem uses WhatsApp Web automation. Use responsibly and follow WhatsApp policies.
+- Keep Chromium available in your runtime (or set `PUPPETEER_EXECUTABLE_PATH`).
+
+## License
+
+MIT. See `LICENSE.txt`.

data/Rakefile

@@ -0,0 +1,6 @@
+require "rake/testtask"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/whatsapp_notifier

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+require "thor"
+require "whatsapp_notifier"
+
+module WhatsAppNotifier
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "doctor", "Validate local setup and print exact fixes"
+    def doctor
+      ok = WhatsAppNotifier::Doctor.run
+      raise Thor::Error, "Doctor checks failed. Apply fixes above and run again." unless ok
+
+      puts "All checks passed."
+    end
+
+    desc "service", "Start the WhatsApp automation service (Bun)"
+    option :port, type: :numeric, default: WhatsAppNotifier::Doctor::DEFAULT_PORT, desc: "Port to run the service on"
+    def service
+      service_path = WhatsAppNotifier.service_path
+      puts "Starting WhatsApp Notifier Service from #{service_path}..."
+
+      ENV["PORT"] ||= options[:port].to_s
+      ENV["WHATSAPP_SESSION_DIR"] ||= WhatsAppNotifier::Doctor.session_dir
+
+      unless system("bun --version > /dev/null 2>&1")
+        raise Thor::Error, "Bun is required. Install from https://bun.sh"
+      end
+
+      # Auto-detect Chromium in common locations for development
+      if !ENV["PUPPETEER_EXECUTABLE_PATH"] && File.exist?("/usr/bin/chromium")
+        ENV["PUPPETEER_EXECUTABLE_PATH"] = "/usr/bin/chromium"
+      end
+
+      Dir.chdir(service_path) do
+        # Ensure dependencies are installed
+        unless File.exist?("node_modules")
+          puts "Installing dependencies (bun install)..."
+          unless system("bun install")
+            raise Thor::Error, "Failed to install Bun dependencies in #{service_path}"
+          end
+        end
+
+        exec("bun index.ts")
+      end
+    end
+  end
+end
+
+WhatsAppNotifier::CLI.start(ARGV)

data/docs/bulk_messaging_policy.md

@@ -0,0 +1,30 @@
+# Bulk Messaging Policy Guardrails
+
+This gem includes technical controls to reduce policy and spam risks:
+
+- paced delivery via `bulk_base_delay_seconds` and `bulk_jitter_seconds`
+- capped recipients via `bulk_max_recipients`
+- bounded retries via `bulk_max_attempts`
+- retry only on configured transient error codes
+- automatic wait/sleep when provider returns `wait_seconds`
+- idempotency key deduplication in the same bulk run
+
+## Recommended defaults
+
+- keep throughput conservative and user-scoped (`metadata[:user_id]`)
+- avoid unsolicited messaging
+- use explicit opt-in recipient lists
+
+## Wait-time compliance
+
+If provider returns:
+
+```ruby
+{ success: false, error_code: :rate_limited, wait_seconds: 30 }
+```
+
+the bulk dispatcher pauses for 30 seconds before moving forward.
+
+## Web automation warning
+
+This gem uses `:web_automation`. Keep use-cases controlled, compliant, and consent-based.

data/docs/graphify.md

@@ -0,0 +1,108 @@
+# Graphify this repository
+
+[Graphify](https://github.com/sponsors/safishamsi) turns a folder of code and docs into a **persistent knowledge graph**: entities, relationships (tagged as extracted vs inferred), community clusters, and browsable outputs. Use it when you want a map of `whatsapp_notifier` before refactoring, onboarding, or tracing how bulk delivery, providers, and Rails integration connect.
+
+This document describes how to run the pipeline **from the gem root** (`whatsapp_notifier/`). It mirrors the `/graphify` agent workflow; you can also run the same steps in a terminal.
+
+## Prerequisites
+
+- **Python 3** with pip
+- Install the package (the CLI may be published as `graphifyy`):
+
+  ```bash
+  python3 -m pip install graphifyy
+  ```
+
+- Optional: `graphify` on your `PATH` (the installer may expose it). If missing, use `python3 -m` forms below.
+
+## What gets indexed here
+
+Reasonable targets for this repo:
+
+| Path | Role |
+|------|------|
+| `.` (repo root) | Full corpus: `lib/`, `spec/`, `docs/`, `examples/` |
+| `lib/whatsapp_notifier` | Core implementation only (smaller graph) |
+| `docs/` | Policy and setup prose only |
+
+Ruby (`.rb`) is treated as **code** (AST + optional semantic extraction). Markdown under `docs/` is **documents**.
+
+## One-shot run (full pipeline)
+
+From the repository root:
+
+1. **Ensure graphify is importable** and record the interpreter (so later steps use the same venv):
+
+   ```bash
+   mkdir -p graphify-out
+   python3 -c "import graphify" 2>/dev/null || python3 -m pip install graphifyy -q
+   python3 -c "import sys; open('graphify-out/.graphify_python', 'w').write(sys.executable)"
+   ```
+
+2. **Detect files** (writes `graphify-out/.graphify_detect.json`; inspect with a JSON viewer or small script if you need counts).
+
+3. **Extract**  
+   - **Code:** AST extraction over Ruby files (imports/calls structure).  
+   - **Docs / non-code:** semantic extraction (LLM) unless the corpus is code-only.  
+   For large corpora, graphify supports **caching** and **chunked** extraction; see upstream docs.
+
+4. **Build graph, cluster, report** — produces the main artifacts below.
+
+5. **Label communities** — short human names per cluster, then regenerate the report.
+
+6. **HTML** — interactive `graphify-out/graph.html` (skipped or warned if the graph is huge).
+
+7. **Cleanup** — some intermediate JSON files may be removed at the end of a full run; **`graph.json`**, **`GRAPH_REPORT.md`**, and **`graph.html`** are the durable outputs.
+
+Use the interpreter pinned in `graphify-out/.graphify_python` for all `python -c "…"` snippets so a venv and the CLI stay consistent:
+
+```bash
+PY="$(cat graphify-out/.graphify_python)"
+"$PY" -c "import graphify; print('ok')"
+```
+
+## Outputs (under `graphify-out/`)
+
+After a successful run you should have:
+
+| Output | Purpose |
+|--------|---------|
+| `graph.html` | Interactive graph in a browser (no server) |
+| `GRAPH_REPORT.md` | Audit-style report: god nodes, surprising links, suggested questions, token usage |
+| `graph.json` | GraphRAG-style structured graph for tools or custom queries |
+| `cost.json` | Cumulative token accounting across runs (if enabled by your graphify version) |
+
+Optional flags (when using the full `/graphify` agent or CLI with the same options):
+
+- `--no-viz` — report + JSON only  
+- `--obsidian` / `--obsidian-dir` — Obsidian vault + canvas  
+- `--update` — incremental re-extraction for changed files only  
+- `--directed` — preserve edge direction in the graph  
+- `--svg` / `--graphml` / `--neo4j` — extra export formats  
+
+## Queries after the graph exists
+
+With `graphify-out/graph.json` present, you can:
+
+- **Broad context:** BFS-style “what is X connected to?”  
+- **Paths:** shortest path between two labeled concepts  
+- **Explain:** neighborhood of one node  
+
+The graphify CLI or agent subcommands (`query`, `path`, `explain`) operate on that file; answers should cite graph edges and confidence tags, not invent links.
+
+## Large repo warning
+
+If detection reports **very high** file or word counts, run graphify on a **subfolder** (for example `lib/whatsapp_notifier` only) first. That keeps HTML visualization and clustering responsive.
+
+## CI and secrets
+
+Do **not** commit API keys or production phone numbers into the corpus before indexing. This gem’s **specs and examples** should use placeholders; scrub any local overrides before running graphify on a copy of the tree if you use real data in dev.
+
+## Related project docs
+
+- [Rails setup](rails_setup.md) — initializer and Active Job wiring  
+- [Bulk messaging policy](bulk_messaging_policy.md) — rate limits and guardrails  
+
+---
+
+*Workflow reference: Cursor `/graphify` skill (graph detection → AST + semantic merge → cluster → report → HTML). For the canonical flag list and agent-only steps (parallel semantic chunks, Whisper for video), use the skill or upstream graphify documentation.*

data/docs/rails_setup.md

@@ -0,0 +1,57 @@
+# Rails Setup
+
+## Initializer
+
+Create `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
+  config.bulk_max_attempts = 3
+end
+```
+
+Defaults already use a built-in adapter that talks to `http://127.0.0.1:3001`.
+
+## Global usage
+
+`WhatsAppNotifier` is available globally:
+
+```ruby
+WhatsAppNotifier.deliver(
+  to: "+919999999999",
+  body: "Payment received",
+  metadata: { user_id: current_user.id }
+)
+```
+
+## Mailer-like class usage
+
+```ruby
+class AlertsNotification < WhatsAppNotifier::Notification
+  to "+919999999999"
+  provider :web_automation
+  template :payment_alert, "Hi {{name}}, payment {{amount}} received."
+
+  def metadata
+    { user_id: params[:user_id] }
+  end
+end
+
+AlertsNotification.deliver_now(params: { name: "Riya", amount: "INR 1500" }, user_id: 42)
+```
+
+## Async behavior
+
+`deliver_later` requires ActiveJob to be available.
+
+```ruby
+AlertsNotification.deliver_later(
+  to: "+919999999999",
+  params: { name: "Riya", amount: "INR 1500" }
+)
+```

data/examples/notification_example.rb

@@ -0,0 +1,14 @@
+require "whatsapp_notifier"
+
+WhatsAppNotifier.configure do |config|
+  config.provider = :web_automation
+  config.web_automation_enabled = true
+end
+
+class WelcomeNotification < WhatsAppNotifier::Notification
+  to "+919999999999"
+  provider :web_automation
+  template :welcome, "Hi {{name}}, welcome to our platform."
+end
+
+WelcomeNotification.deliver_now(params: { name: "Asha" }, metadata: { user_id: "demo-user" })

data/lib/generators/whatsapp_notifier/install_generator.rb

@@ -0,0 +1,60 @@
+require "rails/generators"
+require "whatsapp_notifier/doctor"
+
+module WhatsAppNotifier
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        return if File.exist?("config/initializers/whatsapp_notifier.rb")
+
+        template "whatsapp_notifier.rb", "config/initializers/whatsapp_notifier.rb"
+      end
+
+      def ensure_procfile_entry
+        procfile = "Procfile.dev"
+        line = "whatsapp: bundle exec whatsapp_notifier service"
+
+        unless File.exist?(procfile)
+          create_file(procfile, "#{line}\n")
+          return
+        end
+
+        content = File.read(procfile)
+        return if content.lines.any? { |existing| existing.strip == line }
+
+        append_to_file(procfile, "\n#{line}\n")
+      end
+
+      def ensure_gitignore_entries
+        entries = [
+          "# WhatsApp Notifier",
+          "/tmp/whatsapp_notifier",
+          "/whatsapp_service/node_modules",
+          "/whatsapp_service/.wwebjs_cache",
+          "/whatsapp_service/.wwebjs_auth"
+        ]
+
+        content = File.exist?(".gitignore") ? File.read(".gitignore") : ""
+        missing = entries.reject { |entry| content.include?(entry) }
+        return if missing.empty?
+
+        append_to_file(".gitignore", "\n#{missing.join("\n")}\n")
+      end
+
+      def run_doctor
+        say("\nRunning setup doctor...", :yellow)
+        ok = WhatsAppNotifier::Doctor.run(io: $stdout, app_root: destination_root)
+        return if ok
+
+        raise Thor::Error, "Setup checks failed. Fix items above, then run `bundle exec whatsapp_notifier doctor`."
+      end
+
+      def next_steps
+        say("\nSetup complete.", :green)
+        say("Run `bin/dev`, open `/dashboard/whatsapp/qr`, then send a test message.", :green)
+      end
+    end
+  end
+end

data/lib/generators/whatsapp_notifier/install_service_generator.rb

@@ -0,0 +1,33 @@
+require 'rails/generators'
+
+module WhatsAppNotifier
+  module Generators
+    class InstallServiceGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../whatsapp_notifier/services/web_automation", __dir__)
+
+      def copy_service_files
+        directory '.', 'whatsapp_service'
+      end
+
+      def add_to_gitignore
+        entries = [
+          "# WhatsApp Service",
+          "/whatsapp_service/node_modules",
+          "/whatsapp_service/.wwebjs_cache",
+          "/whatsapp_service/.wwebjs_auth"
+        ]
+        content = File.exist?(".gitignore") ? File.read(".gitignore") : ""
+        missing_entries = entries.reject { |entry| content.include?(entry) }
+        return if missing_entries.empty?
+
+        append_to_file ".gitignore", "\n#{missing_entries.join("\n")}\n"
+      end
+      
+      def show_readme
+        say "\nWhatsApp Service installed in /whatsapp_service", :green
+        say "Make sure you have Bun installed: https://bun.sh", :yellow
+        say "To start the service manually: cd whatsapp_service && bun index.ts", :yellow
+      end
+    end
+  end
+end

data/lib/generators/whatsapp_notifier/templates/whatsapp_notifier.rb

@@ -0,0 +1,6 @@
+WhatsAppNotifier.configure do |config|
+  config.provider = :web_automation
+  config.web_automation_enabled = true
+end
+
+ENV["WHATSAPP_NOTIFIER_SERVICE_URL"] ||= "http://127.0.0.1:3001"

data/lib/whatsapp_notifier/bulk/dispatcher.rb

@@ -0,0 +1,64 @@
+require "set"
+
+module WhatsAppNotifier
+  module Bulk
+    class Dispatcher
+      def initialize(client:, configuration:, sleeper: ->(seconds) { sleep(seconds) }, rng: Random.new)
+        @client = client
+        @configuration = configuration
+        @rate_limiter = RateLimiter.new(
+          base_delay: configuration.bulk_base_delay_seconds,
+          jitter: configuration.bulk_jitter_seconds,
+          sleeper: sleeper,
+          rng: rng
+        )
+        @retry_policy = RetryPolicy.new(
+          max_attempts: configuration.bulk_max_attempts,
+          retryable_error_codes: configuration.bulk_retryable_error_codes
+        )
+        @sleeper = sleeper
+      end
+
+      def deliver(messages, provider: nil)
+        raise ConfigurationError, "messages must be an array" unless messages.is_a?(Array)
+        raise ConfigurationError, "bulk_max_recipients exceeded" if messages.length > @configuration.bulk_max_recipients
+
+        sent_keys = Set.new
+        results = messages.map.with_index do |message, idx|
+          @rate_limiter.wait_before_next if idx.positive?
+          deliver_one(message, sent_keys: sent_keys, provider: provider)
+        end
+
+        { total: results.length, success: results.count(&:success?), failed: results.count(&:failure?), results: results }
+      end
+
+      private
+
+      def deliver_one(message, sent_keys:, provider:)
+        idempotency_key = message[:idempotency_key]
+        if idempotency_key && sent_keys.include?(idempotency_key)
+          return Result.new(
+            success: false,
+            provider: provider || @configuration.provider,
+            error_code: :duplicate_idempotency_key,
+            error_message: "idempotency key already processed"
+          )
+        end
+
+        result = @retry_policy.with_retries do |_attempt|
+          @client.deliver(
+            to: message.fetch(:to),
+            body: message.fetch(:body),
+            metadata: message.fetch(:metadata, {}),
+            provider: provider,
+            idempotency_key: idempotency_key
+          )
+        end
+
+        @sleeper.call(result.wait_seconds) if result.wait_seconds.to_f.positive?
+        sent_keys << idempotency_key if idempotency_key && result.success?
+        result
+      end
+    end
+  end
+end

data/lib/whatsapp_notifier/bulk/rate_limiter.rb

@@ -0,0 +1,17 @@
+module WhatsAppNotifier
+  module Bulk
+    class RateLimiter
+      def initialize(base_delay:, jitter:, sleeper:, rng: Random.new)
+        @base_delay = base_delay.to_f
+        @jitter = jitter.to_f
+        @sleeper = sleeper
+        @rng = rng
+      end
+
+      def wait_before_next
+        delay = @base_delay + (@rng.rand * @jitter)
+        @sleeper.call(delay) if delay.positive?
+      end
+    end
+  end
+end

data/lib/whatsapp_notifier/bulk/retry_policy.rb

@@ -0,0 +1,32 @@
+module WhatsAppNotifier
+  module Bulk
+    class RetryPolicy
+      def initialize(max_attempts:, retryable_error_codes:)
+        @max_attempts = max_attempts
+        @retryable_error_codes = retryable_error_codes
+      end
+
+      def with_retries
+        attempts = 0
+        result = nil
+
+        loop do
+          attempts += 1
+          result = yield(attempts)
+          break unless retry?(result, attempts)
+        end
+
+        result
+      end
+
+      private
+
+      def retry?(result, attempts)
+        return false if attempts >= @max_attempts
+        return false if result.success?
+
+        @retryable_error_codes.include?(result.error_code)
+      end
+    end
+  end
+end