sendly 3.38.0 → 3.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76b3722f8971a04363ce5a5ea47d61eba59db05698652f21cd5ab347c24c74c1
-  data.tar.gz: 478881a38dac65c6f9696d0de53114fadc10651152304542519616794ed64bfe
+  metadata.gz: 91dd6ee6db6b506dea8d70b085fc6a069330e9ddca10b1de8e097b3db07889cd
+  data.tar.gz: 3114725bc7d45361b625ba7c7cfc88b6a6eee0672154b3b3daf46237cb475b53
 SHA512:
-  metadata.gz: db802e6f2ac77bd0978de8a043b8a34488168e820e8b2e6ad3aca7033f43377b1524ccdee742077471486013d6f6e8607465b1fbaf68038dfb8d37d3f119915c
-  data.tar.gz: 33103fdeb0adf5816c3ffcdc23c4107eb52cc814ed904ae2b9d64f314d8fb88bbf2f0e837c0d4bd66781903710c7ffab770da166e5372eebe79d8522c3ace7d8
+  metadata.gz: a8728f247769f3bbd8ad1713a86814eb419c944d64f06797ed94f858b543185d4c1baced35ba9aa910871b04a15e0348aece222a4e88de691e717df9b5542c01
+  data.tar.gz: ba2ad16077e383a0e37b7dee97ebada69cd3c1e815f6775afb677ab331a031da2f643666da3e95cc2b90e0dbff3478a6d35bc9a0364efd9b865c1ff5302f25fd

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 # sendly (Ruby)
 
+## Unreleased
+
+### Breaking Changes
+
+- **A webhook that is not a message is no longer presented as one.** `parse_event` built a `Sendly::WebhookMessageData` out of every `data.object`, whatever the event was. For an `rcs_*`, `whatsapp_*`, `call.*`, `brand.*`, `campaign.*`, `assignment.*`, `number.*`, `port*`, `contact*`, `conversation.*` or `draft.*` payload that dropped every field the event actually carried — `agent_id`, `stage`, `port_request_id`, `duration_secs` and the rest were unreachable — and filled the gaps with message fields that were never sent. `event.data` is now a `Sendly::WebhookObject`, a hash-like view of `data.object`: read a key with `[]` (String or Symbol), a reader method of the same name, or `to_h`. `event.message` is the message view and is `nil` for all of the above; `message.*` events are unchanged, and `event.data` is still the `WebhookMessageData` there.
+
+  ```ruby
+  # before — "" for every RCS event, and the agent was unreachable
+  event.data.from
+  # after
+  event.data[:agent_id]   # => "bb22cc33-..."
+  event.message           # => nil
+  ```
+
+- **Absent fields are `nil` instead of a plausible-looking default.** `WebhookMessageData` defaulted `segments` to `1`, `credits_used` to `0`, `direction` to `"outbound"`, `from` to `""` and `id` to `""`, none of which a handler could tell from a real value. They are now `nil` when the payload did not carry them, and `data.key?(:segments)` says which case you are in. `WebhookVerificationData` loses the same kind of defaults (`delivery_status` `"queued"`, `attempts` `0`, `max_attempts` `3`), though nothing could reach that class before this release.
+
+- **JSON `null` survives as `nil`.** `from` and `to` on a `call.*` event are `null` for every in-app call; `from` used to arrive as `""`. Code branching on `from.empty?` should branch on `nil` now.
+
+- **`event.data.to_h` returns `data.object` as it arrived.** It used to return a compacted subset of the typed message fields, which dropped `text`, `metadata`, `media_urls`, `message_format` and `organization_id`, renamed `message_id` to `id`, and emitted the invented `segments`/`credits_used` defaults. `event.to_h[:data]` is the same hash. For a current-shape payload the familiar keys are all still there.
+
+- **`id` is no longer filled from an unrelated `id` key.** `contact.auto_flagged` carries the contact under `id` and the message that failed under `message_id`, so `event.data.message_id` returned the *contact* id — a handler that marked that message failed acted on the wrong row. Contact events have no message view at all now; read the message with `event.data[:message_id]`.
+
+### Minor Changes
+
+- **`Sendly::WebhookEvent#raw_object`** carries `data.object` exactly as it arrived, for every event type, and **`#object_as(klass)`** reads it as a type of your choosing (`event.object_as(AgentLive)`). `#object` is an alias for `raw_object`.
+
+- **`Sendly::WebhookVerificationData` is reachable.** Nothing ever constructed it, and it read String keys while `parse_event` symbolizes names, so it could not have worked if anything had. `verification.*` events now build one, as `event.verification` and `event.data`, and every reader takes String or Symbol keys.
+
+- **`Sendly::WebhookEvent` gains `#message?` and `#verification?`** for the two cases that have a typed view.
+
+- **`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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sendly (3.38.0)
+    sendly (3.40.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 

data/README.md

@@ -280,8 +280,36 @@ 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
 
+### Managing endpoints
+
 ```ruby
 # Create a webhook endpoint
 webhook = client.webhooks.create(
@@ -314,6 +342,67 @@ rotation = client.webhooks.rotate_secret("whk_xxx")
 client.webhooks.delete("whk_xxx")
 ```
 
+### Receiving events
+
+`Sendly::Webhooks.parse_event` verifies the signature and returns a
+`Sendly::WebhookEvent`. Pass the raw request body — not a re-serialized hash,
+which would no longer match the signature.
+
+```ruby
+event = Sendly::Webhooks.parse_event(
+  request.raw_post,
+  request.headers["X-Sendly-Signature"],
+  ENV.fetch("SENDLY_WEBHOOK_SECRET"),
+  timestamp: request.headers["X-Sendly-Timestamp"]
+)
+```
+
+`event.raw_object` is `data.object` exactly as it arrived, for every event
+type. `event.data` is a hash-like view of the same object: read a key with
+`[]` (String or Symbol), a reader method of the same name, or `to_h`.
+
+```ruby
+case event.type
+when Sendly::Webhooks::EVENT_MESSAGE_DELIVERED
+  # message.* events also get a typed message view
+  puts "#{event.message.id} -> #{event.message.to}"
+when Sendly::Webhooks::EVENT_RCS_AGENT_LIVE
+  puts event.data[:agent_id]
+  puts event.data.stage
+when Sendly::Webhooks::EVENT_CALL_COMPLETED
+  puts event.data[:duration_secs]
+end
+
+# Or read data.object as a type of your own. A Struct or Data class is filled
+# from the members it declares and ignores the rest of the payload, so a field
+# added to the event later cannot break the call.
+AgentLive = Struct.new(:agent_id, :name, :stage)
+agent = event.object_as(AgentLive)
+```
+
+Two things the SDK will not do, because both make a handler act on data that
+was never sent:
+
+- **Nothing is invented.** A field the payload did not carry is `nil`, and
+  `event.data.key?(:segments)` is `false`. `segments`, `credits_used`,
+  `direction`, `to` and `from` are no longer defaulted to `1`, `0`,
+  `"outbound"` and `""`.
+- **`nil` stays `nil`.** An in-app `call.*` event carries `from` and `to` as
+  JSON `null`; they come back as `nil`, not `""`.
+
+`event.message` is the message view and is `nil` for every event that is not a
+message — `rcs_*`, `whatsapp_*`, `call.*`, `brand.*`, `campaign.*`,
+`assignment.*`, `number.*`, `port*`, `contact*`, `conversation.*` and
+`draft.*`, whose payloads are not message-shaped. `verification.*` events get
+`event.verification`, a `Sendly::WebhookVerificationData`. `event.data` is the
+typed view where one exists and a plain `Sendly::WebhookObject` otherwise, so
+reading `data.object` works the same way for all of them, including an event
+type this SDK predates.
+
+Note that `contact.auto_flagged` carries the contact under `id` and the message
+that failed under `message_id`; read the message with
+`event.data[:message_id]`.
+
 ## Account & Credits
 
 ```ruby
@@ -846,9 +935,108 @@ 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). RCS sends and
-capability checks require a live API key. RCS agents are registered by
-Sendly for your brand — contact support to set one up.
+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;

