sendly 3.37.1 → 3.39.0

data/lib/sendly/client.rb

@@ -178,6 +178,20 @@ module Sendly
       @links ||= LinksResource.new(self)
     end
 
+    # Access the WhatsApp resource
+    #
+    # @return [Sendly::WhatsAppResource]
+    def whatsapp
+      @whatsapp ||= WhatsAppResource.new(self)
+    end
+
+    # Access the RCS resource
+    #
+    # @return [Sendly::RcsResource]
+    def rcs
+      @rcs ||= RcsResource.new(self)
+    end
+
     # Make a GET request
     #
     # @param path [String] API path
@@ -189,29 +203,47 @@ module Sendly
 
     # Make a POST request
     #
+    # Every POST carries an Idempotency-Key header. By default the client
+    # generates one per logical request ("sendly-ruby-retry-<uuid>") so the
+    # server can dedupe the client's own retries; pass +idempotency_key+ to
+    # supply your own (1-255 printable ASCII characters) and extend that
+    # protection across process restarts, or +auto_idempotency_key: false+
+    # to skip auto-generation for endpoints that dedupe by other means.
+    #
     # @param path [String] API path
     # @param body [Hash] Request body
+    # @param idempotency_key [String, nil] Caller-supplied idempotency key (optional)
+    # @param auto_idempotency_key [Boolean] Auto-generate a key when none is supplied (default: true)
     # @return [Hash] Response body
-    def post(path, body = {})
-      request(:post, path, body: body)
+    def post(path, body = {}, idempotency_key: nil, auto_idempotency_key: true)
+      request(:post, path, body: body, idempotency_key: idempotency_key,
+                           auto_idempotency_key: auto_idempotency_key)
     end
 
     # 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
@@ -257,11 +289,15 @@ module Sendly
     # @param file [String, IO] File path or IO object
     # @param content_type [String] MIME type of the file
     # @param filename [String] Name for the uploaded file
+    # @param idempotency_key [String, nil] Caller-supplied idempotency key (optional)
     # @return [Hash] Response body
-    def post_multipart(path, file, content_type: "image/jpeg", filename: "upload.jpg")
+    def post_multipart(path, file, content_type: "image/jpeg", filename: "upload.jpg", idempotency_key: nil)
       uri = build_uri(path, {})
       http = build_http(uri)
 
+      explicit_key = normalize_idempotency_key(idempotency_key)
+      key = explicit_key || generate_idempotency_key
+
       boundary = "SendlyRuby#{SecureRandom.hex(16)}"
 
       file_data = file.is_a?(String) ? File.binread(file) : file.read
@@ -283,6 +319,7 @@ module Sendly
 
       attempt = 0
       begin
+        req["Idempotency-Key"] = key
         response = http.request(req)
         handle_response(response)
       rescue Net::OpenTimeout, Net::ReadTimeout
@@ -299,6 +336,10 @@ module Sendly
       rescue ServerError => e
         attempt += 1
         if attempt <= max_retries
+          # A 5xx response may be cached under the key server-side, so an
+          # auto-generated key is rotated to let the retry re-execute.
+          # Caller-supplied keys are never rotated.
+          key = generate_idempotency_key if explicit_key.nil?
           sleep(2 ** attempt)
           retry
         end
@@ -306,6 +347,13 @@ module Sendly
       end
     end
 
+    # Generate an idempotency key for a logical request. Reused across retry
+    # attempts so the server can recognize a retry of a POST that already
+    # reached it and return the original result instead of executing again.
+    def generate_idempotency_key
+      "sendly-ruby-retry-#{SecureRandom.uuid}"
+    end
+
     private
 
     def validate_api_key!
@@ -316,13 +364,19 @@ module Sendly
       end
     end
 
-    def request(method, path, params: {}, body: nil, unversioned: false)
+    def request(method, path, params: {}, body: nil, unversioned: false, idempotency_key: nil,
+                auto_idempotency_key: true)
       uri = build_uri(path, params, unversioned: unversioned)
       http = build_http(uri)
       req = build_request(method, uri, body)
 
+      explicit_key = normalize_idempotency_key(idempotency_key)
+      key = explicit_key
+      key = generate_idempotency_key if key.nil? && method == :post && auto_idempotency_key
+
       attempt = 0
       begin
+        req["Idempotency-Key"] = key if key
         response = http.request(req)
         handle_response(response)
       rescue Net::OpenTimeout, Net::ReadTimeout
