ruby-whatsapp 0.4.0 → 0.4.2

data/docs/configuration.md

@@ -0,0 +1,172 @@
+# Configuration
+
+`Whatsapp.configure` sets the global defaults every `Whatsapp::Client` is built from.
+Call it once at boot.
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key  = ENV.fetch("WHATSAPP_API_KEY")
+  config.phone_id = ENV.fetch("WHATSAPP_PHONE_ID")
+end
+```
+
+## Options
+
+| Option | Default | Needed for |
+| --- | --- | --- |
+| `api_key` | `nil` | Everything — a Meta system-user or app access token |
+| `phone_id` | `nil` | [Messages](messages/README.md), [media](media/README.md), [phone-number onboarding](business_phone_number/README.md) |
+| `waba_id` | `nil` | [Template management](message_templates/README.md), [subscribed apps](subscribed_app/README.md), [the business account](business_phone_number/account.md) |
+| `verify_token` | `nil` | The [webhook GET handshake](webhooks/README.md#verification-the-get-handshake) |
+| `app_secret` | `nil` | [Webhook signature verification](webhooks/README.md#signature-the-post-check) |
+| `host` | `"https://graph.facebook.com"` | Overriding the API host |
+| `version` | `"v24.0"` | Pinning a Graph API version |
+| `media_host_allowlist` | `["lookaside.fbsbx.com", "mmg.whatsapp.net", "graph.facebook.com"]` | [Media download safety](media/README.md#the-token-never-leaves-the-allowlist) |
+
+A full configuration:
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key      = ENV.fetch("WHATSAPP_API_KEY")
+  config.phone_id     = ENV.fetch("WHATSAPP_PHONE_ID")
+  config.waba_id      = ENV.fetch("WHATSAPP_WABA_ID")
+  config.verify_token = ENV.fetch("WHATSAPP_VERIFY_TOKEN")
+  config.app_secret   = ENV.fetch("WHATSAPP_APP_SECRET")
+end
+```
+
+In Rails, put that in `config/initializers/whatsapp.rb` and read from
+`Rails.application.credentials` rather than `ENV`.
+
+## Which ID addresses what
+
+The most common source of confusion. Two different Meta objects, two different
+permissions:
+
+```
+phone_id  ──►  Messages          send_text!, send_template!, send_interactive!, ...
+               Media             upload, get_url, download, delete
+               BusinessPhoneNumber  RequestCode, VerifyCode, Register, Deregister
+               (permission: whatsapp_business_messaging)
+
+waba_id   ──►  MessageTemplates  create, list, find, update, delete, upsert
+               SubscribedApp     List, Subscribe, Unsubscribe
+               BusinessPhoneNumber::Account  Get, Update
+               (permission: whatsapp_business_management)
+```
+
+`BusinessPhoneNumber` is the one module that appears on both sides: its onboarding
+actions address a phone number, while its
+[`Account`](business_phone_number/account.md) actions address the account that number
+belongs to.
+
+Calling a `waba_id` API without one raises before any request is made:
+
+```ruby
+Whatsapp::MessageTemplates.new.list
+# => Whatsapp::MessageTemplates::TemplateError: waba_id is required for template
+#    management; set it via Whatsapp.configure or Client.new(waba_id:)
+```
+
+## Secrets are redacted
+
+`api_key`, `app_secret`, and `verify_token` never appear in `#inspect` output — not on
+`Configuration`, not on `Client`, and therefore not on anything holding a client
+(`Media`, `MessageTemplates`). This matters because error trackers routinely capture
+local variables.
+
+```ruby
+Whatsapp.configuration.inspect
+# => "#<Whatsapp::Configuration host=\"https://graph.facebook.com\" version=\"v24.0\"
+#     api_key=[REDACTED] phone_id=\"106540352242922\" waba_id=nil
+#     verify_token=[REDACTED] app_secret=[REDACTED]>"
+
+Whatsapp::Client.new.inspect
+# => "#<Whatsapp::Client host=\"https://graph.facebook.com\" version=\"v24.0\"
+#     api_key=[REDACTED] phone_id=\"106540352242922\" waba_id=nil>"
+```
+
+The same treatment applies to credentials in transit:
+[`Register#inspect`](business_phone_number/README.md#registering) redacts the PIN and
+`VerifyCode#inspect` redacts the OTP.
+
+## The client
+
+Every API call goes through a `Whatsapp::Client`, which wraps a persistent HTTP
+connection. All its constructor keywords default to `Whatsapp.configuration`:
+
+```ruby
+Whatsapp::Client.new(
+  host:     Whatsapp.configuration.host,
+  version:  Whatsapp.configuration.version,
+  api_key:  Whatsapp.configuration.api_key,
+  phone_id: Whatsapp.configuration.phone_id,
+  waba_id:  Whatsapp.configuration.waba_id,
+  timeout:  30,     # Client::DEFAULT_TIMEOUT, seconds
+  logger:   nil
+)
+```
+
+Every entry point in the gem accepts an optional `client:`, which is how you address a
+second phone number or business account without touching global state:
+
+```ruby
+Whatsapp::Messages.send_text!(
+  to: "+15551234567", body: "Hi",
+  client: Whatsapp::Client.new(phone_id: "OTHER_PHONE_ID")
+)
+
+Whatsapp::MessageTemplates.new(client: Whatsapp::Client.new(waba_id: "OTHER_WABA_ID")).list
+```
+
+### Connection reuse
+
+`Client#connection` memoizes `HTTP.persistent(host)`, so successive calls on the same
+client reuse one TCP connection. Build a client once and hold it for a batch of sends
+rather than constructing one per message:
+
+```ruby
+client = Whatsapp::Client.new
+
+recipients.each { |to| Whatsapp::Messages.send_text!(to:, body: "Hi", client:) }
+```
+
+### Timeouts
+
+```ruby
+Whatsapp::Client.new(timeout: 10)
+```
+
+Applies to the whole request. The default is 30 seconds.
+
+## Instrumentation
+
+Pass a `Logger` to log every request and response:
+
+```ruby
+client = Whatsapp::Client.new(logger: Logger.new($stdout))
+
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hi", client: client)
+# I, [...]  INFO -- : POST https://graph.facebook.com/v24.0/106540352242922/messages
+# I, [...]  INFO -- : 200 OK
+```
+
+| Event | Logged |
+| --- | --- |
+| Request start | `<VERB> <url>` at `info` |
+| Response | `<status> <reason>` at `info` |
+| Error | `<name>: <message>` at `error` |
+
+> **The query string is deliberately dropped.** Media and template endpoints put IDs
+> in query parameters; logging them whole is how identifiers end up in log aggregators
+> forever. Only the path is logged.
+
+In Rails, pass `Rails.logger`:
+
+```ruby
+Whatsapp::Client.new(logger: Rails.logger)
+```
+
+---
+
+See also [errors.md](errors.md) for what the client raises.

data/docs/errors.md

@@ -0,0 +1,208 @@
+# Errors
+
+Every exception this gem raises descends from `Whatsapp::Error`, so one rescue catches
+the lot:
+
+```ruby
+begin
+  Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hi")
+rescue Whatsapp::Error => e
+  Rails.logger.error("WhatsApp call failed: #{e.message}")
+end
+```
+
+## The hierarchy
+
+```
+StandardError
+└── Whatsapp::Error
+    ├── Whatsapp::RequestError                              a message send failed
+    ├── Whatsapp::Messages::PayloadError                    unknown message kind
+    ├── Whatsapp::Messages::Interactive::Header::HeaderError  malformed interactive header
+    ├── Whatsapp::Media::MediaError                         any Media failure
+    ├── Whatsapp::MessageTemplates::TemplateError           any template-management failure
+    ├── Whatsapp::SubscribedApp::Error                      any subscribed-apps failure
+    └── Whatsapp::BusinessPhoneNumber::Error                any phone-number-onboarding or account failure
+```
+
+Each module raises **its own** error class rather than the generic
+`Whatsapp::RequestError`, so you can rescue narrowly:
+
+```ruby
+rescue Whatsapp::MessageTemplates::TemplateError => e
+  # a template problem specifically — retry, or surface to the operator
+end
+```
+
+> **`Whatsapp::Webhook::Error` is not an exception.** Despite the name, it is a value
+> object modelling Meta's error payloads on `Status#errors` and
+> `Message::Unknown#errors`. See
+> [webhooks/messages.md](webhooks/messages.md#errors).
+
+## Validation errors are different
+
+Local validation failures raise **`ActiveModel::ValidationError`**, not a gem class.
+That is deliberate: a validation failure means *you* built something wrong, before any
+network call happened, and ActiveModel's error object carries the per-attribute
+detail.
+
+```ruby
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "x" * 5000)
+# => ActiveModel::ValidationError: Validation failed:
+#    Body is too long (maximum is 4096 characters)
+```
+
+Reach the structured detail through the exception's model:
+
+```ruby
+begin
+  Whatsapp::Messages.send_image!(to: "+15551234567", caption: "x" * 2000)
+rescue ActiveModel::ValidationError => e
+  e.model.errors.full_messages
+  # => ["Either id or link must be present", "Caption is too long (maximum is 1024 characters)"]
+  e.model.errors[:caption]
+  # => ["is too long (maximum is 1024 characters)"]
+end
+```
+
+Because every class runs `validate!` at the end of `initialize`, this raises at
+**construction** time — the client is never touched.
+
+Rescuing both kinds:
+
+```ruby
+begin
+  Whatsapp::Messages.send_template!(to:, name:, language: { code: })
+rescue ActiveModel::ValidationError => e
+  # our payload is wrong — a bug, or bad user input
+rescue Whatsapp::Error => e
+  # Meta said no, or the network did
+end
+```
+
+## Missing keywords
+
+A required Ruby keyword that isn't supplied raises `ArgumentError`, not a validation
+error — it never reaches the validator:
+
+```ruby
+Whatsapp::Messages.send_text!(body: "Hi")
+# => ArgumentError: missing keyword: :to
+```
+
+## API failures
+
+Any non-2xx response raises the owning module's error class with a consistent message
+shape:
+
+```
+Failed to <action>: <status> - <body>
+```
+
+```ruby
+# => Whatsapp::RequestError: Failed to send message: 400 Bad Request -
+#    {"error":{"message":"(#131009) Parameter value is not valid","code":131009}}
+
+# => Whatsapp::Media::MediaError: Failed to upload media: 401 Unauthorized - {...}
+
+# => Whatsapp::MessageTemplates::TemplateError: Failed to create template:
+#    400 Bad Request - {"error":{"message":"Invalid parameter","code":100}}
+```
+
+The response body is truncated at **500** characters, with `… (truncated)` appended —
+Meta's error bodies can be long, and a full one in an exception message tends to end up
+somewhere it shouldn't.
+
+Actions used in these messages: `send message`, `mark message as read`,
+`upload media`, `get media URL`, `download media`, `delete media`,
+`list subscribed apps`, `subscribe app`, `unsubscribe app`,
+`request verification code`, `verify code`, `register business phone number`,
+`deregister business phone number`, plus the template CRUD verbs.
+
+## Missing configuration
+
+The `waba_id` and `phone_id` modules check for their ID **before** building a request,
+and say exactly how to supply it:
+
+```ruby
+Whatsapp::MessageTemplates.new.list
+# => Whatsapp::MessageTemplates::TemplateError: waba_id is required for template
+#    management; set it via Whatsapp.configure or Client.new(waba_id:)
+
+Whatsapp::SubscribedApp::List.call
+# => Whatsapp::SubscribedApp::Error: waba_id is required for subscribed apps;
+#    set it via Whatsapp.configure or Client.new(waba_id:)
+
+Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834")
+# => Whatsapp::BusinessPhoneNumber::Error: phone_id is required for the register edge;
+#    set it via Whatsapp.configure or Client.new(phone_id:)
+
+Whatsapp::BusinessPhoneNumber::Account::Get.call
+# => Whatsapp::BusinessPhoneNumber::Error: waba_id is required for business account
+#    details; set it via Whatsapp.configure or Client.new(waba_id:)
+```
+
+Note the last two: `BusinessPhoneNumber` spans both IDs. Its onboarding actions need
+`phone_id`; its [`Account`](business_phone_number/account.md) actions need `waba_id`.
+
+See [configuration.md](configuration.md#which-id-addresses-what).
+
+## Argument errors from a module
+
+Some misuse is caught before validation and raises the module's own error rather than
+`ActiveModel::ValidationError` — these are wrong *calls*, not wrong *data*:
+
+```ruby
+templates.upsert(name: "x", language: "en_US", ...)
+# => TemplateError: #upsert requires `languages:` (an array of locale codes);
+#    use #create for a single one
+
+templates.update(template_id: "123")
+# => TemplateError: nothing to update: pass category, components or message_send_ttl_seconds
+
+templates.delete(hsm_ids: %w[1 2], name: "x")
+# => TemplateError: hsm_ids cannot be combined with name or hsm_id
+
+Whatsapp::Messages.new(kind: :telepathy, payload: { to: "+1" })
+# => Whatsapp::Messages::PayloadError: Unknown message kind: :telepathy.
+#    Known kinds: text, image, audio, video, document, sticker, contacts, reaction,
+#    location, address, location_request, template, interactive
+```
+
+## Interactive header errors
+
+`Interactive::Header` raises `HeaderError` rather than adding a validation error,
+because a header missing its content cannot be serialized at all:
+
+```ruby
+Whatsapp::Messages.send_interactive!(
+  to: "+15551234567", type: :reply_buttons, body: "Pick one",
+  header: { type: "image" },
+  action: { buttons: [{ id: "a", title: "A" }] }
+)
+# => Whatsapp::Messages::Interactive::Header::HeaderError:
+#    Image link is required for image header
+```
+
+## Retrying
+
+Meta's transient failures are ordinary HTTP: 429 for rate limiting, 5xx for outages.
+The gem does not retry — that policy belongs to your job queue:
+
+```ruby
+class SendWhatsappJob < ApplicationJob
+  retry_on Whatsapp::RequestError, wait: :polynomially_longer, attempts: 5
+  discard_on ActiveModel::ValidationError   # our payload is wrong; retrying won't fix it
+
+  def perform(to:, body:)
+    Whatsapp::Messages.send_text!(to:, body:)
+  end
+end
+```
+
+Discarding on `ActiveModel::ValidationError` is the important half: a locally invalid
+payload will fail identically on every attempt.
+
+> **Rate limits worth knowing.** Template edits are capped at 10 per 30 days and 1 per
+> 24 hours; `Register`/`Deregister` at 10 per number per 72-hour window (error
+> `133016`). None is observable client-side — they arrive as API errors.

data/docs/media/README.md

@@ -0,0 +1,161 @@
+# Media
+
+Upload, locate, download, and delete media assets on the Cloud API. An uploaded asset
+gets a **media ID** you can pass to [image](../messages/image.md),
+[video](../messages/video.md), [audio](../messages/audio.md),
+[document](../messages/document.md), and [sticker](../messages/sticker.md) messages
+instead of a public URL.
+
+Addresses your **phone number** (`phone_id`), like
+[messages](../messages/README.md).
+
+```ruby
+media = Whatsapp::Media.new    # or .new(client: my_client)
+
+media_id = media.upload(file_path: "photo.jpg", type: "image/jpeg")
+info     = media.get_url(media_id: media_id)
+media.download(url: info["url"], save_to: "photo.jpg")
+media.delete(media_id: media_id)
+```
+
+| Method | Request | Returns |
+| --- | --- | --- |
+| `upload(file_path:, type:)` | `POST /{phone_id}/media` (multipart) | `String` media ID |
+| `get_url(media_id:)` | `GET /{media_id}?phone_number_id=` | `Hash` |
+| `download(url:, save_to:)` | `GET <url>` with the bearer token | `String` — the path written |
+| `delete(media_id:)` | `DELETE /{media_id}?phone_number_id=` | `Boolean` |
+
+## Uploading
+
+```ruby
+media_id = Whatsapp::Media.new.upload(file_path: "photo.jpg", type: "image/jpeg")
+# => "1234567890123456"
+```
+
+The file must exist — checked **before** the request, so a typo costs nothing:
+
+```ruby
+Whatsapp::Media.new.upload(file_path: "nope.jpg", type: "image/jpeg")
+# => Whatsapp::Media::MediaError: File not found: nope.jpg
+```
+
+### Why prefer an ID over a link
+
+Sending by `link:` makes Meta re-download the file on **every send**. Uploading once
+and reusing the ID is faster, cheaper, and avoids your CDN being hammered:
+
+```ruby
+media_id = media.upload(file_path: "catalogue.pdf", type: "application/pdf")
+
+recipients.each do |to|
+  Whatsapp::Messages.send_document!(to: to, id: media_id, filename: "catalogue.pdf")
+end
+```
+
+> **Not for template headers.** A media header on a *template* takes a
+> `header_handle` from Meta's Resumable Upload API, which this gem does not wrap.
+> These media IDs are for **sending**, not template creation — see
+> [../message_templates/README.md](../message_templates/README.md#not-wrapped).
+
+## Getting a download URL
+
+```ruby
+info = Whatsapp::Media.new.get_url(media_id: "1234567890123456")
+# => { "url" => "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=...",
+#      "mime_type" => "image/jpeg", "sha256" => "...", "file_size" => 12345,
+#      "id" => "1234567890123456" }
+```
+
+The URL is short-lived and requires the bearer token — you cannot hand it to a browser.
+Fetch it with `#download`.
+
+This is the step after receiving an inbound media message:
+
+```ruby
+message.media_id      # from a webhook Message::Image / Video / Audio / Document / Sticker
+info = media.get_url(media_id: message.media_id)
+```
+
+## Downloading
+
+```ruby
+Whatsapp::Media.new.download(url: info["url"], save_to: "photo.jpg")
+# => "photo.jpg"
+```
+
+The response body is streamed to disk chunk by chunk rather than buffered, so a large
+video doesn't have to fit in memory.
+
+### The token never leaves the allowlist
+
+`#download` attaches your API token to the request, which makes the destination URL
+security-relevant. Two guards run before anything is sent:
+
+1. **HTTPS only.** A plain-HTTP URL is refused outright.
+2. **Allowlisted hosts only.** The host must be on
+   `Configuration#media_host_allowlist`, which defaults to
+   `lookaside.fbsbx.com`, `mmg.whatsapp.net`, and `graph.facebook.com`.
+
+```ruby
+media.download(url: "http://lookaside.fbsbx.com/x", save_to: "f")
+# => Whatsapp::Media::MediaError: Refusing to download from non-HTTPS URL: http://...
+
+media.download(url: "https://evil.example.com/x", save_to: "f")
+# => Whatsapp::Media::MediaError: Refusing to send credentials to non-allowlisted host:
+#    evil.example.com
+```
+
+Matching is exact host or a dotted subdomain, so `evil-fbsbx.com` and
+`fbsbx.com.attacker.com` are both rejected — a substring check would have let both
+through.
+
+Override the list if Meta serves you from a different host:
+
+```ruby
+Whatsapp.configure do |config|
+  config.media_host_allowlist = %w[lookaside.fbsbx.com mmg.whatsapp.net my-proxy.internal]
+end
+```
+
+## Deleting
+
+```ruby
+Whatsapp::Media.new.delete(media_id: "1234567890123456")   # => true
+```
+
+Returns a strict boolean from Meta's `{"success": true}`. A non-2xx response raises
+instead of returning `false`, so `false` genuinely means Meta declined.
+
+## Errors
+
+Every failure raises `Whatsapp::Media::MediaError`:
+
+| Message | Cause |
+| --- | --- |
+| `File not found: <path>` | `upload` — checked locally before any request |
+| `Invalid media URL: <detail>` | `download` — the URL didn't parse |
+| `Refusing to download from non-HTTPS URL: <url>` | `download` — HTTP scheme |
+| `Refusing to send credentials to non-allowlisted host: <host>` | `download` — host not on the allowlist |
+| `Failed to upload media: 400 ...` | Non-2xx from the API |
+| `Failed to get media URL: ...` / `Failed to download media: ...` / `Failed to delete media: ...` | Non-2xx from the API |
+
+Error bodies are truncated at 500 characters. See [../errors.md](../errors.md).
+
+## Round trip: receive, download, reply
+
+```ruby
+media = Whatsapp::Media.new
+
+change.value.messages.each do |message|
+  next unless message.respond_to?(:media_id)
+
+  info = media.get_url(media_id: message.media_id)
+  path = media.download(url: info["url"], save_to: Rails.root.join("tmp", message.id))
+
+  Whatsapp::Messages.send_text!(to: message.from, body: "Got your #{message.mime_type}, thanks!")
+end
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media>