sendly 4.1.0 → 4.3.0

data/examples/list_messages.rb

@@ -8,7 +8,7 @@ client = Sendly::Client.new(ENV["SENDLY_API_KEY"] || "sk_test_v1_example")
 # List recent messages
 puts "=== Recent Messages ==="
 messages = client.messages.list(limit: 10)
-puts "Total: #{messages.total}"
+puts "Total matching: #{messages.total}"
 puts "Has more: #{messages.has_more}"
 puts
 

data/examples/send_sms.rb

@@ -9,7 +9,7 @@ client = Sendly::Client.new(ENV["SENDLY_API_KEY"] || "sk_test_v1_example")
 # Send an SMS
 begin
   message = client.messages.send(
-    to: "+15551234567",
+    to: "+15125550123",
     text: "Hello from Sendly Ruby SDK!"
   )
 
@@ -25,7 +25,11 @@ rescue Sendly::InsufficientCreditsError => e
 rescue Sendly::ValidationError => e
   puts "Validation error: #{e.message}"
 rescue Sendly::RateLimitError => e
-  puts "Rate limited. Retry after: #{e.retry_after} seconds"
+  if e.response_body&.dig("error") == "too_many_failed_key_attempts"
+    puts "Locked out after repeated wrong API keys. Fix the key, then wait #{e.retry_after} seconds"
+  else
+    puts "Rate limited. Retry after: #{e.retry_after} seconds"
+  end
 rescue Sendly::Error => e
   puts "Error: #{e.message}"
 end

data/lib/sendly/account_resource.rb

@@ -69,17 +69,29 @@ module Sendly
 
     # Create a new API key
     #
+    # A live key needs a verified business and a credit balance; the API
+    # answers 403 +verification_required+ or 402 +credits_required+ otherwise.
+    #
     # @param name [String] Display name for the API key
+    # @param type [String] "test" (the default) or "live"
+    # @param scopes [Array<String>, nil] Scopes for the new key, e.g. ["sms:send"].
+    #   Omit to give it every scope the calling key has; a key cannot grant a
+    #   scope it does not have.
     # @param expires_at [String, nil] Optional expiration date (ISO 8601)
-    # @return [Hash] Contains 'apiKey' (metadata) and 'key' (full secret - only shown once!)
+    # @return [Hash] +{ "id", "name", "key", "keyPrefix", "type", "createdAt",
+    #   "expiresAt", "apiKey" }+, where "key" is the full secret (shown only
+    #   once) and "apiKey" is the key's metadata
+    # @raise [ArgumentError] If +name+ is missing or +type+ is not "test" or "live"
     #
     # @example
-    #   result = client.account.create_api_key("Production")
+    #   result = client.account.create_api_key("Production", type: "live", scopes: ["sms:send"])
     #   puts "Save this key: #{result['key']}"  # Only shown once!
-    def create_api_key(name, expires_at: nil)
+    def create_api_key(name, type: "test", scopes: nil, expires_at: nil)
       raise ArgumentError, "API key name is required" if name.nil? || name.empty?
+      raise ArgumentError, "API key type must be \"test\" or \"live\"" unless %w[test live].include?(type.to_s)
 
-      body = { name: name }
+      body = { name: name, type: type.to_s }
+      body[:scopes] = scopes unless scopes.nil?
       body[:expiresAt] = expires_at if expires_at
 
       @client.post("/account/keys", body)

data/lib/sendly/business_upgrade_resource.rb

@@ -363,7 +363,8 @@ module Sendly
 
       if file_bytes
         body_parts << "--#{boundary}\r\n"
-        body_parts << "Content-Disposition: form-data; name=\"einDoc\"; filename=\"#{filename}\"\r\n"
+        safe_name = filename.to_s.gsub('"', "%22").gsub("\r", "%0D").gsub("\n", "%0A")
+        body_parts << "Content-Disposition: form-data; name=\"einDoc\"; filename=\"#{safe_name}\"\r\n"
         body_parts << "Content-Type: #{content_type}\r\n\r\n"
         body_parts << file_bytes
         body_parts << "\r\n"
@@ -385,7 +386,7 @@ module Sendly
       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
+      req.body = body_parts.map { |part| part.to_s.b }.join
 
       begin
         response = http.request(req)

