sendly 3.37.1 → 3.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5da119e52e96f793ddd86099f4f49ef94a5dc50965d480c84e23a43e5d0fa3c2
-  data.tar.gz: f1fd1ae9ba13230e5a939594e3b5049bae6251daa064d5399cfe4a23b4937637
+  metadata.gz: c474ade97511ceecadbff15268b602edb67953395417996e9c1ac8b7626e68ff
+  data.tar.gz: b034a8b316eab9f85e98de49e31db3045326662beeefbafb306844302a147037
 SHA512:
-  metadata.gz: 0a2f993fa684453f88a91144800c2808bcaaad51cbccbc88a982908f8b6ec6d6b7905a24374b1c56d6b1b6b8bb9c8b65a7004133e0f0859a33873be8c4dc5933
-  data.tar.gz: e8d9bb57bbaee7a50bc13ae7237267eb1ec3a3237814be3f9351ff7d43d8ddc9174b663dea7e23b6b02c1c36b2c36930f432c7eb2ac7b493710a458353ce313a
+  metadata.gz: 10f0a1eecb587b5c0b801c1abb5366d41caaa4fecf7e274ac3a37860d82bbdf92ca644280a419626391d0fce53679c35172a66aca3f26893d780bb499321c15c
+  data.tar.gz: 0221a6cfd5de361ff4648b4b4e0256ceccf4bab50e3b44b2616cd2200c136c2acd27409c3b20a99f2f81176663e0e272664a07d07f113d29d2b2064a0546bd33

data/CHANGELOG.md

@@ -1,5 +1,89 @@
 # sendly (Ruby)
 