@@ -339,6 +393,10 @@ module Sendly
       rescue ServerError => e
         attempt += 1
         if attempt <= max_retries
+          # A 5xx response may be cached under the key server-side, so an
+          # auto-generated key is rotated to let the retry re-execute.
+          # Caller-supplied keys are never rotated.
+          key = generate_idempotency_key if key && explicit_key.nil?
           sleep(2 ** attempt) # Exponential backoff
           retry
         end
@@ -346,6 +404,23 @@ module Sendly
       end
     end
 
+    # Validate and normalize a caller-supplied idempotency key. Empty and
+    # whitespace-only values are treated as absent (auto-generation still
+    # applies); invalid values fail fast instead of surfacing later as an
+    # API error.
+    def normalize_idempotency_key(key)
+      return nil if key.nil?
+
+      trimmed = key.to_s.strip
+      return nil if trimmed.empty?
+
+      if trimmed.length > 255 || !trimmed.match?(/\A[\x20-\x7E]+\z/)
+        raise ValidationError, "Idempotency key must be 1-255 printable ASCII characters"
+      end
+
+      trimmed
+    end
+
     def build_uri(path, params, unversioned: false)
       base = unversioned ? api_origin : base_url
       url = "#{base}#{path}"

data/lib/sendly/enterprise.rb

@@ -505,6 +505,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
 
       response = http.request(req)

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

data/lib/sendly/messages.rb

@@ -10,14 +10,66 @@ module Sendly
       @client = client
     end
 
-    # Send an SMS message
+    # Send an SMS, WhatsApp, or RCS message
+    #
+    # Pass +channel: "whatsapp"+ to send on WhatsApp. WhatsApp sends require
+    # a live API key and a +from+ number with an active WhatsApp connection
+    # (see +client.whatsapp.signup+). Provide exactly one of +text+
+    # (free-form, max 4096 bytes), +media_urls+ (a single attachment;
+    # optional +text+ becomes its caption, max 1024 bytes), or +template+
+    # (an approved template). Free-form text and media only deliver inside
+    # an open 24-hour customer-service window — outside it the API responds
+    # 422 +whatsapp_window_closed+; send a template instead (check with
+    # +client.whatsapp.window+).
+    #
+    # Pass +channel: "rcs"+ to send on RCS. RCS sends require a live API key
+    # and a sendable RCS agent on your workspace (see +client.rcs.agents+).
+    # Provide exactly one of +text+ (free-form, optionally with
+    # +suggestions+ — suggested replies and URL actions) or +card+ (a rich
+    # card). +agent_id+ picks the sending agent when your workspace has more
+    # than one. Recipients that can't receive RCS get +text+ delivered as
+    # plain SMS (billed as SMS) unless +fallback_to_sms+ is false — the
+    # returned {Sendly::RcsMessage} discloses which channel delivered.
     #
     # @param to [String] Recipient phone number in E.164 format
-    # @param text [String] Message content (max 1600 characters)
-    # @param from [String] Sender ID or phone number (optional)
-    # @param message_type [String] Message type: "marketing" (default) or "transactional"
+    # @param text [String] Message content (max 1600 characters for SMS);
+    #   for WhatsApp, optional free-form text or the media caption
+    # @param from [String] Sender ID or phone number (optional for SMS);
+    #   required for WhatsApp — must be a WhatsApp-connected number
+    # @param message_type [String] Message type: "marketing" (default) or "transactional" (SMS only)
     # @param metadata [Hash] Custom JSON metadata to attach to the message (max 4KB)
