whatsapp_notifier 0.6.0 → 0.8.0

data/lib/whatsapp_notifier/web_adapter.rb

@@ -6,6 +6,36 @@ module WhatsAppNotifier
   class WebAdapter
     DEFAULT_OPEN_TIMEOUT = 5
     DEFAULT_READ_TIMEOUT = 30
+    # Media bytes can be tens of MB over a slow link — give the binary fetch a
+    # longer read window than the JSON control plane.
+    MEDIA_OPEN_TIMEOUT = 5
+    MEDIA_READ_TIMEOUT = 60
+
+    HTTP_CLASSES = {
+      post: Net::HTTP::Post,
+      get: Net::HTTP::Get,
+      delete: Net::HTTP::Delete
+    }.freeze
+
+    # Optional inbound keys introduced by the 0.7.0 service (media verdict +
+    # sender display name) and the 0.8.0 service (two-way capture). Mapped
+    # ONLY when the wire payload carries them, so hosts can key-gate on
+    # presence: a missing has_media means "0.6.0 service, no media support"
+    # (while has_media: false means "text message"), and a missing from_me
+    # means "customer message or pre-0.8.0 service". `to` carries the
+    # counterparty chat id on operator-sent (from_me) messages — the id the
+    # host threads the conversation on.
+    INBOUND_OPTIONAL_KEYS = {
+      has_media: %w[hasMedia has_media],
+      media_status: %w[mediaStatus media_status],
+      media_error: %w[mediaError media_error],
+      media_mime: %w[mediaMime media_mime],
+      media_filename: %w[mediaFilename media_filename],
+      media_size: %w[mediaSize media_size],
+      sender_name: %w[senderName sender_name],
+      to: %w[to],
+      from_me: %w[fromMe from_me]
+    }.freeze
 
     def self.default_base_url
       ENV["WHATSAPP_NOTIFIER_SERVICE_URL"] || ENV["WHATSAPP_SERVICE_URL"] || "http://127.0.0.1:3001"
@@ -30,7 +60,12 @@ module WhatsAppNotifier
       response = request(:post, "/send/#{user_id}", body: body)
       {
         success: response.fetch("success"),
-        message_id: payload[:idempotency_key] || "local-#{Time.now.to_i}",
+        # Prefer the service-issued WhatsApp message id (0.8.0): it is the key
+        # the host dedupes the send's own fromMe echo on, so a real id must
+        # win over the locally fabricated one. The fallback keeps 0.7.0
+        # services (no messageId in the response) working unchanged.
+        message_id: response["messageId"] || response["message_id"] ||
+                    payload[:idempotency_key] || "local-#{Time.now.to_i}",
         session: session,
         error_message: response["error"]
       }
@@ -60,15 +95,88 @@ module WhatsAppNotifier
       user_id = user_id_from(metadata)
       response = request(:get, "/inbound/#{user_id}")
       raw = response.is_a?(Hash) ? response["messages"] : response
