sendly 4.0.0 → 4.2.0

data/lib/sendly/client.rb

@@ -192,6 +192,24 @@ module Sendly
       @rcs ||= RcsResource.new(self)
     end
 
+    # Access the Calls resource (phone calls handled by your AI agents)
+    #
+    # @return [Sendly::CallsResource]
+    def calls
+      @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
@@ -248,10 +266,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.

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
@@ -101,23 +119,24 @@ module Sendly
       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 = 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
   end
 end

data/lib/sendly/numbers_resource.rb

@@ -53,9 +53,22 @@ module Sendly
                 # true when the number is scheduled for release at period end.
                 :pending_cancellation,
                 # ISO-8601 timestamp string, or nil when no release is scheduled.
-                :scheduled_release_at
+                :scheduled_release_at,
+                # true when the number can place and receive phone calls
+                # (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.
+                :voice_mode
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
+
+    VOICE_MODES = %w[none ring_dashboard agent].freeze
 
     def initialize(data)
+      @raw = data
       @id = data["id"]
       @phone_number = data["phoneNumber"] || data["phone_number"]
       @status = data["status"]
@@ -67,6 +80,13 @@ module Sendly
       @requirements_submitted_at = data["requirementsSubmittedAt"] || data["requirements_submitted_at"]
       @pending_cancellation = data.key?("pendingCancellation") ? data["pendingCancellation"] : data["pending_cancellation"]
       @scheduled_release_at = data["scheduledReleaseAt"] || data["scheduled_release_at"]
+      @voice_enabled = data.key?("voiceEnabled") ? data["voiceEnabled"] : data["voice_enabled"]
+      @voice_mode = data["voiceMode"] || data["voice_mode"]
+    end
+
+    # @return [Boolean] Whether the number can be used as the +from+ of a call
+    def voice_enabled?
+      voice_enabled == true
     end
 
     def to_h
@@ -76,7 +96,8 @@ module Sendly
         monthly_cost_cents: monthly_cost_cents, is_default: is_default,
         requirements_submitted_at: requirements_submitted_at,
         pending_cancellation: pending_cancellation,
-        scheduled_release_at: scheduled_release_at
+        scheduled_release_at: scheduled_release_at,
+        voice_enabled: voice_enabled, voice_mode: voice_mode
       }.compact
     end
   end

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/version.rb

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