data/lib/sendly/calls_resource.rb

@@ -23,7 +23,12 @@ module Sendly
   # A phone call placed or received by one of your workspace's numbers.
   #
   # +kind+ is "pstn" for a phone call and "internal" for a browser-to-browser
-  # call between teammates. +status+ is "ringing" or "active" while the call
+  # call between teammates. +channel+ is where the call took place:
+  # "phone", "whatsapp" (a WhatsApp call, for example one placed from the
+  # dashboard) or "browser" (see {CHANNELS}); a value this SDK predates
+  # comes through unchanged, and it is nil when the API doesn't send one.
+  # An inbound WhatsApp call can read "phone" until the carrier labels it.
+  # +status+ is "ringing" or "active" while the call
   # is live and one of the terminal values ("completed", "no_answer", "busy",
   # "cancelled", "declined", "failed") once it has ended; "suspended" can
   # appear on an internal call whose media dropped and may recover.
@@ -40,6 +45,7 @@ module Sendly
     LIVE_STATUSES = %w[ringing active].freeze
     DIRECTIONS = %w[inbound outbound].freeze
     KINDS = %w[pstn internal].freeze
+    CHANNELS = %w[phone whatsapp browser].freeze
     HANDLED_BY = %w[agent dashboard].freeze
     BILLING_STATES = %w[metered settled unbilled].freeze
     RECORDING_STATUSES = %w[recording ready failed].freeze
@@ -58,12 +64,15 @@ module Sendly
       no_voice_number number_not_found destination_not_supported e911_required lines_busy
       daily_call_limit call_not_found live_key_required voice_internal_error
       insufficient_credits invalid_number rate_limit_exceeded forbidden
+      invalid_request insufficient_permissions agent_in_use agent_limit invalid_voice_mode
+      invalid_address e911_not_applicable voice_attach_failed carrier_refused
+      from_number_not_supported
     ].freeze
 
     attr_reader :id, :object, :kind, :direction, :status, :handled_by, :agent_id,
                 :from, :to, :caller_name, :callee_name, :started_at, :answered_at,
                 :ended_at, :duration_secs, :credits_charged, :billing, :hangup_class,
-                :recording_status, :metadata, :transcript
+                :recording_status, :metadata, :transcript, :channel
 
     # @return [Hash] The raw parsed response
     attr_reader :raw
@@ -74,6 +83,7 @@ module Sendly
       @id = data["id"]
       @object = data["object"] || "call"
       @kind = data["kind"]
+      @channel = data["channel"]
       @direction = data["direction"]
       @status = data["status"]
       @handled_by = data["handledBy"] || data["handled_by"]