+## Unreleased
+
+### Minor Changes
+
+- **`Sendly::ValidationError#field_errors` is now populated.** It was always `nil` before, because the API path never passed it. It now carries the response body's `errors` array on any 400 or 422, on every resource rather than just RCS: `client.contacts.import` already returns one, for example. Each entry is a Hash. Code that treats a truthy `field_errors` as "this only happens for X" should be rechecked.
+
+
+- **RCS agent registration is self-serve from the SDK.** `client.rcs` gains `registration.get`, `dossier.get`, `brands.create` / `brands.update`, and `agents.create` / `get` / `update` / `set_test_devices` / `submit` / `request_launch`, mirroring the dashboard: draft the brand and agent, submit them for Sendly's review, invite test devices once the agent is in testing, then request launch. Reads need the `rcs:read` scope and writes `rcs:write`; test and live keys both work. Nested hashes (address, contact, basics, campaign, testing) accept snake_case or camelCase keys. Logo, hero and call-to-action media must be public `https://` URLs; assets cannot be uploaded over the API. New models: `Sendly::RcsRegistration` (with `CUSTOMER_STAGES`, `REVIEW_STATUSES` and `ERROR_CODES`), `Sendly::RcsDossier`, `Sendly::RcsBrand`, `Sendly::RcsAddress`, `Sendly::RcsContact`, `Sendly::RcsAgentRegistration`, `Sendly::RcsAgentBasics`, `Sendly::RcsAgentCampaign`, `Sendly::RcsCampaignInteraction`, `Sendly::RcsConsentSettings`, `Sendly::RcsOptInMethod`, `Sendly::RcsAgentTesting` and `Sendly::RcsTestDevice`. `Sendly::RcsAgent` (from `agents.list`) gains `stage`. Every route stays behind the RCS rollout: while it is off for your account these calls raise `Sendly::NotFoundError` with `rcs_not_enabled`.
+
+  ```ruby
+  dossier = client.rcs.dossier.get
+  brand = client.rcs.brands.create(**dossier.brand)
+  agent = client.rcs.agents.create(brand_id: brand.id, display_name: "Acme Coffee",
+                                   use_case: "MULTI_USE",
+                                   basics: { logo_url: "https://acme.example/rcs/logo.png" })
+  client.rcs.agents.submit(agent.id, idempotency_key: "rcs-submit-#{agent.id}")
+  ```
+
+- **`client.patch` and `client.put` accept `idempotency_key:`.** Neither generates a key on its own (unchanged), but a key you pass is now sent, so the RCS `update` and `set_test_devices` calls can be replayed safely.
+
+- **`Sendly::ValidationError#field_errors` carries the API's `errors` list** (`[{ "path", "message" }, ...]`) when a 400 or 422 response includes one, instead of always being `nil`. RCS registration uses it to say which brand, agent, campaign or device field needs attention.
+
+## 3.38.0
+
+### Minor Changes
+
+- **Every `POST` now sends an `Idempotency-Key` header.** The client generates one key per logical request (`sendly-ruby-retry-<uuid>`) and holds it across its own retries, so a request that already reached the server before a rate-limit retry is recognised as a repeat instead of being executed a second time. The server records a key only once the first attempt has finished, so this narrows the duplicate-send window rather than closing it: a retry that fires while the original is still running is not seen as a repeat. No code change is needed to get this. To extend the same protection across process restarts or your own retry loop, supply the key yourself:
+
+  ```ruby
+  client.messages.send(
+    to: "+15551234567",
+    text: "Your order shipped",
+    idempotency_key: "order-4821-shipped"
+  )
+  ```
+
+  Repeating a request with the same key inside 24 hours returns the original response instead of sending again. `idempotency_key:` is accepted on `messages.send` (the SMS, WhatsApp and RCS branches alike), `messages.send_group`, `messages.schedule`, `messages.send_batch`, and on `client.post` for any call you assemble by hand. A key must be 1 to 255 printable ASCII characters. Surrounding whitespace is trimmed, an empty or whitespace-only key is treated as if you passed nothing, and anything else raises `Sendly::ValidationError` before a request leaves the process.
+
+- **How keys behave across retries.** On a rate-limit retry the same key is reused. On a 5xx retry an auto-generated key is swapped for a fresh one, because the server responded, so the outcome is known and the retry should be a fresh attempt rather than a repeat of the failed one. The server does not record a 5xx against a key either. A key you supplied is never swapped, which is the whole point of supplying one. `messages.send_batch` is the deliberate exception: it sends no auto-generated key, because the batch endpoint already dedupes header-less retries by hashing the send itself and an auto key would step around that safety net. A key you pass to `send_batch` yourself is still sent. Worth knowing: this client raises `Sendly::TimeoutError` on a timeout rather than retrying, so a timeout is exactly the case where you should pass your own `idempotency_key:` before retrying by hand.
+
+- **Multipart uploads carry a key as well.** `media.upload`, the enterprise verification-document upload, and `business_upgrade.start` / `business_upgrade.resubmit` now attach an auto-generated `Idempotency-Key` to their uploads, so a retried document upload is far less likely to land twice. These methods generate the key internally and do not take an `idempotency_key:` argument yet.
+
+- **Templates were addressing a path the API does not serve. They now work.** Every method on `client.templates` other than `generate` pointed at `/verify/templates...`, which is not registered at any version of the API, so `list`, `get`, `create`, `update`, `delete` and `publish` could only ever raise `Sendly::NotFoundError`. They now address `/api/v1/templates`, which is served, and have been exercised end to end against production. If you wrote code against this resource and concluded it was broken, note carefully that it is live now: calls that previously failed without side effects will really create, edit, publish and delete templates.
+
+- **`Sendly::Template` now mirrors what the API actually returns**, and templates have a draft/published lifecycle. The response body field is `text`, not `body`, and a template carries `status` (`"draft"` or `"published"`, see the new `Sendly::Template::STATUSES`), `version`, `published_at`, `is_preset` and `preset_slug`. New templates are always created as drafts; call `publish` to make one usable. Only drafts can be edited, so an `update` on a published template is rejected by the API, and preset templates cannot be edited at all.
+
+  ```ruby
+  t = client.templates.create(name: "Order shipped", text: "Hi {{name}}, order {{order_id}} has shipped!")
+  t.status          # => "draft"
+  client.templates.publish(t.id)
+  client.templates.list[:templates].each { |x| puts "#{x.name}: #{x.status}" }
+  ```
+
+- **Template members that disappeared in the reshape are back, and deprecated.** If your editor or `ruby -w` starts pointing at these, this is why:
+  - `Template#body` is an alias of `#text`. Use `#text`.
+  - `Template#type` is derived from `#is_preset` and still returns `"preset"` or `"custom"`. Use `#is_preset` or `#preset?`. `Template::TYPES` is kept for the same reason.
+  - `Template#is_published` is derived from `#status`. Use `#status` or `#published?`.
+  - `Template#locale` is **always `nil`** and `Template#is_default` is **always `false`**. These are not deprecated in favour of anything: templates are not scoped by locale and the API has no concept of a default template, so it returns no such fields. There is no replacement. Keep per-locale wording in separate templates.
+
+  `Template#to_h` includes all of the above alongside the current fields, so hashes built from it keep their old keys.
+
+- **Deprecated template keyword arguments now raise instead of lying.** `templates.list` accepts `limit:`, `type:` and `locale:` again, and `templates.create` / `templates.update` accept `body:`, `locale:` and `is_published:` again, but the ones the API cannot honour raise `ArgumentError` with an explanation rather than silently doing nothing:
+  - `list(limit:)` and `list(type:)` raise: the list route returns every visible template in one response and neither paginates nor filters. Slice the returned array, or select over it with `Template#preset?` / `#custom?`. `list` still returns a `:pagination` key so existing destructuring does not blow up, but it is always `nil`.
+  - `locale:` raises everywhere it is accepted.
+  - `create(is_published: true)` and `update(is_published: true)` raise, and point you at `publish(id)`. `is_published: false` is accepted as a no-op, since templates are created as drafts and an update never changes status.
+  - `body:` on `create` and `update` is accepted and sent as `text`. Prefer `text:`.
+
+- **API key management was pointed at routes that do not exist.** `account.api_keys`, `account.api_key(id)` and `account.api_key_usage(id)` requested `/keys...`, which the versioned API does not serve, so they returned 404 no matter what. They now use `/account/keys...`. `account.api_keys` also unwraps the `keys` envelope the API returns, which it previously did not, so it now gives you the `Sendly::ApiKey` array its signature always promised.
+
+- **`account.revoke_api_key` could never revoke anything.** It sent `DELETE /account/keys/:id`, and that path is registered for `GET` only, so every revocation failed. It now sends `PATCH /account/keys/:id/revoke`, which is the verb the server accepts, takes an optional `reason:` recorded on the key's audit trail, and returns the `{ "id", "name", "revoked", "revokedAt" }` hash from the API instead of nothing. Treat this as live: code that has been calling it fruitlessly will now actually revoke keys.
+
+  ```ruby
+  client.account.revoke_api_key("key_abc123", reason: "rotated")
+  ```
+
+- **`account.transactions` raised `TypeError` on every call.** The endpoint returns `{ "transactions": [...] }` and the SDK mapped over that hash directly, so it tried to index an array with a string and blew up before you saw any data. It now unwraps the envelope and returns `Sendly::CreditTransaction` objects, or an empty array for an account with no history. One caveat: `offset:` is still accepted by the method but the endpoint ignores it, so it has no effect. `limit:` works and the server caps it at 100 (50 when omitted).
+
+- **Not fixed, so you are not left hunting:** `templates.unpublish` and `templates.clone` now address `/api/v1/templates/:id/unpublish` and `/api/v1/templates/:id/clone`, but the versioned API serves neither route, so both still fail with a 404. Their docs say so. To retire a published template today, create and publish a replacement and delete the old one; to copy one, read it with `get` and pass its `text` to `create`. Separately, `account.create_api_key` still fails with a 400: the API requires a `type` of `"test"` or `"live"` and the SDK does not send one. Mint keys from the dashboard until that is fixed.
+
+### Patch Changes
+
+- **`faraday` and `faraday-retry` are deprecated dependencies.** The client is built on Ruby's standard-library `net/http` and has not used Faraday at runtime for some time. Both gems stay declared in the gemspec so that this minor release does not pull a dependency out from under anyone resolving it transitively, but they are unused and are slated for removal in the next major version. The README no longer lists Faraday as a requirement.
+- The gem's packaged file list is now an explicit manifest plus `lib/**/*.rb` and `examples/**/*.rb`, rather than a `git ls-files` shell-out. The contents are unchanged, but building the gem from a source tree that is not a git checkout now produces the same gem instead of an empty one.
+
 ## 3.33.0
 
 ### Minor Changes
