ruby-whatsapp 0.4.0 → 0.6.1

data/docs/message_templates/carousel.md

@@ -0,0 +1,103 @@
+# Carousel Templates
+
+Two to ten swipeable cards under a shared body message — a product row, a set of
+listings, a group of offers.
+
+> **MARKETING only.** A carousel on a `UTILITY` or `AUTHENTICATION` template is
+> rejected locally:
+>
+> ```ruby
+> # => ActiveModel::ValidationError: Components CAROUSEL is only supported on
+> #    MARKETING templates, not UTILITY
+> ```
+
+```ruby
+card = {
+  header: { format: "IMAGE", header_handle: "4::aW..." },
+  body: { text: "Rare {{1}} in stock!", example: ["Tulips"] },
+  buttons: [{ type: :quick_reply, text: "More like this" }],
+}
+
+Whatsapp::MessageTemplates.new.create(
+  name: "summer_carousel", language: "en_US", category: "MARKETING",
+  components: [
+    { type: :body, text: "Summer is here, {{1}}!", example: ["Pablo"] },
+    { type: :carousel, cards: [card, card] },
+  ]
+)
+```
+
+The template still needs its own top-level `BODY` — the carousel sits *below* it.
+
+## Card structure
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `header` | yes | `format` must be `IMAGE` or `VIDEO` |
+| `body` | no | Same rules as a normal body |
+| `buttons` | no | **0–2** buttons per card |
+
+> **All cards must be structurally identical.** Same header format, same button types
+> in the same order, and body text on either every card or none. The gem computes a
+> signature per card and compares them:
+>
+> ```ruby
+> # => ActiveModel::ValidationError: Cards must all have an identical structure:
+> #    same header format, same button types, and body text on either every card or none
+> ```
+
+Meta says "up to 2" buttons and never states a minimum, so **zero buttons is valid**.
+
+## Serialized payload
+
+Each card serializes to a bare `{components: [...]}` — note there is **no
+`card_index`** here. That is send-side only:
+
+```ruby
+Whatsapp::MessageTemplates::Template.new(
+  name: "summer_carousel", language: "en_US", category: "marketing",
+  components: [
+    { type: :body, text: "Summer is here, {{1}}!", example: ["Pablo"] },
+    { type: :carousel, cards: [card, card] },
+  ]
+).serialize
+# => {
+#   name: "summer_carousel", language: "en_US", category: "MARKETING",
+#   parameter_format: "POSITIONAL",
+#   components: [
+#     { type: "BODY", text: "Summer is here, {{1}}!", example: { body_text: [["Pablo"]] } },
+#     { type: "CAROUSEL", cards: [
+#       { components: [
+#         { type: "HEADER", format: "IMAGE", example: { header_handle: ["4::aW..."] } },
+#         { type: "BODY", text: "Rare {{1}} in stock!", example: { body_text: [["Tulips"]] } },
+#         { type: "BUTTONS", buttons: [{ type: "QUICK_REPLY", text: "More like this" }] },
+#       ] },
+#       { components: [...] },
+#     ] },
+#   ]
+# }
+```
+
+## Media handles
+
+`header_handle` is **not** a media ID from [`Media#upload`](../media/README.md). It
+comes from Meta's Resumable Upload API, which this gem does not wrap — see
+[README.md § Not wrapped](README.md#not-wrapped).
+
+## Validation errors
+
+```ruby
+{ type: :carousel, cards: [card] }
+# => ActiveModel::ValidationError: Cards is too short (minimum is 2 characters)
+
+{ type: :carousel, cards: [card_with_image_header, card_with_video_header] }
+# => ActiveModel::ValidationError: Cards must all have an identical structure: ...
+
+{ header: { format: "TEXT", text: "Hi" }, body: ..., buttons: [...] }
+# => ActiveModel::ValidationError: Header format must be IMAGE or VIDEO
+#    for a carousel card, got TEXT
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/carousel-templates>

data/docs/message_templates/components.md

@@ -0,0 +1,215 @@
+# Components and Buttons Reference
+
+The complete registry of what a template can be built from. A component validates
+itself; `ComponentSet` validates how components relate to each other.
+
+## Component types
+
+Resolved through the frozen `Component::TYPES` registry — never `const_get` on caller
+input.
+
+| `type:` | Wire type | Purpose |
+| --- | --- | --- |
+| `:header` | `HEADER` | Text, media, or location above the body |
+| `:body` | `BODY` | **Required, exactly one** |
+| `:footer` | `FOOTER` | Small print below the body |
+| `:buttons` | `BUTTONS` | One component holding 1–10 buttons |
+| `:carousel` | `CAROUSEL` | [2–10 identical cards](carousel.md) |
+| `:limited_time_offer` | `LIMITED_TIME_OFFER` | [Countdown + coupon](limited_time_offer.md) |
+
+An unknown type raises before any request:
+
+```ruby
+# => Whatsapp::MessageTemplates::TemplateError: Unknown component type: :greeting.
+#    Known types: header, body, footer, buttons, carousel, limited_time_offer
+```
+
+### Header
+
+| `format` | Fields | Rules |
+| --- | --- | --- |
+| `TEXT` | `text`, `example` | ≤ **60** chars, **at most one** placeholder, no Markdown, no `header_handle` |
+| `IMAGE` `VIDEO` `DOCUMENT` `GIF` | `header_handle` | No `text` |
+| `LOCATION` | — | Nothing else; coordinates are supplied when sending |
+
+Max **one** header per template.
+
+The Markdown check rejects `*` `_` `~` `` ` `` in the literal text but **ignores
+placeholder contents** — named placeholders are lowercase-and-underscores by
+definition, so scanning raw text would reject `{{sale_start_date}}` for its underscore
+and make named parameters unusable in a text header.
+
+```ruby
+{ type: :header, format: "TEXT", text: "Order {{1}} confirmed", example: ["#1234"] }
+{ type: :header, format: "IMAGE", header_handle: "4::aW..." }
+{ type: :header, format: "LOCATION" }
+```
+
+A `LOCATION` header requires the category to be `UTILITY` or `MARKETING`.
+
+### Body
+
+**Required, exactly one per template.** Two mutually exclusive shapes:
+
+| Shape | Fields | Rules |
+| --- | --- | --- |
+| Text | `text`, `example` | ≤ **1024** chars, any number of placeholders, example count must match |
+| Authentication | `add_security_recommendation` | See [authentication.md](authentication.md) |
+
+```ruby
+{ type: :body, text: "Thank you, {{1}}!", example: ["Pablo"] }
+{ type: :body, add_security_recommendation: true }
+```
+
+Example count is checked against the **unique** placeholder count, so a repeated
+`{{1}}` needs one example, not two.
+
+### Footer
+
+Max **one**. Two mutually exclusive shapes:
+
+| Shape | Fields | Rules |
+| --- | --- | --- |
+| Text | `text` | ≤ **60** chars, **no placeholders at all** |
+| Authentication | `code_expiration_minutes` | Integer in **1..90** |
+
+```ruby
+{ type: :footer, text: "Thanks for shopping with us" }
+{ type: :footer, code_expiration_minutes: 15 }
+```
+
+Forbidden entirely alongside a [limited-time offer](limited_time_offer.md).
+
+### Buttons
+
+Max **one** `BUTTONS` component, holding **1–10** buttons.
+
+| Button type | Cap per template |
+| --- | --- |
+| `QUICK_REPLY` | 10 |
+| `URL` | 2 |
+| `PHONE_NUMBER` | 1 |
+| `COPY_CODE` | 1 |
+| `OTP` | uncapped — Meta publishes no limit |
+
+> **Quick replies must be contiguous.** They may sit at the start or the end, but not
+> with another type between them. `[QR, QR, URL]` and `[URL, QR, QR]` are fine;
+> `[QR, URL, QR]` raises `quick reply buttons must be grouped together, without other
+> types between them`.
+
+## Button types
+
+Resolved through the frozen `Button::TYPES` registry.
+
+| `type:` | Wire type | Fields |
+| --- | --- | --- |
+| `:quick_reply` | `QUICK_REPLY` | `text` ≤ **25** |
+| `:url` | `URL` | `text` ≤ 25, `url` ≤ **2000**, `example` |
+| `:phone_number` | `PHONE_NUMBER` | `text` ≤ 25, `phone_number` ≤ **20** |
+| `:copy_code` | `COPY_CODE` | `example` ≤ **20** (a bare String), **no `text`** |
+| `:otp` | `OTP` | `otp_type`, `supported_apps`, `zero_tap_terms_accepted` |
+| `:request_contact_info` | `REQUEST_CONTACT_INFO` | **no fields** — `text` optional and only ever `"Share Contact Info"` |
+
+```ruby
+{ type: :quick_reply,  text: "More like this" }
+{ type: :url,          text: "Track order", url: "https://example.com/o/{{1}}", example: "1234" }
+{ type: :phone_number, text: "Call", phone_number: "15550051310" }
+{ type: :copy_code,    example: "SPRING25" }
+{ type: :otp,          otp_type: "COPY_CODE" }
+{ type: :request_contact_info }
+```
+
+### The URL button's single trailing variable
+
+A URL button may contain **at most one variable, and it must be at the end**:
+
+```ruby
+{ type: :url, text: "Track", url: "https://example.com/{{1}}/details" }
+# => ActiveModel::ValidationError: Url variable must be at the end of the URL
+```
+
+> The URL variable is counted by **occurrence**, not by unique name, so
+> `.../{{1}}/details/{{1}}` is rejected: it ends in a placeholder and names one
+> parameter, but the leading one still sits mid-URL. Everywhere else — body examples
+> above all — the unique count is the correct one, since Meta treats a repeated
+> `{{1}}` as a single parameter needing a single example.
+
+Its `example` is a **flat array on the button**, unlike header and body examples,
+which are nested under an `example` key. A bare String is wrapped for you.
+
+### Buttons Meta supplies the label for
+
+`COPY_CODE` and `OTP` reject `text` (and `autofill_text`) — Meta writes and localises
+those labels:
+
+```ruby
+{ type: :copy_code, example: "SPRING25", text: "Copy" }
+# => ActiveModel::ValidationError: Text cannot be set on a copy-code button;
+#    Meta supplies the label
+```
+
+### The request-contact-info button
+
+Asks the recipient to share their phone number, which they hand over with one tap. It
+takes nothing:
+
+```ruby
+{ type: :buttons, buttons: [{ type: :request_contact_info }] }
+```
+
+This is the counterpart to Meta's usernames rollout: once a user adopts a username their
+phone number may stop reaching you, leaving only their
+[BSUID](../webhooks/messages.md#business-scoped-user-ids-bsuid). It is also the only way
+to reach such a user with a one-tap, zero-tap, or copy-code
+[authentication template](authentication.md), since those require a phone number.
+
+Three things about it:
+
+- **The label is not customizable.** Meta renders it in the recipient's own app language.
+  A `text` field is accepted but must be exactly `"Share Contact Info"`, so the simplest
+  correct thing is to omit it.
+- **`UTILITY` and `MARKETING` only** — a cross-component rule, listed below.
+- **Nothing to fill in when sending.** Unlike a URL or copy-code button, it takes no
+  parameter values, so a template carrying one needs no `button` component in the
+  [send payload](../messages/template.md) at all.
+
+A tap arrives as an inbound [`contacts` message](../webhooks/messages.md#contacts) whose
+`origin` is `"contact_request"`. There is also an
+[interactive-message form](../messages/interactive.md) of the same button, for use inside
+the 24-hour service window.
+
+No per-type cap is enforced: Meta publishes none, and inventing one would reject valid
+payloads — the same reason `OTP` is uncapped. The overall 10-button limit still applies.
+
+## Cross-component rules
+
+Owned by `ComponentSet`, because it is the only object that can see the siblings:
+
+- **Exactly one** `BODY`.
+- **At most one** each of `HEADER`, `FOOTER`, `BUTTONS`, `CAROUSEL`,
+  `LIMITED_TIME_OFFER`.
+- `CAROUSEL` or `LIMITED_TIME_OFFER` → category must be `MARKETING`.
+- A `LOCATION` header → category must be `UTILITY` or `MARKETING`.
+- A `REQUEST_CONTACT_INFO` button → category must be `UTILITY` or `MARKETING`.
+- `LIMITED_TIME_OFFER` present → `FOOTER` forbidden, `BODY` ≤ **600**, header
+  `IMAGE`/`VIDEO` only, copy-code `example` ≤ **15** and that button must be **first**.
+
+The category-dependent rules are **skipped when `category` is nil** — which is exactly
+what `#update` needs, since editing replaces components without re-supplying a
+category.
+
+## Not registered
+
+Only types with a published Meta field reference get a class. Named in Meta's Graph
+enum but deliberately absent:
+
+- **Components:** `GREETING`, `ALBUM`, `CALL_PERMISSION_REQUEST`,
+  `TAP_TARGET_CONFIGURATION`, `ATTACHMENT`.
+- **Buttons:** `FLOW`, `MPM`, `CATALOG`, `VOICE_CALL`, `VIDEO_CALL`, `POSTBACK`,
+  `BOOKING_STATUS`, `PAYMENT_REQUEST`. Most of these *are*
+  accepted by [`LibraryTemplate`](library.md), because Meta documents them by name in
+  that context.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/>

data/docs/message_templates/library.md

@@ -0,0 +1,98 @@
+# Library Templates
+
+Meta maintains a library of pre-written, pre-approved templates for common cases —
+delivery updates, appointment reminders, payment confirmations. Cloning one usually
+comes back **`APPROVED` immediately**, skipping the 24-hour review entirely.
+
+```ruby
+Whatsapp::MessageTemplates.new.create_from_library(
+  name: "my_delivery_update", language: "en_US", category: "UTILITY",
+  library_template_name: "delivery_update_1",
+  library_template_button_inputs: [
+    { type: "URL", url: { base_url: "https://example.com/{{1}}",
+                          url_suffix_example: "https://example.com/order_update" } },
+  ]
+)
+# => #<Response::Created id="1" status="APPROVED" category="UTILITY">
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `name` | yes | Your name for the clone. `/\A[a-z0-9_]+\z/`, max 512 |
+| `language` | yes | Validated against the supported list |
+| `category` | yes | `UTILITY` \| `MARKETING` \| `AUTHENTICATION` |
+| `library_template_name` | yes | Meta's name for the source template |
+| `library_template_body_inputs` | no | Body toggles — see below |
+| `library_template_button_inputs` | no | Button configuration — see below |
+
+> **No `components:` at all.** The wording is Meta's; you only supply the identity and
+> the few configurable inputs. That is the whole point of the library.
+
+## Body inputs
+
+| Field | Type |
+| --- | --- |
+| `add_contact_number` | Boolean |
+| `add_learn_more_link` | Boolean |
+| `add_security_recommendation` | Boolean |
+| `add_track_package_link` | Boolean |
+| `code_expiration_minutes` | Integer, **1–90** |
+
+```ruby
+library_template_body_inputs: {
+  add_contact_number: true,
+  add_track_package_link: true,
+}
+```
+
+## Button inputs
+
+`type` is one of `QUICK_REPLY` `URL` `PHONE_NUMBER` `OTP` `MPM` `CATALOG` `FLOW`
+`VOICE_CALL` `APP` — deliberately a **wider set** than the button types available to
+hand-built templates, because Meta documents these by name in the library context.
+
+| `type` | Required extra |
+| --- | --- |
+| `URL` | `url: { base_url:, url_suffix_example: }` |
+| `PHONE_NUMBER` | `phone_number:` |
+| `APP` | `supported_apps:` |
+| `OTP` | `otp_type:`, plus `zero_tap_terms_accepted:` for zero-tap |
+
+```ruby
+library_template_button_inputs: [
+  { type: "URL", url: { base_url: "https://example.com/{{1}}",
+                        url_suffix_example: "https://example.com/order_update" } },
+  { type: "PHONE_NUMBER", phone_number: "15550051310" },
+]
+```
+
+## Validation errors
+
+```ruby
+{ type: "URL", url: {} }
+# => ActiveModel::ValidationError: Url requires a base_url for a URL button input
+
+{ type: "PHONE_NUMBER" }
+# => ActiveModel::ValidationError: Phone number can't be blank for a PHONE_NUMBER button input
+
+{ type: "APP" }
+# => ActiveModel::ValidationError: Supported apps can't be blank for an APP button input
+```
+
+## Unverified detail
+
+`library_template_button_inputs` is emitted as a **real JSON array**. Meta's guide
+shows a JSON-*stringified* array while the Graph reference types it
+`array<JSON object>`. This has not been settled against a live WABA — if Meta rejects
+the array form, it is a one-line change in `LibraryTemplate#serialize`.
+
+## Not wrapped
+
+Browsing the library itself (`message_template_library`) is not wrapped — find the
+`library_template_name` you want in WhatsApp Manager or Meta's docs.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-library>

data/docs/message_templates/limited_time_offer.md

@@ -0,0 +1,94 @@
+# Limited-Time Offer Templates
+
+Adds a live countdown and a copyable coupon code to a marketing message. The countdown
+is rendered by WhatsApp itself, so the urgency stays accurate no matter when the
+recipient opens the thread.
+
+> **MARKETING only**, and the presence of a `LIMITED_TIME_OFFER` component tightens
+> four other rules at once. See [The knock-on rules](#the-knock-on-rules).
+
+```ruby
+Whatsapp::MessageTemplates.new.create(
+  name: "spring_offer", language: "en_US", category: "MARKETING",
+  components: [
+    { type: :header, format: "IMAGE", header_handle: "4::aW..." },
+    { type: :limited_time_offer, text: "Expiring offer!", has_expiration: true },
+    { type: :body, text: "Good news, {{1}}! Use code {{2}} for 25% off.",
+      example: ["Pablo", "SPRING25"] },
+    { type: :buttons, buttons: [
+      { type: :copy_code, example: "SPRING25" },
+      { type: :url, text: "Book now!", url: "https://example.com/o?c={{1}}", example: "n3mtql" },
+    ] },
+  ]
+)
+```
+
+## The component
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `text` | yes | Max **16** characters — the offer label |
+| `has_expiration` | no | `true` shows the countdown |
+
+It serializes nested, unlike every other component:
+
+```ruby
+{ type: "LIMITED_TIME_OFFER", limited_time_offer: { text: "Expiring offer!", has_expiration: true } }
+```
+
+## The knock-on rules
+
+Adding a limited-time offer changes what the rest of the template may contain. These
+are enforced by `ComponentSet`, which is the only object that can see all the
+components at once:
+
+| Rule | Error if violated |
+| --- | --- |
+| **No `FOOTER`** at all | `a FOOTER is not allowed in a LIMITED_TIME_OFFER template` |
+| `BODY` drops to **600** chars (from 1024) | `the BODY of a LIMITED_TIME_OFFER template is limited to 600 characters` |
+| Header must be **`IMAGE` or `VIDEO`** | `the header must be IMAGE or VIDEO in a LIMITED_TIME_OFFER template, got TEXT` |
+| Copy-code button must be **first** | `the copy-code button must be first in a LIMITED_TIME_OFFER template` |
+| Copy-code `example` ≤ **15** chars (from 20) | `the copy-code example is limited to 15 characters in a LIMITED_TIME_OFFER template` |
+
+## Serialized payload
+
+```ruby
+Whatsapp::MessageTemplates::Template.new(
+  name: "limited_time_offer_caribbean_pkg_2023", language: "en_US", category: "marketing",
+  components: [
+    { type: :header, format: "image", header_handle: "4::aW" },
+    { type: :limited_time_offer, text: "Expiring offer!", has_expiration: true },
+    { type: :body, text: "Good news, {{1}}! Use code {{2}} to get 25% off!",
+      example: ["Pablo", "CARIBE25"] },
+    { type: :buttons, buttons: [
+      { type: :copy_code, example: "CARIBE25" },
+      { type: :url, text: "Book now!", url: "https://x.test/offers?code={{1}}", example: "n3mtql" },
+    ] },
+  ]
+).serialize
+# => {
+#   name: "limited_time_offer_caribbean_pkg_2023", language: "en_US", category: "MARKETING",
+#   parameter_format: "POSITIONAL",
+#   components: [
+#     { type: "HEADER", format: "IMAGE", example: { header_handle: ["4::aW"] } },
+#     { type: "LIMITED_TIME_OFFER",
+#       limited_time_offer: { text: "Expiring offer!", has_expiration: true } },
+#     { type: "BODY", text: "Good news, {{1}}! Use code {{2}} to get 25% off!",
+#       example: { body_text: [["Pablo", "CARIBE25"]] } },
+#     { type: "BUTTONS", buttons: [
+#       { type: "COPY_CODE", example: "CARIBE25" },
+#       { type: "URL", text: "Book now!", url: "https://x.test/offers?code={{1}}",
+#         example: ["n3mtql"] }] },
+#   ]
+# }
+```
+
+## Media handles
+
+`header_handle` comes from Meta's Resumable Upload API, not
+[`Media#upload`](../media/README.md) — see
+[README.md § Not wrapped](README.md#not-wrapped).
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/limited-time-offer-templates>

data/docs/message_templates/responses.md

@@ -0,0 +1,173 @@
+# Template Responses
+
+Four endpoints, four response shapes — so four classes rather than one that is mostly
+`nil`.
+
+| Method | Returns |
+| --- | --- |
+| `create`, `create_from_library`, `upsert` | [`Response::Created`](#created) |
+| `find` | [`Response::Node`](#node) |
+| `list` | [`Response::Collection`](#collection) |
+| `update`, `delete` | plain `Boolean` |
+
+## Created
+
+`{id, status, category}` — what you get back from a submission.
+
+```ruby
+created = templates.create(name: "order_confirmation", language: "en_US",
+                           category: "UTILITY", components: [...])
+
+created.id        # => "1259544702043867"
+created.status    # => "PENDING"
+created.category  # => "UTILITY"
+
+created.pending?  # => true
+created.approved? # => false
+created.rejected? # => false
+```
+
+A [library template](library.md) usually comes back `APPROVED` immediately; everything
+else starts `PENDING` and is reviewed asynchronously.
+
+## Node
+
+The full template object, from `find`.
+
+```ruby
+template = templates.find(template_id: "564750795574598")
+```
+
+| Accessor | Example |
+| --- | --- |
+| `id` | `"564750795574598"` |
+| `name` | `"order_confirmation"` |
+| `status` | `"APPROVED"` |
+| `category` | `"UTILITY"` |
+| `language` | `"en_US"` |
+| `components` | **raw hashes** — see below |
+| `parameter_format` | `"POSITIONAL"` |
+| `sub_category` | `"ORDER_DETAILS"` |
+| `rejected_reason` | `"NONE"` |
+| `quality_score` | `#<QualityScore score="GREEN" date=1700000000 reasons=[]>` |
+| `previous_category` | `"MARKETING"` |
+| `correct_category` | `"UTILITY"` |
+| `message_send_ttl_seconds` | `3600` |
+| `cta_url_link_tracking_opted_out` | `false` |
+| `library_template_name` | `"delivery_update_1"` |
+
+Predicates: `#approved?`, `#rejected?`, `#paused?`, and `#editable?` (true for
+`APPROVED`, `REJECTED`, and `PAUSED`).
+
+```ruby
+template.status     # => "APPROVED"
+template.editable?  # => true
+```
+
+> **`#components` stays raw hashes on purpose.** It is not rebuilt into the
+> `Component` classes. Those validate a payload being *written*; this is Meta's echo of
+> one, carrying fields the write side does not model. Running write-side rules over
+> data we did not author would raise on perfectly valid responses. Read it as data;
+> build a new `Template` when you want to change something.
+
+```ruby
+template.components
+# => [{ "type" => "BODY", "text" => "Thank you, {{1}}!",
+#       "example" => { "body_text" => [["Pablo"]] } }]
+```
+
+## Collection
+
+`{data, paging, summary}` from `list`. It is `Enumerable`, so it behaves like the array
+of `Node`s it wraps.
+
+```ruby
+page = templates.list(status: %w[APPROVED], limit: 25)
+
+page.map(&:name)                    # => ["order_confirmation", ...]
+page.select(&:approved?)            # Enumerable
+page.next_cursor                    # => "AFTER" — nil on the last page
+page.remaining                      # => 249
+```
+
+| Accessor | Holds |
+| --- | --- |
+| `data` | `Array<Response::Node>` |
+| `paging` | `Response::Paging` — `before`, `after` (flattened from `paging.cursors`) |
+| `summary` | `Response::Summary` |
+
+`#next_cursor` is `paging&.after`; `#remaining` is `summary&.remaining`.
+
+### Summary
+
+| Accessor | Meaning |
+| --- | --- |
+| `total_count` | Templates matching the filter |
+| `message_template_count` | Templates on the account |
+| `message_template_limit` | The account's cap |
+| `are_translations_complete` | Boolean |
+| `remaining` | `limit - count`, or `nil` when either is missing |
+
+```ruby
+page.summary.message_template_count  # => 12
+page.summary.message_template_limit  # => 250
+page.remaining                       # => 238
+```
+
+### Paging
+
+Manual — there is no auto-pagination:
+
+```ruby
+page = templates.list(limit: 25)
+all  = page.to_a
+
+while (cursor = page.next_cursor)
+  page = templates.list(limit: 25, after: cursor)
+  all.concat(page.to_a)
+end
+```
+
+### QualityScore
+
+```ruby
+template.quality_score.score    # => "GREEN"  — GREEN | YELLOW | RED | UNKNOWN
+template.quality_score.date     # => 1_700_000_000
+template.quality_score.reasons  # => []
+```
+
+Best-effort schema on `reasons` — Meta publishes no sub-fields for it.
+
+## Booleans
+
+`update` and `delete` return a plain `true`/`false` derived from `{"success": true}`:
+
+```ruby
+templates.update(template_id: "564750795574598", category: "MARKETING")  # => true
+templates.delete(name: "order_confirmation")                             # => true
+```
+
+A non-2xx response raises `Whatsapp::MessageTemplates::TemplateError` instead of
+returning `false`, so `false` genuinely means "Meta said no", not "the request failed".
+
+## Statuses
+
+| Status | Meaning |
+| --- | --- |
+| `PENDING` | Under review |
+| `APPROVED` | Sendable |
+| `REJECTED` | Refused — see `rejected_reason` |
+| `PAUSED` | Temporarily halted for quality |
+| `DISABLED` | Permanently disabled; cannot be deleted |
+| `IN_APPEAL` | Rejection under appeal |
+| `PENDING_DELETION` | Deletion queued |
+| `DELETED` | Gone |
+| `LIMIT_EXCEEDED` | Account template cap hit |
+| `ARCHIVED` | Archived |
+
+`rejected_reason` is one of `NONE`, `ABUSIVE_CONTENT`, `INVALID_FORMAT`,
+`PROMOTIONAL`, `TAG_CONTENT_MISMATCH`, `SCAM`.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/docs/graph-api/reference/whats-app-business-hsm/>