@@ -123,7 +133,7 @@ module Sendly
 
     def to_h
       {
-        id: id, object: object, kind: kind, direction: direction, status: status,
+        id: id, object: object, kind: kind, channel: channel, direction: direction, status: status,
         handled_by: handled_by, agent_id: agent_id, from: from, to: to,
         caller_name: caller_name, callee_name: callee_name, started_at: started_at,
         answered_at: answered_at, ended_at: ended_at, duration_secs: duration_secs,
@@ -182,8 +192,8 @@ module Sendly
   # call runs, "ready" once it can be fetched, or "failed". +url+ and
   # +expires_at+ are set only when {#ready?}: the URL is signed and valid for
   # five minutes. Recordings are Ogg/Opus (+content_type+ "audio/ogg");
-  # agent-handled calls are recorded dual-channel, caller left and agent
-  # right.
+  # agent-handled calls are recorded dual-channel, with the agent on the
+  # left channel and the other party on the right.
   class CallRecording
     STATUSES = %w[none recording ready failed].freeze
 
@@ -213,9 +223,10 @@ module Sendly
   # Calls resource: place phone calls handled by your AI agents, list and
   # inspect calls, end a call and fetch recordings.
   #
-  # A call placed over the API is answered by one of the AI agents you
-  # configure in the dashboard under Calls, then Agents; the +from+ number
-  # must have voice switched on in the dashboard. Calls are charged per
+  # A call placed over the API is answered by one of your AI agents
+  # (create them with {VoiceAgentsResource#create} or in the dashboard
+  # under Calls, then Agents); the +from+ number must have voice switched
+  # on ({VoiceNumbersResource#update} or the dashboard). Calls are charged per
   # started minute from your credit balance: 2 credits a minute outbound,
   # plus 8 a minute while an agent is on the call. Destinations are US and
   # Canadian numbers. Reads need the +calls:read+ scope, writes
@@ -228,9 +239,9 @@ module Sendly
   # +voice_not_enabled+, +outbound_calls_not_enabled+, +agent_not_found+,
   # +number_not_found+ and +call_not_found+; {Sendly::ValidationError} for
   # +invalid_number+, +destination_not_supported+, +agent_required+,
-  # +invalid_metadata+ and +from_number_required+;
-  # {Sendly::InsufficientCreditsError} for +insufficient_credits+;
-  # {Sendly::RateLimitError} for +daily_call_limit+ and
+  # +invalid_metadata+, +from_number_required+ and
+  # +from_number_not_supported+; {Sendly::InsufficientCreditsError} for
+  # +insufficient_credits+; {Sendly::RateLimitError} for +daily_call_limit+ and
   # +rate_limit_exceeded+; {Sendly::APIError} with the HTTP status for
   # +e911_required+ (428), +agent_disabled+ / +no_voice_number+ /
   # +lines_busy+ (409) and +live_key_required+ / +forbidden+ (403); and
@@ -261,7 +272,9 @@ module Sendly
     # @param agent_id [String] The AI agent that talks on the call
     # @param from [String, nil] A voice-enabled number in your workspace.
     #   Optional when the workspace has exactly one; required (the API
-    #   responds 400 +from_number_required+) when it has more.
+    #   responds 400 +from_number_required+) when it has more. Calls can
+    #   only be placed from US and Canadian numbers (400
+    #   +from_number_not_supported+ otherwise).
     # @param context [String, nil] Up to 2000 characters appended to the
     #   agent's instructions for this call only. Not echoed back.
     # @param metadata [Hash{String => String}, nil] Up to 20 string pairs
@@ -272,13 +285,15 @@ module Sendly
     # @return [Sendly::Call] The new call (+status+ "ringing", +handled_by+ "agent")
     # @raise [Sendly::ValidationError] If +to+ or +agent_id+ is missing, or
     #   HTTP 400 (+invalid_number+, +destination_not_supported+,
-    #   +agent_required+, +invalid_metadata+, +from_number_required+)
+    #   +agent_required+, +invalid_metadata+, +from_number_required+,
+    #   +from_number_not_supported+)
     # @raise [Sendly::NotFoundError] HTTP 404 (+voice_not_enabled+,
     #   +outbound_calls_not_enabled+, +agent_not_found+, +number_not_found+)
     # @raise [Sendly::InsufficientCreditsError] HTTP 402 when the balance
     #   cannot cover one minute at the agent rate
     # @raise [Sendly::APIError] HTTP 428 +e911_required+ (register an
-    #   emergency address for the number first), 409 +agent_disabled+ /
+    #   emergency address for the number first with
+    #   {VoiceNumbersResource#register_emergency_address}), 409 +agent_disabled+ /
     #   +no_voice_number+ / +lines_busy+, 403 +live_key_required+
     # @raise [Sendly::RateLimitError] HTTP 429 +daily_call_limit+ / +rate_limit_exceeded+
     # @raise [Sendly::ServerError] HTTP 503 +voice_unavailable+ /

data/lib/sendly/campaigns_resource.rb

@@ -1,22 +1,29 @@
 # frozen_string_literal: true
 
 module Sendly
+  # A campaign. A sent campaign's status is +completed+. +recipient_count+
+  # is the number of recipients it was sent to, or for a scheduled campaign
+  # the number it will be sent to (0 for a draft). +started_at+ is when
+  # sending began. +template_id+ is always +nil+: the API does not return it.
   class Campaign
     attr_reader :id, :name, :text, :template_id, :contact_list_ids, :status,
                 :recipient_count, :sent_count, :delivered_count, :failed_count,
                 :estimated_credits, :credits_used, :scheduled_at, :timezone,
                 :started_at, :completed_at, :created_at, :updated_at
 
-    STATUSES = %w[draft scheduled sending sent paused cancelled failed].freeze
+    # Campaign statuses. The API returns +draft+, +scheduled+, +sending+,
+    # +completed+, +cancelled+ and +failed+; +sent+ and +paused+ are never
+    # returned.
+    STATUSES = %w[draft scheduled sending sent paused cancelled failed completed].freeze
 
     def initialize(data)
       @id = data["id"]
       @name = data["name"]
-      @text = data["text"]
+      @text = data["text"] || data["messageText"]
       @template_id = data["template_id"] || data["templateId"]
-      @contact_list_ids = data["contact_list_ids"] || data["contactListIds"] || []
+      @contact_list_ids = data["contact_list_ids"] || data["contactListIds"] || [data["targetListId"]].compact
       @status = data["status"]
-      @recipient_count = data["recipient_count"] || data["recipientCount"] || 0
+      @recipient_count = data["recipient_count"] || data["recipientCount"] || data["totalRecipients"] || 0
       @sent_count = data["sent_count"] || data["sentCount"] || 0
       @delivered_count = data["delivered_count"] || data["deliveredCount"] || 0
       @failed_count = data["failed_count"] || data["failedCount"] || 0
@@ -24,7 +31,7 @@ module Sendly
       @credits_used = data["credits_used"] || data["creditsUsed"] || 0
       @scheduled_at = parse_time(data["scheduled_at"] || data["scheduledAt"])
       @timezone = data["timezone"]
-      @started_at = parse_time(data["started_at"] || data["startedAt"])
+      @started_at = parse_time(data["started_at"] || data["startedAt"] || data["sentAt"])
       @completed_at = parse_time(data["completed_at"] || data["completedAt"])
       @created_at = parse_time(data["created_at"] || data["createdAt"])
       @updated_at = parse_time(data["updated_at"] || data["updatedAt"])
@@ -42,8 +49,14 @@ module Sendly
       status == "sending"
     end
 
+    # @return [Boolean] Whether the campaign has been sent (status +completed+)
     def sent?
-      status == "sent"
+      %w[sent completed].include?(status)
+    end
+
+    # @return [Boolean] Whether the status is +completed+, which is what a sent campaign becomes
+    def completed?
+      status == "completed"
     end
 
     def cancelled?
@@ -73,6 +86,9 @@ module Sendly
     end
   end
 
+  # A campaign's recipient count and cost estimate. +id+ and
+  # +estimated_segments+ are not returned by the API (+nil+ and 0).
+  # +breakdown+ is per country: +{ "US" => { "count", "credits", "allowed" } }+.
   class CampaignPreview
     attr_reader :id, :recipient_count, :estimated_segments, :estimated_credits,
                 :current_balance, :has_enough_credits, :breakdown,
@@ -85,7 +101,7 @@ module Sendly
       @estimated_credits = data["estimated_credits"] || data["estimatedCredits"] || 0
       @current_balance = data["current_balance"] || data["currentBalance"] || 0
       @has_enough_credits = data["has_enough_credits"] || data["hasEnoughCredits"] || false
-      @breakdown = data["breakdown"]
+      @breakdown = data["breakdown"] || data["byCountry"]
       @blocked_count = data["blocked_count"] || data["blockedCount"]
       @sendable_count = data["sendable_count"] || data["sendableCount"]
       @warnings = data["warnings"]
@@ -97,6 +113,37 @@ module Sendly
     end
   end
 
+  # The result of {CampaignsResource#send_campaign}: the batch the campaign's
+  # messages went out in. +id+ is the campaign's ID, +status+ the batch's
+  # (+processing+, +completed+, +partial_failure+ or +failed+), and
+  # +recipient_count+ the messages in the batch. Name, text and dates are not
+  # part of the response; read the campaign with {CampaignsResource#get}.
+  class CampaignSendResult < Campaign
+    # @return [String] Batch the messages went out in; see {Sendly::Messages#get_batch}
+    attr_reader :batch_id
+
+    # @return [Integer] Credits returned for messages that failed
+    attr_reader :credits_refunded
+
+    # @return [Array<Hash>] Each message in the batch; empty while the batch is processing
+    attr_reader :messages
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
+
+    def initialize(data, campaign_id = nil)
+      super(data)
+      @raw = data
+      @id = campaign_id || data["id"]
+      @batch_id = data["batchId"] || data["batch_id"]
+      @recipient_count = data["total"] || @recipient_count
+      @sent_count = data["sent"] || @sent_count
+      @failed_count = data["failed"] || @failed_count
+      @credits_refunded = data["creditsRefunded"] || data["credits_refunded"] || 0
+      @messages = data["messages"] || []
+    end
+  end
+
   class CampaignsResource
     def initialize(client)
       @client = client
@@ -155,9 +202,13 @@ module Sendly
       CampaignPreview.new(response)
     end
 
+    # Send a campaign now.
+    #
+    # @param id [String] Campaign ID
+    # @return [Sendly::CampaignSendResult] The batch the campaign went out in
     def send_campaign(id)
       response = @client.post("/campaigns/#{URI.encode_www_form_component(id)}/send")
-      Campaign.new(response)
+      CampaignSendResult.new(response, id)
     end
 
     def schedule(id, scheduled_at:, timezone: nil)

data/lib/sendly/client.rb

@@ -199,6 +199,17 @@ module Sendly
       @calls ||= CallsResource.new(self)
     end
 
+    # Access the Voice resource (numbers, AI agents and voices for phone calls)
+    #
+    # @return [Sendly::VoiceResource]
+    #
+    # @example
+    #   agent = client.voice.agents.create(name: "Front desk")
+    #   client.voice.numbers.update("+15555550188", voice_enabled: true, voice_mode: "agent", agent_id: agent.id)
+    def voice
+      @voice ||= VoiceResource.new(self)
+    end
+
     # Make a GET request
     #
     # @param path [String] API path
@@ -221,10 +232,11 @@ module Sendly
     # @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)
+    # @param retry_server_errors [Boolean] Retry a 5xx before raising it (default: true)
     # @return [Hash] Response body
-    def post(path, body = {}, idempotency_key: nil, auto_idempotency_key: true)
+    def post(path, body = {}, idempotency_key: nil, auto_idempotency_key: true, retry_server_errors: true)
       request(:post, path, body: body, idempotency_key: idempotency_key,
-                           auto_idempotency_key: auto_idempotency_key)
+                           auto_idempotency_key: auto_idempotency_key, retry_server_errors: retry_server_errors)
     end
 
     # Make a PATCH request