@@ -87,7 +171,7 @@
 
 - `/api/v1/enterprise/workspaces/:id/verification/submit` now returns specific missing-field errors (e.g. `"Missing required fields: website"`) instead of listing every required field whether present or not.
 - Endpoint accepts both flat and `{ verification: {...} }` wrapped shapes (matches `/enterprise/provision`).
-- `use_case` validation expanded from 23 entries to the full 43-value Telnyx enum.
+- `use_case` validation expanded from 23 entries to the full 43-value carrier use-case enum.
 
 ## 3.29.0
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sendly (3.37.1)
+    sendly (3.39.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 
@@ -74,7 +74,7 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
     uri (1.1.1)
-    webmock (3.26.2)
+    webmock (3.26.4)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)

data/README.md

@@ -280,6 +280,32 @@ puts result.explanation  # what changed and why
 puts result.model        # model used (when available)
 ```
 
+## Idempotency
+
+Every POST carries an automatically generated `Idempotency-Key` header, held
+across the client's own rate-limit retries, so a retry of a request that
+already reached the API returns the original result instead of sending and
+charging again. Pass your own key (1-255 printable ASCII characters) when the
+guarantee needs to outlive the process, such as a job queue that re-runs after
+a crash or your own retry loop; `idempotency_key:` is accepted on
+`messages.send`, `send_group`, `schedule`, and `send_batch`.
+
+```ruby
+message = client.messages.send(
+  to: "+15551234567",
+  text: "Your order has shipped!",
+  idempotency_key: "order-4821-shipped"
+)
+```
+
+Repeating a request with the same key within 24 hours returns the original
+response; `send_batch` sends no automatic key, because the API already
+deduplicates identical batches by their contents. Note this client raises
+`Sendly::TimeoutError` instead of retrying a timeout, so a timeout is exactly
+when to retry with your own key.
+
+Full details: https://sendly.live/docs/idempotency
+
 ## Webhooks
 
 ```ruby