-      Array(raw).map do |m|
-        {
-          from: m["from"],
-          body: m["body"],
-          message_id: m["messageId"] || m["message_id"],
-          timestamp: m["timestamp"],
-          type: m["type"]
-        }
-      end
+      Array(raw).map { |m| map_inbound_message(m) }
+    end
+
+    # Fetches the raw bytes of a downloaded inbound media file. Returns
+    # { body:, mime:, filename:, size: } or nil when the service has no copy
+    # (never downloaded, swept by TTL, or already deleted).
+    #
+    # Deliberately NOT routed through #request: that path JSON-parses the
+    # response body (and host apps are known to patch it further), which would
+    # corrupt binary payloads.
+    def fetch_media(message_id:, metadata: {})
+      user_id = user_id_from(metadata)
+      res = binary_get("/media/#{user_id}/#{path_id(message_id)}")
+      return nil if res.code.to_s == "404"
+      raise "service request failed (#{res.code}): #{res.body}" unless res.is_a?(Net::HTTPSuccess)
+
+      body = res.body.to_s
+      {
+        body: body,
+        mime: res["Content-Type"],
+        filename: filename_from(res["Content-Disposition"]),
+        size: body.bytesize
+      }
+    end
+
+    # On-demand re-download (WhatsApp tap-to-download). The host calls this when
+    # an operator opens a media bubble whose bytes the service no longer holds
+    # (rolled off by the per-user cap or expired by TTL): the service re-pulls
+    # THAT one message's media and stores it, after which the host fetches it
+    # with the usual fetch_media GET. Returns { mime:, filename:, size:, status: }
+    # on success, or nil when the media is gone upstream (404) — same nil-on-404
+    # contract as fetch_media, so a host that gets nil can grey the bubble out.
+    # A 0.7.0 service mid-rollout has no /refetch route and also answers 404 →
+    # nil, indistinguishable from gone, which is the safe degrade.
+    def refetch_media(message_id:, chat_id:, metadata: {})
+      user_id = user_id_from(metadata)
+      body = { messageId: message_id, chatId: chat_id }
+      response = request(:post, "/media/#{user_id}/refetch", body: body, allow_404: true)
+      return nil unless response["success"]
+
+      {
+        mime: response["mediaMime"] || response["media_mime"],
+        filename: response["mediaFilename"] || response["media_filename"],
+        size: response["mediaSize"] || response["media_size"],
+        status: response["mediaStatus"] || response["media_status"]
+      }
+    end
+
+    # Removes the service's copy after the host has attached the bytes.
+    # Idempotent on the service side: deleting absent media still succeeds.
+    # A 0.6.0 service mid-rollout has no /media routes and answers 404 —
+    # degrade to { success: false } instead of raising, mirroring
+    # fetch_media's nil-on-404.
+    def delete_media(message_id:, metadata: {})
+      user_id = user_id_from(metadata)
+      response = request(:delete, "/media/#{user_id}/#{path_id(message_id)}", allow_404: true)
+      { success: response.fetch("success", false) }
+    end
+
+    # Lists the paired number's 1:1 chats for history-sync discovery. Returns
+    # [{ id:, name:, last_message_at: }] newest-first; the service caps the
+    # list at its newest 500 and excludes groups/status/privacy chats. The
+    # route is token-gated like /media and raises the standard error on any
+    # non-2xx (401 when the user never paired or isn't ready).
+    def list_chats(metadata: {})
+      user_id = user_id_from(metadata)
+      response = request(:get, "/chats/#{user_id}")
+      Array(response["chats"]).map { |chat| map_chat_summary(chat) }
+    end
+
+    # Replays one chat's history through the service's live-capture
+    # normalizer and returns it synchronously (no queue, no webhook) —
+    # oldest-first, mapped exactly like fetch_inbound messages, including
+    # from_me/to on the operator's side of the conversation. History media
+    # arrives marked unavailable by design (media_error "history"): the
+    # service never bulk-downloads old media; live capture handles bytes
+    # going forward.
+    def fetch_history(chat_id:, limit: 50, metadata: {})
+      user_id = user_id_from(metadata)
+      body = { chatId: chat_id, limit: clamp_history_limit(limit) }
+      response = request(:post, "/history/#{user_id}", body: body)
+      Array(response["messages"]).map { |m| map_inbound_message(m) }
     end
 
     # Logs the user out of WhatsApp and clears their saved session on the service.
@@ -78,24 +186,102 @@ module WhatsAppNotifier
       { success: response.fetch("success", false) }
     end
 
+    # Mirrors the service-side clamp (history.ts) so a host-passed limit can
+    # never balloon one request into a session-stalling bulk fetch.
+    HISTORY_LIMIT_DEFAULT = 50
+    HISTORY_LIMIT_RANGE = (1..200).freeze
+
     private
 
     def user_id_from(metadata)
       (metadata[:user_id] || metadata["user_id"] || "default").to_s
     end
 