@@ -255,10 +267,14 @@ module Sendly
 
     # Make a DELETE request
     #
+    # No Idempotency-Key is generated for a DELETE; pass +idempotency_key+
+    # to send one (1-255 printable ASCII characters).
+    #
     # @param path [String] API path
+    # @param idempotency_key [String, nil] Caller-supplied idempotency key (optional)
     # @return [Hash] Response body
-    def delete(path)
-      request(:delete, path)
+    def delete(path, idempotency_key: nil)
+      request(:delete, path, idempotency_key: idempotency_key)
     end
 
     # Make a GET request against the API origin, bypassing the +/api/v1+ base.
@@ -297,8 +313,10 @@ module Sendly
     # @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)
+    # @param retry_server_errors [Boolean] Retry a 5xx before raising it (default: true)
     # @return [Hash] Response body
-    def post_multipart(path, file, content_type: "image/jpeg", filename: "upload.jpg", idempotency_key: nil)
+    def post_multipart(path, file, content_type: "image/jpeg", filename: "upload.jpg", idempotency_key: nil,
+                       retry_server_errors: true)
       uri = build_uri(path, {})
       http = build_http(uri)
 
@@ -308,10 +326,11 @@ module Sendly
       boundary = "SendlyRuby#{SecureRandom.hex(16)}"
 
       file_data = file.is_a?(String) ? File.binread(file) : file.read
