sendly 4.1.0 → 4.3.0

data/lib/sendly/errors.rb

@@ -12,12 +12,30 @@ module Sendly
     # @return [Integer, nil] HTTP status code
     attr_reader :status_code
 
+    # @return [Hash, nil] The parsed JSON body of the API's error response,
+    #   or +nil+ for errors raised before a request was sent. The API's own
+    #   error code is under +"error"+, and some refusals carry more than a
+    #   message: a 409 +agent_in_use+ lists the numbers the agent still
+    #   answers under +"numbers"+, and a 422 +invalid_address+ carries a
+    #   corrected address (or +nil+) under +"suggested"+.
+    attr_reader :response_body
+
     def initialize(message = nil, code: nil, details: nil, status_code: nil)
       @code = code
       @details = details
       @status_code = status_code
       super(message)
     end
+
+    # Attach the parsed body of the API response this error came from.
+    #
+    # @api private
+    # @param body [Hash, nil]
+    # @return [self]
+    def with_response_body(body)
+      @response_body = body
+      self
+    end
   end
 
   # Raised when the API key is invalid or missing
@@ -96,28 +114,38 @@ module Sendly
 
   # Convert API response to appropriate error
   class ErrorFactory
-    def self.from_response(status, body)
+    def self.from_response(status, body, retry_after_header: nil)
       message = body["message"] || body["error"] || "Unknown error"
       code = body["code"]
       details = body["details"]
 
-      case status
-      when 400, 422
-        ValidationError.new(message, details: details, field_errors: body["errors"])
-      when 401
-        AuthenticationError.new(message)
-      when 402
-        InsufficientCreditsError.new(message)
-      when 404
-        NotFoundError.new(message)
-      when 429
-        retry_after = body["retry_after"] || body["retryAfter"]
-        RateLimitError.new(message, retry_after: retry_after)
-      when 500..599
-        ServerError.new(message, status_code: status)
-      else
-        APIError.new(message, status_code: status, code: code, details: details)
-      end
+      error = case status
+              when 400, 422
+                ValidationError.new(message, details: details, field_errors: body["errors"])
+              when 401
+                AuthenticationError.new(message)
+              when 402
+                InsufficientCreditsError.new(message)
+              when 404
+                NotFoundError.new(message)
+              when 429
+                retry_after = parse_retry_after(retry_after_header) || body["retry_after"] || body["retryAfter"]
+                RateLimitError.new(message, retry_after: retry_after)
+              when 500..599
+                ServerError.new(message, status_code: status)
+              else
+                APIError.new(message, status_code: status, code: code, details: details)
+              end
+      error.with_response_body(body)
+    end
+
+    def self.parse_retry_after(value)
+      text = value.to_s.strip
+      return text.to_i if text.match?(/\A\d+\z/)
+      return text.to_f if text.match?(/\A\d+\.\d+\z/)
+
+      nil
     end
+    private_class_method :parse_retry_after
   end
 end

data/lib/sendly/messages.rb

@@ -13,8 +13,11 @@ module Sendly
     # 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+
+    # the +sms:send+ scope (not +whatsapp:write+), a live API key and a
+    # +from+ number with an active WhatsApp connection (see
+    # +client.whatsapp.signup+). WhatsApp is enabled per person (the user who
+    # owns the API key, not the workspace); while it is off the API responds
+    # 403 +whatsapp_not_enabled+. 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
@@ -71,7 +74,22 @@ module Sendly
     #   response instead of executing again.
     # @return [Sendly::Message, Sendly::WhatsAppMessage, Sendly::RcsMessage] The sent message
     #