@@ -330,13 +356,13 @@ puts "Total: #{credits['balance']} credits"
 # View credit transaction history
 transactions = client.account.transactions
 transactions.each do |tx|
-  puts "#{tx['type']}: #{tx['amount']} credits - #{tx['description']}"
+  puts "#{tx.type}: #{tx.amount} credits - #{tx.description}"
 end
 
 # List API keys
 keys = client.account.api_keys
 keys.each do |key|
-  puts "#{key['name']}: #{key['prefix']}*** (#{key['type']})"
+  puts "#{key.name}: #{key.prefix} (#{key.type})"
 end
 
 # Create a new API key
@@ -457,20 +483,17 @@ client.campaigns.delete(campaign.id)
 Reusable message templates with variables. AI can also draft one for you.
 
 ```ruby
-# Create / list / get
+# Create / list / get. New templates start as drafts; publish to lock one for use.
 template = client.templates.create(
   name: "Order shipped",
-  body: "Hi {{name}}, order #{{order_id}} has shipped!",
-  is_published: true
+  text: "Hi {{name}}, order {{order_id}} has shipped!"
 )
-client.templates.list(type: "custom")[:templates].each { |t| puts t.name }
+client.templates.list[:templates].each { |t| puts "#{t.name} — #{t.status}" }
 t = client.templates.get(template.id)
 
-# Update, publish/unpublish, clone
-client.templates.update(template.id, body: "Hi {{name}}, your order is on the way!")
+# Update (drafts only), publish, delete
+client.templates.update(template.id, text: "Hi {{name}}, your order is on the way!")
 client.templates.publish(template.id)
-client.templates.unpublish(template.id)
-client.templates.clone(template.id, name: "Order shipped (copy)")
 client.templates.delete(template.id)
 
 # Generate a template with AI
@@ -745,6 +768,276 @@ status = client.links.update(link.code, disabled: true)
 puts status.disabled?
 ```
 