+      safe_name = filename.to_s.gsub('"', "%22").gsub("\r", "%0D").gsub("\n", "%0A")
 
       body = []
       body << "--#{boundary}\r\n"
-      body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\"\r\n"
+      body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{safe_name}\"\r\n"
       body << "Content-Type: #{content_type}\r\n\r\n"
       body << file_data
       body << "\r\n--#{boundary}--\r\n"
@@ -322,7 +341,7 @@ module Sendly
       req["User-Agent"] = "sendly-ruby/#{VERSION}"
       req["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
       req["X-Organization-Id"] = @organization_id if @organization_id
-      req.body = body.join
+      req.body = body.map { |part| part.to_s.b }.join
 
       attempt = 0
       begin
@@ -335,18 +354,14 @@ module Sendly
         raise NetworkError, "Connection failed: #{e.message}"
       rescue RateLimitError => e
         attempt += 1
-        if attempt <= max_retries && e.retry_after
+        if attempt <= max_retries && e.retry_after && retryable_rate_limit?(e)
           sleep(e.retry_after)
           retry
         end
         raise
       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?
+        if retry_server_errors && attempt <= max_retries
           sleep(2 ** attempt)
           retry
         end
@@ -363,6 +378,17 @@ module Sendly
 
     private
 
+    RETRYABLE_RATE_LIMIT_CODES = [
+      nil, "rate_limit_exceeded", "provision_rate_limit", "too_many_concurrent_verifications"
+    ].freeze
+    MAX_RETRY_WAIT_SECONDS = 60
+    private_constant :RETRYABLE_RATE_LIMIT_CODES, :MAX_RETRY_WAIT_SECONDS
+
+    def retryable_rate_limit?(error)
+      code = error.response_body.is_a?(Hash) ? error.response_body["error"] : nil
+      RETRYABLE_RATE_LIMIT_CODES.include?(code) && error.retry_after.to_f <= MAX_RETRY_WAIT_SECONDS
+    end
+
     def validate_api_key!
       raise AuthenticationError, "API key is required" if api_key.nil? || api_key.empty?
 
@@ -372,7 +398,7 @@ module Sendly
     end
 
     def request(method, path, params: {}, body: nil, unversioned: false, idempotency_key: nil,
-                auto_idempotency_key: true)
+                auto_idempotency_key: true, retry_server_errors: true)
       uri = build_uri(path, params, unversioned: unversioned)
       http = build_http(uri)
       req = build_request(method, uri, body)