-    # @raise [Sendly::ValidationError] If parameters are invalid
+    # @raise [Sendly::ValidationError] If parameters are invalid, or on
+    #   WhatsApp the 422 +whatsapp_send_failed+ when WhatsApp refused the
+    #   message (final, not retried, not charged; cached under the
+    #   idempotency key and replayed for 24 hours)
+    # @raise [Sendly::ServerError] On WhatsApp, the 502 +whatsapp_send_failed+:
+    #   the message provably never reached the carrier, so it was not sent
+    #   and is safe to send again. It isn't charged and is never cached, so
+    #   the client retries it like any 5xx first under the same idempotency
+    #   key. No send returns 503 +whatsapp_unavailable+.
+    # @raise [Sendly::APIError] On WhatsApp, the 409
+    #   +whatsapp_send_unconfirmed+ (+status_code+ 409): the outcome is
+    #   unknown. The message was marked failed and refunded but may still be
+    #   delivered, so check before sending it again (it could arrive twice).
+    #   It is not retried automatically, and it is cached under the
+    #   idempotency key, so repeating the request with the same key returns
+    #   this answer again.
     # @raise [Sendly::InsufficientCreditsError] If account has no credits
     # @raise [Sendly::RateLimitError] If rate limit is exceeded
     #
@@ -327,7 +345,7 @@ module Sendly
     #
     # @param status [String] Filter by status
     # @param to [String] Filter by recipient
-    # @param batch_size [Integer] Number of messages per request
+    # @param batch_size [Integer] Number of messages per request (the API returns at most 100)
     # @yield [Message] Each message
     # @return [Enumerator] If no block given
     #
@@ -343,9 +361,9 @@ module Sendly
         page = list(limit: batch_size, offset: offset, status: status, to: to)
         page.each(&block)
 
-        break unless page.has_more
+        break if !page.has_more || page.count.zero?
 
-        offset += batch_size
+        offset += page.count
       end
     end
 
@@ -446,7 +464,9 @@ module Sendly
     # @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
+    # @return [Hash] Batch result: +batchId+, +status+ (processing, completed,
+    #   partial_failure or failed), +total+, +sent+, +failed+, +creditsUsed+,
+    #   +creditsRefunded+ and +messages+
     #
     # @raise [Sendly::ValidationError] If parameters are invalid
     # @raise [Sendly::InsufficientCreditsError] If account has insufficient credits
@@ -458,7 +478,7 @@ module Sendly
     #       { to: "+15559876543", text: "Hello Bob!" }
     #     ]
     #   )
-    #   puts "Batch #{result['batchId']}: #{result['queued']} queued"
+    #   puts "Batch #{result['batchId']}: #{result['total']} messages, #{result['status']}"
     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?
 
@@ -505,12 +525,12 @@ module Sendly
     #
     # @param limit [Integer] Maximum batches to return (default: 20, max: 100)
     # @param offset [Integer] Number of batches to skip
-    # @param status [String] Filter by status (processing, completed, failed)
+    # @param status [String] Filter by status (processing, completed, partial_failure, failed)
     # @return [Hash] Paginated list of batches
     #
     # @example
     #   batches = client.messages.list_batches(limit: 10)