-    # @return [Sendly::Message] The sent message
+    # @param media_urls [Array<String>] Media URLs to attach (WhatsApp accepts exactly one)
+    # @param channel [String] Message channel: omit (or "sms") for SMS,
+    #   "whatsapp" for WhatsApp, "rcs" for RCS
+    # @param template [Hash] WhatsApp only: approved template to send, with
+    #   :name, :language, and optional :variables ({ "1" => "Acme" }) and
+    #   :buttons ([{ index: 0, variables: { "1" => "4821" } }]). Works
+    #   regardless of the 24-hour window.
+    # @param agent_id [String] RCS only: the agent to send from. Optional
+    #   when your workspace has exactly one sendable agent; required (the
+    #   API responds 400 +rcs_agent_ambiguous+) when it has more.
+    # @param card [Hash] RCS only: a rich card, with :title, :description,
+    #   and optional :mediaUrl (a public JPEG, PNG, or GIF), :orientation
+    #   ("vertical" or "horizontal"), and :suggestions. Passed through
+    #   verbatim, so use the camelCase keys shown. Cards have no SMS form
+    #   and only deliver to RCS-capable recipients.
+    # @param suggestions [Array<Hash>] RCS only, alongside +text+: suggested
+    #   replies and actions, each either
+    #   { reply: { text: ..., postbackData: ... } } or
+    #   { action: { text: ..., postbackData: ..., url: ... } }. Passed
+    #   through verbatim, so use the camelCase keys shown. Suggestions have
+    #   no SMS form and are dropped on a fallback.
+    # @param fallback_to_sms [Boolean] RCS only: deliver +text+ as plain SMS
+    #   when the recipient can't receive RCS (default true). Pass false to
+    #   fail with 422 +rcs_not_supported_for_recipient+ instead.
+    # @param idempotency_key [String] Idempotency key for this operation
+    #   (1-255 printable ASCII characters). The SDK already generates a key
+    #   per logical request automatically, so the server can dedupe the
+    #   SDK's own retries. Supply your own key when you need idempotency
+    #   across process restarts or your own retry loops — repeating a
+    #   request with the same key within 24 hours returns the original
+    #   response instead of executing again.
+    # @return [Sendly::Message, Sendly::WhatsAppMessage, Sendly::RcsMessage] The sent message
     #
     # @raise [Sendly::ValidationError] If parameters are invalid
     # @raise [Sendly::InsufficientCreditsError] If account has no credits
@@ -37,8 +89,93 @@ module Sendly
     #     text: "Your verification code is 123456",
     #     message_type: "transactional"
     #   )
-    def send(to:, text:, from: nil, message_type: nil, metadata: nil, media_urls: nil)
+    #
+    # @example WhatsApp free-form reply inside an open 24h window
+    #   message = client.messages.send(
+    #     channel: "whatsapp",
+    #     to: "+15551234567",
+    #     from: "+15559876543",
+    #     text: "Your table is ready!"
+    #   )
+    #
+    # @example WhatsApp template send — works regardless of the window
+    #   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"
+    #   puts message.credits_used    # priced by country + category
+    #
+    # @example RCS text with suggested replies and actions
+    #   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" } }
+    #     ]
+    #   )
+    #   puts message.channel      # "rcs", or "sms" when it fell back
+    #   puts message.fell_back?   # true when delivered as plain SMS
+    #
+    # @example RCS rich card (RCS-capable recipients only)
+    #   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",
+    #       orientation: "vertical"
+    #     }
+    #   )
+    def send(to:, text: nil, from: nil, message_type: nil, metadata: nil, media_urls: nil,
+             channel: nil, template: nil, agent_id: nil, card: nil, suggestions: nil,
+             fallback_to_sms: nil, idempotency_key: nil)
       validate_phone!(to)
+
+      if channel.to_s == "rcs"
+        has_text = !(text.nil? || text.to_s.empty?)
+        has_card = !card.nil?
+        raise ValidationError, "Provide exactly one of 'text' or 'card'" if has_text == has_card
+
+        body = { channel: "rcs", to: to }
+        body[:agentId] = agent_id if agent_id
+        body[:text] = text if has_text
+        body[:card] = card if has_card
+        body[:suggestions] = suggestions if suggestions
+        body[:fallbackToSms] = fallback_to_sms unless fallback_to_sms.nil?
+        body[:metadata] = metadata if metadata
+
+        response = client.post("/messages", body, idempotency_key: idempotency_key)
+        return RcsMessage.new(response)
+      end
+
+      if channel.to_s == "whatsapp"
+        validate_phone!(from)
+        has_media = media_urls.is_a?(Array) && !media_urls.empty?
+        if (text.nil? || text.empty?) && !has_media && template.nil?
+          raise ValidationError, "Provide 'text', 'media_urls', or 'template'"
+        end
+
+        body = { channel: "whatsapp", to: to, from: from }
+        body[:text] = text unless text.nil?
+        body[:mediaUrls] = media_urls if has_media
+        body[:template] = template if template
+        body[:metadata] = metadata if metadata
+
+        response = client.post("/messages", body, idempotency_key: idempotency_key)
+        return WhatsAppMessage.new(response)
+      end
+
       validate_text!(text)
 
       body = { to: to, text: text }
@@ -47,7 +184,7 @@ module Sendly
       body[:metadata] = metadata if metadata
       body[:mediaUrls] = media_urls if media_urls
 