@@ -392,18 +418,14 @@ module Sendly
         raise NetworkError, "Connection failed: #{e.message}"
       rescue RateLimitError => e
         attempt += 1
-        if attempt <= max_retries && e.retry_after
+        if attempt <= max_retries && e.retry_after && retryable_rate_limit?(e)
           sleep(e.retry_after)
           retry
         end
         raise
       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?
+        if retry_server_errors && attempt <= max_retries
           sleep(2 ** attempt) # Exponential backoff
           retry
         end
@@ -429,6 +451,7 @@ module Sendly
     end
 
     def build_uri(path, params, unversioned: false)
+      validate_path_segments!(path)
       base = unversioned ? api_origin : base_url
       url = "#{base}#{path}"
       uri = URI.parse(url)
@@ -441,6 +464,16 @@ module Sendly
       uri
     end
 
+    DOT_SEGMENT = /\A(?:\.|%2e){1,2}\z/i
+    private_constant :DOT_SEGMENT
+
+    def validate_path_segments!(path)
+      segments = path.to_s.split("?", 2).first.to_s.split("/", -1).drop(1)
+      return unless segments.any? { |segment| segment.empty? || DOT_SEGMENT.match?(segment) }
+
+      raise ValidationError, "IDs in a request path cannot be empty, '.' or '..'"
+    end
+
     # Derive the bare API origin (scheme + host [+ non-default port]) from the
     # configured base URL, dropping its path. Origin-level endpoints such as
     # the URL shortener at +/api/links+ hang off this, not the +/api/v1+ base.
@@ -491,7 +524,8 @@ module Sendly
 
       return body if status >= 200 && status < 300
 
-      raise ErrorFactory.from_response(status, body)
+      retry_after = status == 429 ? response["Retry-After"] : nil
+      raise ErrorFactory.from_response(status, body, retry_after_header: retry_after)
     end
 
     def parse_body(body)

data/lib/sendly/conversations_resource.rb

@@ -30,11 +30,23 @@ module Sendly
       ConversationWithMessages.new(response)
     end
 
-    def reply(id, text:, media_urls: nil, metadata: nil)
+    # Reply in a conversation. Send +text+, +media_urls+, or both.
+    #
+    # @param id [String] Conversation ID
+    # @param text [String, nil] Message text
+    # @param media_urls [Array<String>, nil] Media to attach (sent as MMS)
+    # @param metadata [Hash, nil] Custom metadata
+    # @return [Sendly::Message] The sent message
+    # @raise [Sendly::ValidationError] If +id+ is missing, or there is neither text nor media
+    def reply(id, text: nil, media_urls: nil, metadata: nil)
       raise ValidationError, "Conversation ID is required" if id.nil? || id.empty?