data/lib/sendly/client.rb

@@ -222,20 +222,28 @@ module Sendly
 
     # Make a PATCH request
     #
+    # No Idempotency-Key is generated for a PATCH; pass +idempotency_key+
+    # to send one (1-255 printable ASCII characters).
+    #
     # @param path [String] API path
     # @param body [Hash] Request body
+    # @param idempotency_key [String, nil] Caller-supplied idempotency key (optional)
     # @return [Hash] Response body
-    def patch(path, body = {})
-      request(:patch, path, body: body)
+    def patch(path, body = {}, idempotency_key: nil)
+      request(:patch, path, body: body, idempotency_key: idempotency_key)
     end
 
     # Make a PUT request
     #
+    # No Idempotency-Key is generated for a PUT; pass +idempotency_key+
+    # to send one (1-255 printable ASCII characters).
+    #
     # @param path [String] API path
     # @param body [Hash] Request body
+    # @param idempotency_key [String, nil] Caller-supplied idempotency key (optional)
     # @return [Hash] Response body
-    def put(path, body = {})
-      request(:put, path, body: body)
+    def put(path, body = {}, idempotency_key: nil)
+      request(:put, path, body: body, idempotency_key: idempotency_key)
     end
 
     # Make a DELETE request

data/lib/sendly/errors.rb

@@ -47,7 +47,9 @@ module Sendly
 
   # Raised when the request contains invalid parameters
   class ValidationError < Error
-    # @return [Hash, nil] Field-specific validation errors
+    # @return [Array<Hash>, Hash, nil] Field-specific validation errors. For
+    #   API responses this is the +errors+ list from the body when present,
+    #   e.g. +[{ "path" => "brand.ein", "message" => "Enter a 9-digit EIN" }]+
     attr_reader :field_errors
 
     def initialize(message = "Validation failed", field_errors: nil, details: nil)
@@ -101,7 +103,7 @@ module Sendly
 
       case status
       when 400, 422
-        ValidationError.new(message, details: details)
+        ValidationError.new(message, details: details, field_errors: body["errors"])
       when 401
         AuthenticationError.new(message)
       when 402