-    def request(method, path, body: nil)
+    def clamp_history_limit(limit)
+      Integer(limit).clamp(HISTORY_LIMIT_RANGE.min, HISTORY_LIMIT_RANGE.max)
+    rescue ArgumentError, TypeError
+      # Non-integer garbage falls back to the default — the service does the
+      # same, so both layers agree on the effective page size.
+      HISTORY_LIMIT_DEFAULT
+    end
+
+    def map_chat_summary(chat)
+      {
+        id: chat["id"],
+        name: chat["name"],
+        last_message_at: chat.key?("lastMessageAt") ? chat["lastMessageAt"] : chat["last_message_at"]
+      }
+    end
+
+    def map_inbound_message(message)
+      mapped = {
+        from: message["from"],
+        body: message["body"],
+        message_id: message["messageId"] || message["message_id"],
+        timestamp: message["timestamp"],
+        type: message["type"]
+      }
+      INBOUND_OPTIONAL_KEYS.each do |key, wire_keys|
+        wire = wire_keys.find { |candidate| message.key?(candidate) }
+        mapped[key] = message[wire] if wire
+      end
+      mapped
+    end
+
+    # Mirror the service-side sanitizeId charset so a hostile message_id can
+    # never smuggle path separators or a query string into the request URL.
+    def path_id(message_id)
+      message_id.to_s.gsub(/[^A-Za-z0-9@._-]/, "")
+    end
+
+    def filename_from(content_disposition)
+      content_disposition.to_s[/filename="([^"]*)"/, 1]
+    end
+
+    # The /media routes are token-gated when the service has
+    # WHATSAPP_WEBHOOK_TOKEN set — the same shared secret the service uses to
+    # sign its webhook pushes, reused in the other direction.
+    def webhook_token
+      token = ENV["WHATSAPP_WEBHOOK_TOKEN"].to_s
+      token.empty? ? nil : token
+    end
+
+    # Net::HTTP does NOT infer TLS from the URL scheme — without an explicit
+    # use_ssl a https:// service URL would silently speak plaintext to port
+    # 443. Both request paths (JSON control plane + binary media fetch) must
+    # honor the scheme.
+    def use_ssl?(uri)
+      uri.scheme == "https"
+    end
+
+    def binary_get(path)
+      uri = URI.parse("#{@base_url}#{path}")
+      req = Net::HTTP::Get.new(uri.request_uri)
+      req["X-WA-Token"] = webhook_token if webhook_token
+
+      Net::HTTP.start(uri.host, uri.port,
+                      use_ssl: use_ssl?(uri),
+                      open_timeout: MEDIA_OPEN_TIMEOUT,
+                      read_timeout: MEDIA_READ_TIMEOUT) { |http| http.request(req) }
+    end
+
+    def request(method, path, body: nil, allow_404: false)
       uri = URI.parse("#{@base_url}#{path}")
-      klass = method == :post ? Net::HTTP::Post : Net::HTTP::Get
-      req = klass.new(uri.request_uri)
+      req = HTTP_CLASSES.fetch(method).new(uri.request_uri)
       req["Content-Type"] = "application/json"
+      req["X-WA-Token"] = webhook_token if webhook_token
       req.body = JSON.generate(body) if body
 
       res = Net::HTTP.start(uri.host, uri.port,
+                            use_ssl: use_ssl?(uri),
                             open_timeout: @open_timeout,
                             read_timeout: @read_timeout) { |http| http.request(req) }
       parsed = parse_body(res.body)
       return parsed if res.is_a?(Net::HTTPSuccess)
+      # Callers opting in treat "route/resource not there" as a soft miss
+      # (e.g. delete_media against a 0.6.0 service) — the parsed error body
+      # carries no "success" key, so they degrade rather than raise.
+      return parsed if allow_404 && res.code.to_s == "404"
 
       raise "service request failed (#{res.code}): #{parsed["error"] || res.body}"
     end

data/lib/whatsapp_notifier.rb

@@ -66,6 +66,26 @@ module WhatsAppNotifier
       client.fetch_inbound(provider: provider, metadata: metadata)
     end
 
+    def fetch_media(message_id:, provider: nil, metadata: {})
+      client.fetch_media(message_id: message_id, provider: provider, metadata: metadata)
+    end
+
+    def delete_media(message_id:, provider: nil, metadata: {})
+      client.delete_media(message_id: message_id, provider: provider, metadata: metadata)
+    end
+
+    def refetch_media(message_id:, chat_id:, provider: nil, metadata: {})
+      client.refetch_media(message_id: message_id, chat_id: chat_id, provider: provider, metadata: metadata)
+    end
+
+    def list_chats(provider: nil, metadata: {})
+      client.list_chats(provider: provider, metadata: metadata)
+    end
+
+    def fetch_history(chat_id:, limit: 50, provider: nil, metadata: {})
+      client.fetch_history(chat_id: chat_id, limit: limit, provider: provider, metadata: metadata)
+    end
+
     def logout(provider: nil, metadata: {})
       client.logout(provider: provider, metadata: metadata)
     end

data/spec/client_spec.rb

@@ -67,6 +67,54 @@ RSpec.describe WhatsAppNotifier::Client do
     end
   end
 