-      response = client.post("/messages", body)
+      response = client.post("/messages", body, idempotency_key: idempotency_key)
       # API returns message directly at top level
       Message.new(response)
     end
@@ -65,6 +202,8 @@ module Sendly
     # @param from [String] Sender ID or phone number (optional)
     # @param media_urls [Array<String>] Media URLs to attach (required unless text is provided)
     # @param message_type [String] Message type: "transactional" (default) or "marketing"
+    # @param idempotency_key [String] Idempotency key for this operation
+    #   (1-255 printable ASCII characters, optional)
     # @return [Sendly::GroupMessage] The sent group message, including a group_message_id
     #
     # @raise [Sendly::ValidationError] If fewer than 2 / more than 8 recipients, or no body
@@ -77,7 +216,7 @@ module Sendly
     #   )
     #   puts group.id
     #   puts group.group_message_id
-    def send_group(to:, text: nil, from: nil, media_urls: nil, message_type: nil)
+    def send_group(to:, text: nil, from: nil, media_urls: nil, message_type: nil, idempotency_key: nil)
       unless to.is_a?(Array) && to.length >= 2
         raise ValidationError, "Group messaging requires at least 2 recipients in 'to'"
       end
@@ -94,7 +233,7 @@ module Sendly
       body[:mediaUrls] = media_urls if has_media
       body[:messageType] = message_type if message_type
 
-      response = client.post("/messages/group", body)
+      response = client.post("/messages/group", body, idempotency_key: idempotency_key)
       GroupMessage.new(response)
     end
 
@@ -218,6 +357,8 @@ module Sendly
     # @param from [String] Sender ID or phone number (optional)
     # @param message_type [String] Message type: "marketing" (default) or "transactional"
     # @param metadata [Hash] Custom JSON metadata to attach to the message (max 4KB)
+    # @param idempotency_key [String] Idempotency key for this operation
+    #   (1-255 printable ASCII characters, optional)
     # @return [Hash] The scheduled message
     #
     # @raise [Sendly::ValidationError] If parameters are invalid
@@ -229,7 +370,7 @@ module Sendly
     #     scheduled_at: "2025-01-20T10:00:00Z"
     #   )
     #   puts scheduled["id"]
-    def schedule(to:, text:, scheduled_at:, from: nil, message_type: nil, metadata: nil)
+    def schedule(to:, text:, scheduled_at:, from: nil, message_type: nil, metadata: nil, idempotency_key: nil)
       validate_phone!(to)
       validate_text!(text)
       raise ValidationError, "scheduled_at is required" if scheduled_at.nil? || scheduled_at.empty?
@@ -239,7 +380,7 @@ module Sendly
       body[:messageType] = message_type if message_type
       body[:metadata] = metadata if metadata
 
-      client.post("/messages/schedule", body)
+      client.post("/messages/schedule", body, idempotency_key: idempotency_key)
     end
 
     # List scheduled messages
@@ -303,6 +444,8 @@ module Sendly
     # @param from [String] Sender ID or phone number (optional, applies to all)
     # @param message_type [String] Message type: "marketing" (default) or "transactional"
     # @param metadata [Hash] Shared metadata for all messages (max 4KB). Each message can also have its own metadata hash which takes priority.
+    # @param idempotency_key [String] Idempotency key for this operation
+    #   (1-255 printable ASCII characters, optional)
     # @return [Hash] Batch response with batch_id and status
     #
     # @raise [Sendly::ValidationError] If parameters are invalid
@@ -316,7 +459,7 @@ module Sendly
     #     ]
     #   )
     #   puts "Batch #{result['batchId']}: #{result['queued']} queued"
-    def send_batch(messages:, from: nil, message_type: nil, metadata: nil)
+    def send_batch(messages:, from: nil, message_type: nil, metadata: nil, idempotency_key: nil)
       raise ValidationError, "Messages array is required" if messages.nil? || messages.empty?
 
       messages.each_with_index do |msg, i|
@@ -334,7 +477,11 @@ module Sendly
       body[:messageType] = message_type if message_type
       body[:metadata] = metadata if metadata
 
-      client.post("/messages/batch", body)
+      # The batch endpoint dedupes header-less retries server-side by hashing
+      # the request content; an auto-generated key would bypass that net for
+      # identical cross-process re-runs, so only caller-supplied keys are sent.
+      client.post("/messages/batch", body, idempotency_key: idempotency_key,
+                                           auto_idempotency_key: false)
     end
 
     # Get batch status by ID