sendly 4.2.0 → 4.3.0

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/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.2.0"
+  VERSION = "4.3.0"
 end

data/lib/sendly/webhooks_resource.rb

@@ -16,6 +16,8 @@ module Sendly
     # @param mode [String, nil] Event mode filter: "all", "test", or "live" (live requires verification)
     # @param metadata [Hash, nil] Custom metadata
     # @return [Sendly::WebhookCreatedResponse]
+    # @raise [ArgumentError] If +url+ is not an https:// URL or +events+ is
+    #   empty; no request is sent
     #
     # @example
     #   webhook = client.webhooks.create(
@@ -65,6 +67,8 @@ module Sendly
     # @param mode [String, nil] Event mode filter: "all", "test", or "live"
     # @param metadata [Hash, nil] Custom metadata
     # @return [Sendly::Webhook]
+    # @raise [ArgumentError] If +webhook_id+ does not start with +whk_+ or
+    #   +url+ is not an https:// URL; no request is sent
     def update(webhook_id, url: nil, events: nil, description: nil, is_active: nil, mode: nil, metadata: nil)
       validate_webhook_id!(webhook_id)
       raise ArgumentError, "Webhook URL must be HTTPS" if url && !url.start_with?("https://")
@@ -94,7 +98,9 @@ module Sendly
     # Test a webhook endpoint
     #
     # @param webhook_id [String] Webhook ID
-    # @return [Sendly::WebhookTestResult]
+    # @return [Sendly::WebhookTestResult] The delivered test, with its status code and timing
+    # @raise [Sendly::ValidationError] If the test delivery fails; the message
+    #   is the API's, e.g. "Test webhook failed: ..."
     def test(webhook_id)
       validate_webhook_id!(webhook_id)
       response = @client.post("/webhooks/#{URI.encode_www_form_component(webhook_id)}/test")
@@ -139,8 +145,10 @@ module Sendly
     # Backfill missed webhook events from the underlying message log.
     #
     # Use when a circuit-breaker outage left events with no audit row (the
-    # case {#redeliver} cannot recover). Synthesized events have fresh IDs;
-    # clients should dedupe by event.data.object.id (the message ID).
+    # case {#redeliver} cannot recover). Synthesized message events carry the
+    # same event id the original dispatch used, so dedupe on event.id. Do not
+    # dedupe on event.data.object.id: a message's sent and delivered events
+    # share it.
     # Rejects with HTTP 409 if the circuit is currently open — call
     # {#reset_circuit} first.
     #
@@ -162,6 +170,11 @@ module Sendly
 
     # Rotate the webhook signing secret
     #
+    # Deliveries are signed with the new secret as soon as this returns, and
+    # the old secret is not kept, so have your endpoint accept both secrets
+    # while you deploy the new one. The new secret is shown only once, on
+    # {Sendly::WebhookSecretRotation#new_secret}.
+    #
     # @param webhook_id [String] Webhook ID
     # @return [Sendly::WebhookSecretRotation]
     def rotate_secret(webhook_id)
@@ -170,14 +183,24 @@ module Sendly
       WebhookSecretRotation.new(response)
     end
 
-    # Get delivery history for a webhook
+    # Get delivery history for a webhook, newest first
     #
     # @param webhook_id [String] Webhook ID
+    # @param limit [Integer, nil] Maximum deliveries to return (the API defaults to 50, max 100)
+    # @param offset [Integer, nil] Number of deliveries to skip
+    # @param status [String, nil] Only deliveries with this status
+    #   (see {Sendly::WebhookDelivery::STATUSES})
     # @return [Array<Sendly::WebhookDelivery>]
-    def deliveries(webhook_id)
+    def deliveries(webhook_id, limit: nil, offset: nil, status: nil)
       validate_webhook_id!(webhook_id)
-      response = @client.get("/webhooks/#{URI.encode_www_form_component(webhook_id)}/deliveries")
-      response.map { |data| WebhookDelivery.new(data) }
+      params = {}
+      params[:limit] = limit unless limit.nil?
+      params[:offset] = offset unless offset.nil?
+      params[:status] = status unless status.nil?
+
+      response = @client.get("/webhooks/#{URI.encode_www_form_component(webhook_id)}/deliveries", params)
+      items = response.is_a?(Hash) ? response["deliveries"] : response
+      (items || []).map { |data| WebhookDelivery.new(data) }
     end
 
     # Retry a failed delivery