-    #   batches["data"].each { |b| puts "#{b['batchId']}: #{b['status']}" }
+    #   batches["data"].each { |b| puts "#{b['id']}: #{b['status']}" }
     def list_batches(limit: 20, offset: 0, status: nil)
       params = {
         limit: [limit, 100].min,
@@ -537,7 +557,7 @@ module Sendly
     #       { to: "+15559876543", text: "Hello Bob!" }
     #     ]
     #   )
-    #   puts "Can send: #{preview['canSend']}"
+    #   puts "Sufficient credits: #{preview['hasSufficientCredits']}"
     #   puts "Credits needed: #{preview['creditsNeeded']}"
     def preview_batch(messages:, from: nil, message_type: nil)
       raise ValidationError, "Messages array is required" if messages.nil? || messages.empty?

data/lib/sendly/numbers_resource.rb

@@ -55,7 +55,8 @@ module Sendly
                 # ISO-8601 timestamp string, or nil when no release is scheduled.
                 :scheduled_release_at,
                 # true when the number can place and receive phone calls
-                # (switched on in the dashboard under Calls, then Settings).
+                # (switched on with {VoiceNumbersResource#update} or in the
+                # dashboard under Calls, then Settings).
                 :voice_enabled,
                 # One of {VOICE_MODES}: "none" when voice is off, "ring_dashboard"
                 # when inbound calls ring the team, "agent" when an AI agent answers.

data/lib/sendly/templates_resource.rb

@@ -222,10 +222,6 @@ module Sendly
     end
 
     # Copy an existing template into a new draft.
-    #
-    # @note Not available yet: the versioned API serves no clone route, so
-    #   this call fails with a 404. To copy a template today, read it with
-    #   {#get} and pass its {Template#text} to {#create}.
     def clone(id, name: nil)
       body = {}
       body[:name] = name if name

data/lib/sendly/types.rb

@@ -63,6 +63,12 @@ module Sendly
     # @return [Hash, nil] AI classification metadata for inbound messages
     attr_reader :ai_metadata
 
+    # @return [Array<String>] Media attached to the message; empty when there is none
+    attr_reader :media_urls
+
+    # @return [String] "sms", "mms", "rcs" or "whatsapp"; "sms" when the response does not say
+    attr_reader :message_format
+
     # Message status constants (sending removed - doesn't exist in database)
     STATUSES = %w[queued sent delivered failed bounced retrying].freeze
 
@@ -90,6 +96,8 @@ module Sendly
       @retry_count = data["retryCount"] || 0
       @metadata = data["metadata"]
       @ai_metadata = data["aiMetadata"]
+      @media_urls = data["mediaUrls"] || data["media_urls"] || []
+      @message_format = data["messageFormat"] || data["message_format"] || "sms"
     end
 
     # Check if message was delivered
@@ -133,7 +141,9 @@ module Sendly
         error_code: error_code,
         retry_count: retry_count,
         metadata: metadata,
-        ai_metadata: ai_metadata
+        ai_metadata: ai_metadata,
+        media_urls: media_urls,
+        message_format: message_format
       }.compact
     end
 
@@ -155,7 +165,7 @@ module Sendly
     # @return [Array<Message>] Messages in this page
     attr_reader :data
 
-    # @return [Integer] Total number of messages
+    # @return [Integer] Total number of messages that match the query, across all pages
     attr_reader :total
 
     # @return [Integer] Current limit
@@ -168,11 +178,16 @@ module Sendly
     attr_reader :has_more
 
     def initialize(response)
+      pagination = response["pagination"] || {}
       @data = (response["data"] || []).map { |m| Message.new(m) }
-      @total = response["count"] || @data.length
-      @limit = response["limit"] || 20
-      @offset = response["offset"] || 0
-      @has_more = (@offset + @data.length) < @total
+      @total = pagination["total"] || response["total"] || response["count"] || @data.length
+      @limit = pagination["limit"] || response["limit"] || 20
+      @offset = pagination["offset"] || response["offset"] || 0
+      @has_more = if pagination.key?("hasMore")
+                    pagination["hasMore"]
+                  else
+                    (@offset + @data.length) < @total
+                  end
     end
 
     # Iterate over messages
@@ -433,14 +448,31 @@ module Sendly
   end
 
   # Result of testing a webhook
+  #
+  # Only a delivered test comes back as a result: when the test delivery
+  # fails, {Sendly::WebhooksResource#test} raises {Sendly::ValidationError}
+  # with the API's message.
   class WebhookTestResult
     attr_reader :success, :status_code, :response_time_ms, :error
 
+    # @return [String, nil] The API's summary of the test delivery
+    attr_reader :message
+
+    # @return [String, nil] ID of the test delivery
+    attr_reader :delivery_id
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
+
     def initialize(data)
+      delivery = data["delivery"] || {}
+      @raw = data
       @success = data["success"]
-      @status_code = data["status_code"] || data["statusCode"]
-      @response_time_ms = data["response_time_ms"] || data["responseTimeMs"]
-      @error = data["error"]
+      @status_code = data["status_code"] || data["statusCode"] || delivery["status_code"]
+      @response_time_ms = data["response_time_ms"] || data["responseTimeMs"] || delivery["response_time"]
+      @error = data["error"] || delivery["error"]
+      @message = data["message"]
+      @delivery_id = delivery["id"] || delivery["delivery_id"]
     end
 
     def success?