-      raise ValidationError, "Message text is required" if text.nil? || text.empty?
 
-      body = { text: text }
+      has_text = !(text.nil? || text.empty?)
+      has_media = media_urls.is_a?(Array) && !media_urls.empty?
+      raise ValidationError, "Provide 'text' or 'media_urls'" unless has_text || has_media
+
+      body = {}
+      body[:text] = text if has_text
       body[:mediaUrls] = media_urls if media_urls
       body[:metadata] = metadata if metadata
 
@@ -123,9 +135,9 @@ module Sendly
         page = list(limit: batch_size, offset: offset, status: status)
         page.each(&block)
 
-        break unless page.has_more
+        break if !page.has_more || page.count.zero?
 
-        offset += batch_size
+        offset += page.count
       end
     end
   end

data/lib/sendly/drafts_resource.rb

@@ -24,7 +24,8 @@ module Sendly
       params[:offset] = offset if offset
 
       response = @client.get("/drafts", params.compact)
-      DraftList.new(response)
+      page_size = limit.to_s.empty? ? 50 : [limit.to_s.to_i, 100].min
+      DraftList.new(response, page_size, offset.to_s.to_i)
     end
 
     def get(id)

data/lib/sendly/enterprise.rb

@@ -102,13 +102,23 @@ module Sendly
       submit_verification(workspace_id, **partial_updates)
     end
 
-    def inherit_verification(workspace_id, source_workspace_id:)
+    # Give a workspace the verification of another workspace you own.
+    #
+    # By default the workspace shares the source's verification and sending
+    # number. Pass +purchase_new_number: true+ to copy only the business
+    # details and buy the workspace its own toll-free number; the response
+    # then has +"newNumber" => true+.
+    #
+    #   client.enterprise.workspaces.inherit_verification(workspace_id,
+    #     source_workspace_id: source_id, purchase_new_number: true)
+    def inherit_verification(workspace_id, source_workspace_id:, purchase_new_number: nil)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
       raise ArgumentError, "Source workspace ID is required" if source_workspace_id.nil? || source_workspace_id.empty?
 
-      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/verification/inherit", {
-        source_workspace_id: source_workspace_id
-      })
+      body = { sourceWorkspaceId: source_workspace_id }
+      body[:purchaseNewNumber] = purchase_new_number unless purchase_new_number.nil?
+
+      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/verification/inherit", body)
     end
 
     def get_verification(workspace_id)
@@ -134,12 +144,13 @@ module Sendly
       @client.get("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/credits")
     end
 
-    def create_key(workspace_id, name: nil, type: nil)
+    def create_key(workspace_id, name: nil, type: nil, scopes: nil)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
+      raise ArgumentError, "Key name is required" if name.nil? || name.to_s.empty?
 
-      body = {}
-      body[:name] = name if name
+      body = { name: name }
       body[:type] = type if type
+      body[:scopes] = scopes unless scopes.nil?
 
       @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/keys", body)
     end
@@ -245,7 +256,7 @@ module Sendly
 
     def provision_bulk(workspaces)
       raise ArgumentError, "Workspaces array is required" if workspaces.nil? || !workspaces.is_a?(Array) || workspaces.empty?
-      raise ArgumentError, "Maximum 50 workspaces per bulk provision" if workspaces.length > 50
+      raise ArgumentError, "Maximum 100 workspaces per bulk provision" if workspaces.length > 100
 
       @client.post("/enterprise/workspaces/provision/bulk", { workspaces: workspaces })
     end
@@ -470,7 +481,7 @@ module Sendly
                      else "application/octet-stream"
                      end
 
-      filename = File.basename(file_path)
+      filename = File.basename(file_path).gsub('"', "%22").gsub("\r", "%0D").gsub("\n", "%0A")
 
       boundary = "SendlyRuby#{SecureRandom.hex(16)}"
       body_parts = []
@@ -507,7 +518,7 @@ module Sendly
       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
+      req.body = body_parts.map { |part| part.to_s.b }.join
 
       response = http.request(req)
       body = response.body.nil? || response.body.empty? ? {} : JSON.parse(response.body)