+  it "delegates fetch_media and delete_media to the provider" do
+    Dir.mktmpdir do |dir|
+      config.provider = :web_automation
+      config.web_automation_enabled = true
+      config.web_session_path = File.join(dir, "session.json")
+      config.web_adapter = double(
+        send_message: { success: true, session: {} },
+        fetch_qr_code: "qr",
+        connection_status: { state: "AUTHENTICATED", authenticated: true },
+        fetch_media: { body: "bytes", mime: "image/jpeg", filename: nil, size: 5 },
+        delete_media: { success: true },
+        refetch_media: { mime: "image/jpeg", filename: nil, size: 5, status: "available" }
+      )
+      client = described_class.new(configuration: config)
+
+      expect(client.fetch_media(message_id: "m1", provider: :web_automation, metadata: { user_id: 1 }))
+        .to include(body: "bytes", size: 5)
+      expect(client.delete_media(message_id: "m1", provider: :web_automation, metadata: { user_id: 1 }))
+        .to eq(success: true)
+      expect(client.refetch_media(message_id: "m1", chat_id: "919@c.us", provider: :web_automation, metadata: { user_id: 1 }))
+        .to include(status: "available")
+    end
+  end
+
+  it "delegates list_chats and fetch_history to the provider" do
+    Dir.mktmpdir do |dir|
+      config.provider = :web_automation
+      config.web_automation_enabled = true
+      config.web_session_path = File.join(dir, "session.json")
+      adapter = double(
+        send_message: { success: true, session: {} },
+        fetch_qr_code: "qr",
+        connection_status: { state: "AUTHENTICATED", authenticated: true },
+        list_chats: [{ id: "919@c.us", name: "Asha", last_message_at: 9 }],
+        fetch_history: [{ from: "919@c.us", body: "old", message_id: "h1" }]
+      )
+      config.web_adapter = adapter
+      client = described_class.new(configuration: config)
+
+      expect(client.list_chats(provider: :web_automation, metadata: { user_id: 1 }))
+        .to eq([{ id: "919@c.us", name: "Asha", last_message_at: 9 }])
+      expect(client.fetch_history(chat_id: "919@c.us", provider: :web_automation, metadata: { user_id: 1 }))
+        .to eq([{ from: "919@c.us", body: "old", message_id: "h1" }])
+      # The default page size survives the delegation chain untouched.
+      expect(adapter).to have_received(:fetch_history).with(chat_id: "919@c.us", limit: 50, metadata: { user_id: 1 })
+    end
+  end
+
   it "delegates logout to the provider" do
     Dir.mktmpdir do |dir|
       config.provider = :web_automation

data/spec/generators/install_service_generator_spec.rb

@@ -58,7 +58,7 @@ RSpec.describe "WhatsAppNotifier::Generators::InstallServiceGenerator" do
       generator.copy_service_files
 
       sources = generator.copied.map(&:first)
-      expect(sources).to match_array(%w[index.ts inbound.ts init_gate.ts metrics.ts sessions.ts package.json bun.lock])
+      expect(sources).to match_array(%w[index.ts history.ts inbound.ts init_gate.ts media.ts metrics.ts send.ts sessions.ts package.json bun.lock])
       expect(sources.grep(/test|node_modules|\.wwebjs|\.puppeteer/)).to be_empty
       expect(generator.copied.map(&:last)).to all(start_with("whatsapp_service/"))
     end
@@ -69,6 +69,17 @@ RSpec.describe "WhatsAppNotifier::Generators::InstallServiceGenerator" do
                         "SERVICE_FILES lists #{file} but it is missing from the service dir"
       end
     end
+
+    # An ejected service that is missing a module index.ts imports dies on
+    # boot — pin the file list to the imports so a new module (like media.ts
+    # in 0.7.0) can never be forgotten again.
+    it "ships every local module index.ts imports" do
+      index = File.read(File.join(generator_class.source_root, "index.ts"), encoding: "UTF-8")
+      local_imports = index.scan(%r{from '\./([A-Za-z0-9_]+)'}).flatten.map { |name| "#{name}.ts" }
+
+      expect(local_imports).not_to be_empty
+      expect(generator_class.const_get(:SERVICE_FILES)).to include(*local_imports)
+    end
   end
 
   describe "#add_to_gitignore" do

data/spec/providers/web_automation_spec.rb

@@ -137,6 +137,103 @@ RSpec.describe WhatsAppNotifier::Providers::WebAutomation do
     end
   end
 