+## WhatsApp
+
+Connect a number you own to WhatsApp, create Meta-reviewed message
+templates, and send via `client.messages.send(channel: "whatsapp", ...)`.
+Connecting is a one-time $19 setup (no monthly fee) and always ends with a
+human step: the signup returns a connect URL a person must open in a
+browser and log in with Facebook to link their WhatsApp Business Account.
+
+Free-form text and media only deliver inside a 24-hour customer-service
+window (opened by the recipient messaging you); an approved template works
+anytime. Templates are reviewed by Meta (typically 24-48h) and categorized
+as authentication, utility, or marketing — pricing follows the category and
+destination country. Note: Meta has paused marketing template delivery to
+US (+1) numbers.
+
+```ruby
+# 1. Connect a number ($19 one-time; a human must open the connect URL)
+signup = client.whatsapp.signup.create(phone_number: "+15559876543")
+puts "Have your user open: #{signup.connect_url}"
+
+# 2. Poll until active
+status = client.whatsapp.signup.get(signup.id)
+puts status.failure_reasons if status.failed?
+
+# List your connected senders
+client.whatsapp.senders.list[:senders].each do |s|
+  puts "#{s.phone_number} (#{s.display_name || 'no name yet'}) — #{s.status}"
+end
+
+# Read and update a sender's business profile (what recipients see when
+# they open your details in WhatsApp)
+profile = client.whatsapp.senders.get_profile("+15559876543")
+puts profile.display_name
+puts profile.about
+
+client.whatsapp.senders.update_profile(
+  "+15559876543",
+  about: "Fresh roasted coffee, delivered.",               # max 139 chars
+  description: "Small-batch roaster shipping nationwide.", # max 512 chars
+  website: "https://acme.example"
+)
+
+# 3. Create a template (Meta reviews it, usually 24-48h)
+template = client.whatsapp.templates.create(
+  sender: "+15559876543",
+  name: "order_shipped",
+  language: "en_US",
+  category: "UTILITY",
+  body: "Hi {{1}}, your order {{2}} has shipped!",
+  examples: { "1" => "Sam", "2" => "#4821" }
+)
+puts template.status  # "PENDING"
+
+# List, edit-and-resubmit (the recovery path for rejections), or delete
+client.whatsapp.templates.list[:templates].each { |t| puts "#{t.name} — #{t.status}" }
+client.whatsapp.templates.update(template.id, body: "Hi {{1}}, order {{2}} is on its way!",
+                                              examples: { "1" => "Sam", "2" => "#4821" })
+client.whatsapp.templates.delete(template.id)
+
+# 4. Send — free-form inside an open 24h window, template anytime
+window = client.whatsapp.window(from: "+15559876543", to: "+15551234567")
+if window.open?
+  client.messages.send(
+    channel: "whatsapp",
+    to: "+15551234567",
+    from: "+15559876543",
+    text: "Your table is ready!"
+  )
+else
+  message = client.messages.send(
+    channel: "whatsapp",
+    to: "+15551234567",
+    from: "+15559876543",
+    template: {
+      name: "order_shipped",
+      language: "en_US",
+      variables: { "1" => "Acme Inc", "2" => "#4821" }
+    }
+  )
+  puts message.whatsapp.kind  # "template"
+end
+
+# Media with a caption (also window-bound; one attachment per message)
+client.messages.send(
+  channel: "whatsapp",
+  to: "+15551234567",
+  from: "+15559876543",
+  text: "Here is your receipt",
+  media_urls: ["https://example.com/receipt.pdf"]
+)
+```
+
+## RCS
+
+Send branded rich messages — text with suggested replies and actions, or
+rich cards with an image and buttons — through your workspace's RCS agent
+by passing `channel: "rcs"` to `client.messages.send`. Delivery is
+per-recipient: not every device or network supports RCS. Text sends fall
+back to plain SMS automatically (billed as SMS) unless you disable the
+fallback; rich cards have no SMS form and only deliver to RCS-capable
+recipients.
+
+The RCS channel is being rolled out gradually and is not yet generally
+available; until it is enabled for your account the endpoints read as
+absent and calls raise `Sendly::NotFoundError` (HTTP 404: `not_found` on
+sends and listing, `rcs_not_enabled` on registration). RCS sends and
+capability checks require a live API key.
+
+### Registering an agent
+
+Registration is self-serve, from the dashboard or the API. Draft the
+brand (the business) and the agent (what recipients see), submit them for
+Sendly's review, and once approved they go on to the carrier network for
+brand verification and agent review. The agent then reaches invited test
+devices only; when you have tested it, request launch and Sendly reviews
+the campaign before sending the launch on to the carrier network. Watch
+`customer_stage` (one of `Sendly::RcsRegistration::CUSTOMER_STAGES`) to
+see where a registration is.
+
+Registration reads need the `rcs:read` scope and writes `rcs:write`; test
+and live keys both work, since drafting is not carrier-backed. Logo, hero
+and call-to-action media must be public `https://` URLs: assets cannot be
+uploaded over the API, only from the dashboard. Nested hashes (address,
+contact, basics, campaign, testing) accept snake_case or camelCase keys.
+Every write accepts `idempotency_key:`; `POST`s get an auto-generated key
+as usual, while `PATCH` and `PUT` send one only when you pass it.
+
+```ruby
+# Where is the registration at?
+reg = client.rcs.registration.get
+puts reg.stage  # "draft" until something is submitted
+
+# Seed the brand from details Sendly already holds (your 10DLC brand or
+# toll-free verification), then fill in the rest
+dossier = client.rcs.dossier.get
+brand = client.rcs.brands.create(**dossier.brand)  # dossier.source: "tendlc", "verification" or "none"
+client.rcs.brands.update(brand.id,
+  display_name: "Acme Coffee",
+  legal_entity_type: "LIMITED_LIABILITY_COMPANY",
+  contact: { first_name: "Sam", last_name: "Lee", email: "sam@acme.example",
+             phone_number: "+15551234567" }
+)
+
+# Draft the agent. Media must be public https URLs.
+agent = client.rcs.agents.create(
+  brand_id: brand.id,
+  display_name: "Acme Coffee",
+  use_case: "MULTI_USE",
+  basics: {
+    description: "Order updates and offers from Acme Coffee",
+    logo_url: "https://acme.example/rcs/logo.png",
+    hero_url: "https://acme.example/rcs/hero.png",
+    brand_color: "#5B3A29",
+    privacy_policy_url: "https://acme.example/privacy",
+    terms_and_conditions_url: "https://acme.example/terms",
+    phone_number: { number: "+15551234567", label: "Support" }
+  }
+)
+
+# Submit for Sendly's review. Pass your own key if you may retry: a replay
+# returns the original response without submitting again.
+agent = client.rcs.agents.submit(agent.id, idempotency_key: "rcs-submit-#{agent.id}")
+puts agent.review_status  # "awaiting_review"
+
+# Later: poll, and act on a review note
+agent = client.rcs.agents.get(agent.id)
+if agent.changes_requested?
+  puts agent.review_note
+  client.rcs.agents.update(agent.id, basics: { hero_url: "https://acme.example/rcs/hero-v2.png" })
+end
+
+# Once the agent is in testing, invite devices, describe the campaign,
+# then request launch
+client.rcs.agents.set_test_devices(agent.id, devices: [
+  { phone_number: "+15557654321", label: "Sam's Pixel" }
+])
+client.rcs.agents.update(agent.id,
+  campaign: {
+    company_overview: "Specialty coffee roaster with three cafes in Austin",
+    agent_overview: "Order updates, pickup alerts and support replies",
+    interactions: [{ interaction_type: "TRANSACTIONAL_UPDATES",
+                     description: "Order and pickup status" }],
+    message_examples: ["Your order #4821 has shipped!",
+                       "Your latte is ready for pickup at 5th St",
+                       "Reply HELP for support or STOP to opt out"],
+    consent_settings: {
+      opt_in_methods: [{ method_type: "WEBSITE", description: "Checkbox at checkout" }],
+      call_to_action: "Get order updates by RCS",
+      call_to_action_url: "https://acme.example/updates",
+      double_opt_in: false,
+      help_response: "Acme Coffee: reply STOP to opt out, or email help@acme.example",
+      opt_out_response: "You're opted out of Acme Coffee updates."
+    }
+  }
+)
+client.rcs.agents.request_launch(agent.id, test_url: "https://acme.example/rcs-test")
+```
+
+Registration errors map onto the usual classes: `Sendly::NotFoundError`
+for `rcs_not_enabled` and `rcs_not_found`; `Sendly::ValidationError` for
+`rcs_us_only` and `rcs_invalid_content`, whose `field_errors` is the API's
+list of `{ "path", "message" }` hashes; and `Sendly::APIError` with
+`status_code` 409 for `rcs_field_locked`, `rcs_brand_not_verified` and
+`rcs_launch_not_ready`, or 403 for a key missing the scope.
+
+### Sending
+
+```ruby
+# Discover your RCS agents ("testing" reaches invited test devices only;
+# "approved" reaches everyone). Pass agent_id on sends and capability
+# checks when your workspace has more than one agent.
+client.rcs.agents.list[:agents].each do |a|
+  puts "#{a.name} — #{a.status}#{a.sendable? ? ' (sendable)' : ''}"
+end
+
+# Pre-flight: can this recipient receive RCS?
+capability = client.rcs.capability(to: "+15551234567")
+puts capability.capable? ? "RCS" : "would fall back to SMS"
+
+# Text with suggested replies and actions. Nested suggestion and card
+# hashes are passed through verbatim, so they use the camelCase keys the
+# API expects.
+message = client.messages.send(
+  channel: "rcs",
+  to: "+15551234567",
+  text: "Your order has shipped! Want live updates?",
+  suggestions: [
+    { reply: { text: "Yes, notify me", postbackData: "notify_yes" } },
+    { action: { text: "Track order", postbackData: "track",
+                url: "https://acme.example/orders/4821" } }
+  ]
+)
+
+# The response discloses which channel delivered
+puts message.channel # "rcs", or "sms" when it fell back
+if message.fell_back?
+  # Delivered as plain SMS (billed as SMS). Suggestions have no SMS form
+  # and were dropped — message.rcs.suggestions_dropped is true.
+else
+  puts message.rcs.kind       # "text" or "card"
+  puts message.rcs.agent_name # the brand name recipients see
+end
+
+# Rich card (RCS-capable recipients only — cards have no SMS form)
+client.messages.send(
+  channel: "rcs",
+  to: "+15551234567",
+  card: {
+    title: "Spring collection",
+    description: "New arrivals are in - take a look.",
+    mediaUrl: "https://example.com/spring.jpg", # public JPEG, PNG, or GIF
+    orientation: "vertical",                    # or "horizontal"
+    suggestions: [
+      { action: { text: "Shop now", postbackData: "shop",
+                  url: "https://acme.example/spring" } }
+    ]
+  }
+)
+
+# Opt out of the SMS fallback — the send raises Sendly::ValidationError
+# (HTTP 422 rcs_not_supported_for_recipient) when the recipient can't
+# receive RCS
+client.messages.send(
+  channel: "rcs",
+  to: "+15551234567",
+  text: "RCS or nothing",
+  fallback_to_sms: false
+)
+```
+
 ## Error Handling
 
 ```ruby
@@ -893,7 +1186,8 @@ Full enterprise docs: [sendly.live/docs/enterprise](https://sendly.live/docs/ent
 ## Requirements
 
 - Ruby 3.0+
-- Faraday 2.0+
+
+The client is built on Ruby's standard-library `net/http` and does not use Faraday at runtime. The gemspec still declares `faraday` and `faraday-retry` so this release does not drop a runtime dependency that callers may be resolving transitively. Both are unused and are slated for removal in the next major version.
 
 ## License
 

data/lib/sendly/account_resource.rb

@@ -39,15 +39,15 @@ module Sendly
       params[:offset] = offset if offset
 
       response = @client.get("/credits/transactions", params)
-      response.map { |data| CreditTransaction.new(data) }
+      (response["transactions"] || []).map { |data| CreditTransaction.new(data) }
     end
 
     # List API keys for the account
     #
     # @return [Array<Sendly::ApiKey>]
     def api_keys
-      response = @client.get("/keys")
-      response.map { |data| ApiKey.new(data) }
+      response = @client.get("/account/keys")
+      (response["keys"] || []).map { |data| ApiKey.new(data) }
     end
 
     # Get a specific API key by ID
@@ -55,7 +55,7 @@ module Sendly
     # @param key_id [String] API key ID
     # @return [Sendly::ApiKey]
     def api_key(key_id)
-      response = @client.get("/keys/#{key_id}")
+      response = @client.get("/account/keys/#{key_id}")
       ApiKey.new(response)
     end
 
@@ -64,7 +64,7 @@ module Sendly
     # @param key_id [String] API key ID
     # @return [Hash] Usage statistics
     def api_key_usage(key_id)
-      @client.get("/keys/#{key_id}/usage")
+      @client.get("/account/keys/#{key_id}/usage")
     end
 
     # Create a new API key
@@ -88,11 +88,15 @@ module Sendly
     # Revoke an API key
     #
     # @param key_id [String] API key ID to revoke
-    # @return [void]
-    def revoke_api_key(key_id)
+    # @param reason [String, nil] Optional reason recorded on the key's audit trail
+    # @return [Hash] +{ "id" => ..., "name" => ..., "revoked" => true, "revokedAt" => ... }+
+    def revoke_api_key(key_id, reason: nil)
       raise ArgumentError, "API key ID is required" if key_id.nil? || key_id.empty?
 
-      @client.delete("/account/keys/#{key_id}")
+      body = {}
+      body[:reason] = reason if reason
+
+      @client.patch("/account/keys/#{key_id}/revoke", body)
     end
 
     # Rotate an API key.

data/lib/sendly/business_upgrade_resource.rb

@@ -383,6 +383,8 @@ module Sendly
       req["User-Agent"] = "sendly-ruby/#{Sendly::VERSION}"
       req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
       req["X-Organization-Id"] = @client.organization_id if @client.organization_id
+      # Single-use auto key (this path has no retry loop).
+      req["Idempotency-Key"] = @client.generate_idempotency_key
       req.body = body_parts.join
 
       begin