@@ -449,14 +481,49 @@ module Sendly
   end
 
   # Result of rotating webhook secret
+  #
+  # The API signs deliveries with the new secret from the moment the rotation
+  # returns and does not keep the old one, so {#new_secret} is the only secret
+  # that verifies deliveries from then on.
   class WebhookSecretRotation
-    attr_reader :webhook, :new_secret, :old_secret_expires_at, :message
+    # @return [Sendly::Webhook, nil] Always +nil+: the rotation response does not include the webhook
+    attr_reader :webhook
+
+    # @return [String] The new signing secret. It is shown only once.
+    attr_reader :new_secret
+
+    # @return [Time, nil] Always +nil+: the API does not keep the old secret, so it has no expiry
+    attr_reader :old_secret_expires_at
+
+    # @return [String, nil] Confirmation message
+    attr_reader :message
+
+    # @return [String, nil] The webhook's ID
+    attr_reader :id
+
+    # @return [Integer, nil] The webhook's secret version as the API reports it
+    attr_reader :new_secret_version
+
+    # @return [Integer, nil] The grace period the API reports (24). The old
+    #   secret is not kept, so it does not verify deliveries during it.
+    attr_reader :grace_period_hours
+
+    # @return [Time, nil] When the secret was rotated
+    attr_reader :rotated_at
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
 
     def initialize(data)
-      @webhook = Webhook.new(data["webhook"])
-      @new_secret = data["new_secret"] || data["newSecret"]
+      @raw = data
+      @webhook = data["webhook"] ? Webhook.new(data["webhook"]) : nil
+      @new_secret = data["new_secret"] || data["newSecret"] || data["secret"]
       @old_secret_expires_at = parse_time(data["old_secret_expires_at"] || data["oldSecretExpiresAt"])
       @message = data["message"]
+      @id = data["id"]
+      @new_secret_version = data["new_secret_version"] || data["newSecretVersion"]
+      @grace_period_hours = data["grace_period_hours"] || data["gracePeriodHours"]
+      @rotated_at = parse_time(data["rotated_at"] || data["rotatedAt"])
     end
 
     private
@@ -475,13 +542,56 @@ module Sendly
 
   # Represents account information
   class Account
-    attr_reader :id, :email, :name, :created_at
+    # @return [String, nil] The user's ID
+    attr_reader :id
+
+    # @return [String, nil] The user's email address
+    attr_reader :email
+
+    # @return [String, nil] The name of the workspace the API key belongs to,
+    #   or +nil+ when the key is not bound to a workspace
+    attr_reader :name
+
+    # @return [Time, nil] When the user signed up
+    attr_reader :created_at
+
+    # @return [Hash, nil] The workspace the API key belongs to
+    #   (+"id"+, +"name"+, +"isPersonal"+), or +nil+
+    attr_reader :organization
+
+    # @return [String, nil] The workspace's ID, the +organization_id+ in webhook payloads
+    attr_reader :organization_id
+
+    # @return [Hash, nil] Credit balances (+"balance"+, +"reservedBalance"+)
+    attr_reader :credits
+
+    # @return [Hash, nil] Business verification (+"status"+, +"type"+, +"region"+,
+    #   +"submittedAt"+, +"updatedAt"+), or +nil+ when there is none
+    attr_reader :verification
+
+    # @return [Hash, nil] The API key making the call (+"id"+, +"name"+, +"type"+,
+    #   +"scopes"+, +"createdAt"+, +"lastUsedAt"+)
+    attr_reader :api_key
+
+    # @return [Hash, nil] Sending limits (+"messagesPerMinute"+, +"messagesPerDay"+)
+    attr_reader :limits
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
 
     def initialize(data)