+  it "fetches, deletes and refetches media via the adapter when enabled" do
+    Dir.mktmpdir do |dir|
+      adapter = double(
+        fetch_qr_code: "qr", connection_status: {},
+        fetch_media: { body: "bytes", mime: "image/jpeg", filename: "a.jpg", size: 5 },
+        delete_media: { success: true },
+        refetch_media: { mime: "image/jpeg", filename: "a.jpg", size: 5, status: "available" }
+      )
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect(provider.fetch_media(message_id: "m1", metadata: { user_id: 1 })).to include(mime: "image/jpeg")
+      expect(provider.delete_media(message_id: "m1", metadata: { user_id: 1 })).to eq(success: true)
+      expect(provider.refetch_media(message_id: "m1", chat_id: "919@c.us", metadata: { user_id: 1 }))
+        .to include(status: "available")
+      expect(adapter).to have_received(:fetch_media).with(message_id: "m1", metadata: { user_id: 1 })
+      expect(adapter).to have_received(:delete_media).with(message_id: "m1", metadata: { user_id: 1 })
+      expect(adapter).to have_received(:refetch_media).with(message_id: "m1", chat_id: "919@c.us", metadata: { user_id: 1 })
+    end
+  end
+
+  it "raises on the media helpers when the provider is disabled" do
+    Dir.mktmpdir do |dir|
+      adapter = double(fetch_qr_code: "qr", connection_status: {}, fetch_media: nil, delete_media: { success: true }, refetch_media: nil)
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter, enabled: false)
+      provider = described_class.new(configuration: config)
+
+      expect { provider.fetch_media(message_id: "m1") }.to raise_error(WhatsAppNotifier::ConfigurationError, /disabled/)
+      expect { provider.delete_media(message_id: "m1") }.to raise_error(WhatsAppNotifier::ConfigurationError, /disabled/)
+      expect { provider.refetch_media(message_id: "m1", chat_id: "919@c.us") }.to raise_error(WhatsAppNotifier::ConfigurationError, /disabled/)
+    end
+  end
+
+  it "raises on the media helpers when the adapter lacks media support" do
+    Dir.mktmpdir do |dir|
+      adapter = double(fetch_qr_code: "qr", connection_status: {})
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect { provider.fetch_media(message_id: "m1") }.to raise_error(WhatsAppNotifier::ConfigurationError, /media fetch/)
+      expect { provider.delete_media(message_id: "m1") }.to raise_error(WhatsAppNotifier::ConfigurationError, /media deletion/)
+      expect { provider.refetch_media(message_id: "m1", chat_id: "919@c.us") }.to raise_error(WhatsAppNotifier::ConfigurationError, /media refetch/)
+    end
+  end
+
+  it "lists chats and fetches history via the adapter when enabled" do
+    Dir.mktmpdir do |dir|
+      adapter = double(
+        fetch_qr_code: "qr", connection_status: {},
+        list_chats: [{ id: "919@c.us", name: "Asha", last_message_at: 9 }],
+        fetch_history: [{ from: "919@c.us", body: "old", message_id: "h1" }]
+      )
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect(provider.list_chats(metadata: { user_id: 1 })).to eq([{ id: "919@c.us", name: "Asha", last_message_at: 9 }])
+      expect(provider.fetch_history(chat_id: "919@c.us", limit: 20, metadata: { user_id: 1 }))
+        .to eq([{ from: "919@c.us", body: "old", message_id: "h1" }])
+      expect(adapter).to have_received(:list_chats).with(metadata: { user_id: 1 })
+      expect(adapter).to have_received(:fetch_history).with(chat_id: "919@c.us", limit: 20, metadata: { user_id: 1 })
+    end
+  end
+
+  it "defaults the history limit to 50 through the provider" do
+    Dir.mktmpdir do |dir|
+      adapter = double(fetch_qr_code: "qr", connection_status: {}, fetch_history: [])
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      provider.fetch_history(chat_id: "919@c.us")
+
+      expect(adapter).to have_received(:fetch_history).with(chat_id: "919@c.us", limit: 50, metadata: {})
+    end
+  end
+
+  it "raises on the history helpers when the provider is disabled" do
+    Dir.mktmpdir do |dir|
+      adapter = double(fetch_qr_code: "qr", connection_status: {}, list_chats: [], fetch_history: [])
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter, enabled: false)
+      provider = described_class.new(configuration: config)
+
+      expect { provider.list_chats }.to raise_error(WhatsAppNotifier::ConfigurationError, /disabled/)
+      expect { provider.fetch_history(chat_id: "919@c.us") }.to raise_error(WhatsAppNotifier::ConfigurationError, /disabled/)
+    end
+  end
+
+  it "raises on the history helpers when the adapter lacks history support" do
+    Dir.mktmpdir do |dir|
+      adapter = double(fetch_qr_code: "qr", connection_status: {})
+      config = build_config(path: File.join(dir, "session.json"), adapter: adapter)
+      provider = described_class.new(configuration: config)
+
+      expect { provider.list_chats }.to raise_error(WhatsAppNotifier::ConfigurationError, /chat listing/)
+      expect { provider.fetch_history(chat_id: "919@c.us") }.to raise_error(WhatsAppNotifier::ConfigurationError, /history replay/)
+    end
+  end
+
   it "logs out via adapter when enabled" do
     Dir.mktmpdir do |dir|
       adapter = double(fetch_qr_code: "qr", connection_status: {}, logout: { success: true })