-      @id = data["id"]
-      @email = data["email"]
-      @name = data["name"]
-      @created_at = parse_time(data["created_at"] || data["createdAt"])
+      user = data["user"] || {}
+      @raw = data
+      @organization = data["organization"]
+      @organization_id = @organization && @organization["id"]
+      @id = user["id"] || data["id"]
+      @email = user["email"] || data["email"]
+      @name = (@organization && @organization["name"]) || data["name"]
+      @created_at = parse_time(user["createdAt"] || user["created_at"] || data["created_at"] || data["createdAt"])
+      @credits = data["credits"]
+      @verification = data["verification"]
+      @api_key = data["apiKey"] || data["api_key"]
+      @limits = data["limits"]
     end
 
     private
@@ -509,8 +619,9 @@ module Sendly
   class CreditTransaction
     attr_reader :id, :type, :amount, :balance_after, :description, :message_id, :created_at
 
-    # Transaction type constants
-    TYPES = %w[purchase usage refund adjustment bonus].freeze
+    # Transaction type constants. Auto-recharges are recorded as +purchase+;
+    # +adjustment+ is never recorded.
+    TYPES = %w[purchase usage refund adjustment bonus transfer admin_grant admin_seed].freeze
 
     def initialize(data)
       @id = data["id"]
@@ -542,20 +653,41 @@ module Sendly
 
   # Represents an API key
   class ApiKey
-    attr_reader :id, :name, :type, :prefix, :last_four, :permissions,
+    attr_reader :id, :name, :type, :prefix, :permissions,
                 :created_at, :last_used_at, :expires_at, :is_revoked
 
+    # @return [nil] Always +nil+: no API response carries the last four characters
+    attr_reader :last_four
+
+    # @return [Array<String>] The key's scopes (the same list as {#permissions})
+    attr_reader :scopes
+
+    # @return [Boolean, nil] Whether the key is active, or +nil+ when the response does not say
+    attr_reader :is_active
+
+    # @return [Time, nil] When the key was revoked
+    attr_reader :revoked_at
+
     def initialize(data)
       @id = data["id"]
       @name = data["name"]
       @type = data["type"]
       @prefix = data["prefix"]
       @last_four = data["last_four"] || data["lastFour"]
-      @permissions = data["permissions"] || []
+      @permissions = data["permissions"] || data["scopes"] || []
+      @scopes = data["scopes"] || data["permissions"] || []
       @created_at = parse_time(data["created_at"] || data["createdAt"])
       @last_used_at = parse_time(data["last_used_at"] || data["lastUsedAt"])
       @expires_at = parse_time(data["expires_at"] || data["expiresAt"])
-      @is_revoked = data["is_revoked"] || data["isRevoked"] || false
+      @revoked_at = parse_time(data["revoked_at"] || data["revokedAt"])
+      @is_active = data.key?("isActive") ? data["isActive"] : data["is_active"]
+      @is_revoked = if data.key?("isRevoked") || data.key?("is_revoked")
+                      data["isRevoked"] || data["is_revoked"] || false
+                    elsif !@is_active.nil?
+                      !@is_active
+                    else
+                      !@revoked_at.nil?
+                    end
     end
 
     def test?
@@ -842,13 +974,20 @@ module Sendly
 
     attr_reader :data, :total, :limit, :offset, :has_more
 
-    def initialize(response)
+    # @param response [Hash] The parsed list response
+    # @param limit [Integer, nil] The page size the API used, when the response does not say
+    # @param offset [Integer, nil] The offset the API used, when the response does not say
+    def initialize(response, limit = nil, offset = nil)
       @data = (response["data"] || []).map { |d| Draft.new(d) }
       pagination = response["pagination"] || {}
       @total = pagination["total"] || @data.length
-      @limit = pagination["limit"] || 20
-      @offset = pagination["offset"] || 0
-      @has_more = pagination["hasMore"] || pagination["has_more"] || false
+      @limit = pagination["limit"] || limit || 20
+      @offset = pagination["offset"] || offset || 0
+      @has_more = if pagination.key?("hasMore") || pagination.key?("has_more")
+                    pagination["hasMore"] || pagination["has_more"] || false
+                  else
+                    (@offset + @data.length) < @total
+                  end
     end
 
     def each(&block)

data/lib/sendly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sendly
-  VERSION = "4.1.0"
+  VERSION = "4.3.0"
 end