sendly 3.31.0 → 3.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80748f70518bf065b5c3aec3495bbc69ef4641793a57186757ea1f10957de933
-  data.tar.gz: b98259199daccc2948950da3a6058b4b66140ff72b4c8a9b1ad5fae6a59a639c
+  metadata.gz: 71c3ad356b4aa2903e05f1f174ce9a70f1fb1fe5cc4b0748ae69db333a0c25ac
+  data.tar.gz: 86df6410241d17dc84854057d19b2b13e6f32f504bf87243e276ec9260f78a34
 SHA512:
-  metadata.gz: 796976f6e39f8bb3fad45e86b9bdb5256521c46dbe566ace7c14ccb72192ea4902c79965b93cdf757eb23677e254166cbdc0ba2195ef51c0c90d85c7365984c6
-  data.tar.gz: 32b41bc79313a7f26d6cd6dac95125ad210168be1dcd8ca9e2389a7d1beb2c4678fa7f32769e4263c102cdf1b94ed68276bb8c84b84d5dc67c992c9238a1f230
+  metadata.gz: 385c9b3f1973a51b923fed18d0b23a128c060d0d122ed782e08f3a21c1477ece2caca8aaeba65c71c8c494946630ffe21e9ac12eade63530ea207de10dfa0661
+  data.tar.gz: 6e274e7b40280d52118812b61ffa31b936d912baa0147027a448c7156d110ed24e4c3c0ba70f2a589bae3d0b3531316761a80fe2864fa821415002e0d3741f01

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 # sendly (Ruby)
 
+## 3.33.0
+
+### Minor Changes
+
+- New `client.conversations.suggest_replies(id)` method — `POST /api/v1/conversations/:id/suggest-replies`. Returns AI-generated reply suggestions for a conversation based on its recent message history, mirroring the Node SDK's `conversations.suggestReplies()` and the equivalent methods on the other Sendly SDKs (closes a feature parity gap). Returns a `Sendly::SuggestRepliesResponse`, which is `Enumerable` over its `SuggestedReply` entries and also exposes `#suggestions`, `#based_on_message_id`, and `#model`.
+
+  ```ruby
+  client = Sendly::Client.new("sk_live_v1_xxx")
+
+  result = client.conversations.suggest_replies("conv_abc123")
+  result.suggestions.each do |reply|
+    puts "[#{reply.tone}] #{reply.text}"
+  end
+  ```
+
+## 3.32.0
+
+### Minor Changes
+
+- New `business_upgrade` resource for the toll-free entity-upgrade ("fork-with-new-number") flow. When a customer forms a new legal entity (e.g. an LLC), this resource lets them reserve a new toll-free number under the new entity, submit it for carrier review, and atomically swap to it on approval — without disrupting outbound SMS during the 1-2 week review window. Mirrors the Node SDK's `businessUpgrade` resource at parity.
+
+  ```ruby
+  client = Sendly::Client.new("sk_live_v1_xxx")
+
+  # Validate before submitting (no writes)
+  preview = client.business_upgrade.preflight(
+    business_name: "Acme Holdings LLC",
+    brn: "12-3456789",
+    brn_type: "EIN",
+    brn_country: "US",
+    entity_type: "PRIVATE_PROFIT"
+  )
+
+  # Best-of prefill across all the caller's verified workspaces
+  prefill = client.business_upgrade.best_prefill
+
+  # Submit the upgrade with the IRS letter (multipart upload)
+  result = client.business_upgrade.start(
+    "ws_abc",
+    business_name: "Acme Holdings LLC",
+    brn: "12-3456789",
+    brn_type: "EIN",
+    brn_country: "US",
+    entity_type: "PRIVATE_PROFIT",
+    ein_doc_path: "./CP-575.pdf"
+  )
+
+  # Status, cancel, resubmit, set old-number disposition
+  client.business_upgrade.status("ws_abc")
+  client.business_upgrade.cancel("ws_abc")
+  client.business_upgrade.resubmit("ws_abc", contact_email: "new@acme.com")
+  client.business_upgrade.set_disposition("ws_abc", disposition: "released")
+  client.business_upgrade.set_disposition("ws_abc", disposition: "moved", target_workspace_id: "ws_xyz")
+  ```
+
+  Methods: `preflight`, `best_prefill`, `start`, `status`, `cancel`, `resubmit`, `set_disposition`. EIN PDFs can be passed via `ein_doc_path:` (file path) or `ein_doc:` (raw bytes / IO).
+
 ## 3.31.0
 
 ### Patch Changes

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sendly (3.31.0)
+    sendly (3.34.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 

data/README.md

@@ -291,6 +291,47 @@ puts "New key: #{result['key']}"  # Only shown once!
 client.account.revoke_api_key('key_xxx')
 ```
 
+## Numbers
+
+Search for, list, and purchase phone numbers. Requires an API key with the
+`numbers:read` / `numbers:write` scopes.
+
+```ruby
+# List supported countries and the number types available in each
+client.numbers.list_countries[:countries].each do |country|
+  puts "#{country.code} #{country.name}: #{country.number_types.join(', ')}"
+end
+
+# Find available numbers (monthly_cost is already customer-priced)
+result = client.numbers.list_available(country: 'GB', type: 'mobile', contains: '777')
+number = result[:numbers].first
+puts "#{number.phone_number} — #{number.monthly_cost} #{number.currency}/mo"
+
+# List numbers you already own
+client.numbers.list[:numbers].each do |n|
+  puts "#{n.phone_number} (#{n.status})"
+end
+
+# Buy a number
+purchase = client.numbers.buy(
+  phone_number: number.phone_number,
+  country_code: number.country,
+  phone_number_type: number.number_type,
+  monthly_cost: number.monthly_cost
+)
+
+case purchase.status
+when 'provisioning'
+  puts "Provisioning #{purchase.number.phone_number}"
+when 'documents_required', 'payment_required'
+  # Hand the user the hosted page + code, wait for them to finish, then
+  # re-call buy with the SAME arguments plus the completed action's code.
+  puts "Visit #{purchase.action_url} and enter code #{purchase.action_code}"
+  # ...after the action completes:
+  # client.numbers.buy(..., action_code: purchase.action_code)
+end
+```
+
 ## Error Handling
 
 ```ruby

data/lib/sendly/business_upgrade_resource.rb

@@ -0,0 +1,404 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+
+module Sendly
+  # Business Upgrade resource — Entity-Upgrade ("fork-with-new-number")
+  #
+  # Manages the toll-free business entity upgrade flow: when a customer
+  # forms a new legal entity (e.g. an LLC), this resource lets them
+  # reserve a new toll-free number under the new entity, submit it for
+  # carrier review, and atomically swap to it on approval — without
+  # disrupting outbound SMS during the 1-2 week review window.
+  #
+  # @see https://sendly.live/docs/business-upgrade
+  #
+  # @example Validate before submitting
+  #   preview = client.business_upgrade.preflight(
+  #     business_name: "Acme Holdings LLC",
+  #     brn: "12-3456789",
+  #     brn_type: "EIN",
+  #     brn_country: "US",
+  #     entity_type: "PRIVATE_PROFIT"
+  #   )
+  #
+  # @example Submit an upgrade with the IRS letter
+  #   result = client.business_upgrade.start(
+  #     "ws_abc",
+  #     business_name: "Acme Holdings LLC",
+  #     brn: "12-3456789",
+  #     brn_type: "EIN",
+  #     brn_country: "US",
+  #     entity_type: "PRIVATE_PROFIT",
+  #     ein_doc_path: "./CP-575.pdf"
+  #   )
+  class BusinessUpgradeResource
+    # Entity types accepted by the carrier
+    ENTITY_TYPES = %w[
+      SOLE_PROPRIETOR
+      PRIVATE_PROFIT
+      PUBLIC_PROFIT
+      NON_PROFIT
+      GOVERNMENT
+    ].freeze
+
+    # Business Registration Number types
+    BRN_TYPES = %w[EIN SSN DUNS CRA VAT LEI OTHER].freeze
+
+    # Disposition options for the old toll-free number after approval
+    DISPOSITIONS = %w[moved released].freeze
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Validate a candidate entity upgrade payload before submission.
+    # Returns issues + proposed auto-fixes. No writes — purely advisory.
+    #
+    # Accepts the same fields as +start+. Returns a hash with
+    # +verdict+ (+"ready"+, +"warnings"+, +"blocked"+), +issues+, and
+    # +proposedFixes+.
+    #
+    # @param business_name [String, nil]
+    # @param brn [String, nil]
+    # @param brn_type [String, nil] One of {BRN_TYPES}
+    # @param brn_country [String, nil] ISO country code
+    # @param entity_type [String, nil] One of {ENTITY_TYPES}
+    # @param doing_business_as [String, nil]
+    # @param website [String, nil]
+    # @param address1 [String, nil]
+    # @param address2 [String, nil]
+    # @param city [String, nil]
+    # @param state [String, nil]
+    # @param zip [String, nil]
+    # @param address_country [String, nil]
+    # @param contact_first_name [String, nil]
+    # @param contact_last_name [String, nil]
+    # @param contact_email [String, nil]
+    # @param contact_phone [String, nil]
+    # @param monthly_volume [String, nil]
+    # @param use_case [String, nil]
+    # @param use_case_summary [String, nil]
+    # @param sample_messages [String, nil]
+    # @param opt_in_workflow [String, nil]
+    # @param privacy_url [String, nil]
+    # @param terms_url [String, nil]
+    # @param additional_information [String, nil]
+    # @param age_gated_content [Boolean, nil]
+    # @return [Hash] Preflight report
+    def preflight(business_name: nil, brn: nil, brn_type: nil, brn_country: nil,
+                  entity_type: nil, doing_business_as: nil, website: nil,
+                  address1: nil, address2: nil, city: nil, state: nil, zip: nil,
+                  address_country: nil, contact_first_name: nil,
+                  contact_last_name: nil, contact_email: nil, contact_phone: nil,
+                  monthly_volume: nil, use_case: nil, use_case_summary: nil,
+                  sample_messages: nil, opt_in_workflow: nil, privacy_url: nil,
+                  terms_url: nil, additional_information: nil,
+                  age_gated_content: nil)
+      body = build_upgrade_body(
+        business_name: business_name, brn: brn, brn_type: brn_type,
+        brn_country: brn_country, entity_type: entity_type,
+        doing_business_as: doing_business_as, website: website,
+        address1: address1, address2: address2, city: city, state: state,
+        zip: zip, address_country: address_country,
+        contact_first_name: contact_first_name,
+        contact_last_name: contact_last_name, contact_email: contact_email,
+        contact_phone: contact_phone, monthly_volume: monthly_volume,
+        use_case: use_case, use_case_summary: use_case_summary,
+        sample_messages: sample_messages, opt_in_workflow: opt_in_workflow,
+        privacy_url: privacy_url, terms_url: terms_url,
+        additional_information: additional_information,
+        age_gated_content: age_gated_content
+      )
+
+      @client.post("/verification/preflight", body)
+    end
+
+    # Get a "best-of" prefill across all the caller's verified workspaces.
+    # Returns most-recent non-empty values per messaging field. Use this
+    # to pre-populate the upgrade form for users whose current workspace
+    # has incomplete data.
+    #
+    # @return [Hash] +{ "prefill" => {...}, "sourceWorkspaceCount" => Integer }+
+    def best_prefill
+      @client.get("/verification/best-prefill")
+    end
+
+    # Start an entity upgrade for the given workspace. Auto-provisions
+    # a new toll-free number + messaging profile and submits to the
+    # carrier for review. Returns the pending verification details.
+    #
+    # The current toll-free number continues sending throughout the
+    # 1-2 week carrier review; on approval, an atomic swap promotes
+    # the new number.
+    #
+    # The EIN document (when supplied) is uploaded as multipart form-data
+    # under the +einDoc+ field. Provide either +ein_doc_path+ (a path on
+    # disk) or +ein_doc+ (raw bytes / IO) — not both.
+    #
+    # @param workspace_id [String]
+    # @param business_name [String]
+    # @param brn [String]
+    # @param brn_type [String] One of {BRN_TYPES}
+    # @param brn_country [String] ISO country code
+    # @param entity_type [String] One of {ENTITY_TYPES}
+    # @param ein_doc_path [String, nil] Path to the EIN/CP-575 PDF
+    # @param ein_doc [String, IO, nil] Raw EIN PDF bytes or IO
+    # @param ein_doc_filename [String, nil] Filename (defaults to "ein-doc.pdf")
+    # @param ein_doc_content_type [String, nil] MIME type (defaults to "application/pdf")
+    # @return [Hash] Upgrade start response
+    def start(workspace_id, business_name:, brn:, brn_type:, brn_country:,
+              entity_type:, doing_business_as: nil, website: nil,
+              address1: nil, address2: nil, city: nil, state: nil, zip: nil,
+              address_country: nil, contact_first_name: nil,
+              contact_last_name: nil, contact_email: nil, contact_phone: nil,
+              monthly_volume: nil, use_case: nil, use_case_summary: nil,
+              sample_messages: nil, opt_in_workflow: nil, privacy_url: nil,
+              terms_url: nil, additional_information: nil,
+              age_gated_content: nil, ein_doc_path: nil, ein_doc: nil,
+              ein_doc_filename: nil, ein_doc_content_type: nil)
+      raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
+
+      fields = build_upgrade_body(
+        business_name: business_name, brn: brn, brn_type: brn_type,
+        brn_country: brn_country, entity_type: entity_type,
+        doing_business_as: doing_business_as, website: website,
+        address1: address1, address2: address2, city: city, state: state,
+        zip: zip, address_country: address_country,
+        contact_first_name: contact_first_name,
+        contact_last_name: contact_last_name, contact_email: contact_email,
+        contact_phone: contact_phone, monthly_volume: monthly_volume,
+        use_case: use_case, use_case_summary: use_case_summary,
+        sample_messages: sample_messages, opt_in_workflow: opt_in_workflow,
+        privacy_url: privacy_url, terms_url: terms_url,
+        additional_information: additional_information,
+        age_gated_content: age_gated_content
+      )
+
+      post_multipart_with_fields(
+        "/workspaces/#{url_escape(workspace_id)}/upgrade",
+        fields,
+        ein_doc_path: ein_doc_path,
+        ein_doc: ein_doc,
+        ein_doc_filename: ein_doc_filename,
+        ein_doc_content_type: ein_doc_content_type
+      )
+    end
+
+    # Check whether the given workspace has a pending entity upgrade.
+    # Returns +{ "pending" => nil }+ when no upgrade is in flight.
+    #
+    # @param workspace_id [String]
+    # @return [Hash]
+    def status(workspace_id)
+      raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
+
+      @client.get("/workspaces/#{url_escape(workspace_id)}/upgrade/status")
+    end
+
+    # Cancel a pending entity upgrade for the given workspace. Releases
+    # the reserved toll-free number, deletes the new messaging profile,
+    # and removes the stored EIN document. Idempotent.
+    #
+    # @param workspace_id [String]
+    # @return [Hash]
+    def cancel(workspace_id)
+      raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
+
+      @client.post("/workspaces/#{url_escape(workspace_id)}/upgrade/cancel", {})
+    end
+
+    # Resubmit a rejected (or waiting-for-customer) entity upgrade with
+    # updated fields and optionally a new EIN document. All fields are
+    # optional — only the ones you pass are sent.
+    #
+    # @param workspace_id [String]
+    # @return [Hash]
+    def resubmit(workspace_id, business_name: nil, brn: nil, brn_type: nil,
+                 brn_country: nil, entity_type: nil, doing_business_as: nil,
+                 website: nil, address1: nil, address2: nil, city: nil,
+                 state: nil, zip: nil, address_country: nil,
+                 contact_first_name: nil, contact_last_name: nil,
+                 contact_email: nil, contact_phone: nil, monthly_volume: nil,
+                 use_case: nil, use_case_summary: nil, sample_messages: nil,
+                 opt_in_workflow: nil, privacy_url: nil, terms_url: nil,
+                 additional_information: nil, age_gated_content: nil,
+                 ein_doc_path: nil, ein_doc: nil, ein_doc_filename: nil,
+                 ein_doc_content_type: nil)
+      raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
+
+      fields = build_upgrade_body(
+        business_name: business_name, brn: brn, brn_type: brn_type,
+        brn_country: brn_country, entity_type: entity_type,
+        doing_business_as: doing_business_as, website: website,
+        address1: address1, address2: address2, city: city, state: state,
+        zip: zip, address_country: address_country,
+        contact_first_name: contact_first_name,
+        contact_last_name: contact_last_name, contact_email: contact_email,
+        contact_phone: contact_phone, monthly_volume: monthly_volume,
+        use_case: use_case, use_case_summary: use_case_summary,
+        sample_messages: sample_messages, opt_in_workflow: opt_in_workflow,
+        privacy_url: privacy_url, terms_url: terms_url,
+        additional_information: additional_information,
+        age_gated_content: age_gated_content
+      )
+
+      post_multipart_with_fields(
+        "/workspaces/#{url_escape(workspace_id)}/upgrade/resubmit",
+        fields,
+        ein_doc_path: ein_doc_path,
+        ein_doc: ein_doc,
+        ein_doc_filename: ein_doc_filename,
+        ein_doc_content_type: ein_doc_content_type
+      )
+    end
+
+    # After a successful entity-upgrade approval, choose what happens to
+    # the old toll-free number:
+    #
+    # - +"moved"+: keep it active under another workspace owned by the
+    #   same user (requires +target_workspace_id+)
+    # - +"released"+: return it to the carrier pool
+    #
+    # @param workspace_id [String]
+    # @param disposition [String] +"moved"+ or +"released"+
+    # @param target_workspace_id [String, nil] Required when +disposition+ is +"moved"+
+    # @return [Hash]
+    def set_disposition(workspace_id, disposition:, target_workspace_id: nil)
+      raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
+      unless DISPOSITIONS.include?(disposition)
+        raise ArgumentError, "disposition must be one of: #{DISPOSITIONS.join(", ")}"
+      end
+      if disposition == "moved" && (target_workspace_id.nil? || target_workspace_id.empty?)
+        raise ArgumentError, "target_workspace_id is required when disposition is 'moved'"
+      end
+
+      body = { disposition: disposition }
+      body[:targetOrgId] = target_workspace_id if target_workspace_id
+
+      @client.post("/workspaces/#{url_escape(workspace_id)}/upgrade/disposition", body)
+    end
+
+    private
+
+    def url_escape(value)
+      URI.encode_www_form_component(value)
+    end
+
+    def build_upgrade_body(business_name:, brn:, brn_type:, brn_country:,
+                           entity_type:, doing_business_as:, website:,
+                           address1:, address2:, city:, state:, zip:,
+                           address_country:, contact_first_name:,
+                           contact_last_name:, contact_email:, contact_phone:,
+                           monthly_volume:, use_case:, use_case_summary:,
+                           sample_messages:, opt_in_workflow:, privacy_url:,
+                           terms_url:, additional_information:,
+                           age_gated_content:)
+      body = {}
+      body[:businessName] = business_name unless business_name.nil?
+      body[:brn] = brn unless brn.nil?
+      body[:brnType] = brn_type unless brn_type.nil?
+      body[:brnCountry] = brn_country unless brn_country.nil?
+      body[:entityType] = entity_type unless entity_type.nil?
+      body[:doingBusinessAs] = doing_business_as unless doing_business_as.nil?
+      body[:website] = website unless website.nil?
+      body[:address1] = address1 unless address1.nil?
+      body[:address2] = address2 unless address2.nil?
+      body[:city] = city unless city.nil?
+      body[:state] = state unless state.nil?
+      body[:zip] = zip unless zip.nil?
+      body[:addressCountry] = address_country unless address_country.nil?
+      body[:contactFirstName] = contact_first_name unless contact_first_name.nil?
+      body[:contactLastName] = contact_last_name unless contact_last_name.nil?
+      body[:contactEmail] = contact_email unless contact_email.nil?
+      body[:contactPhone] = contact_phone unless contact_phone.nil?
+      body[:monthlyVolume] = monthly_volume unless monthly_volume.nil?
+      body[:useCase] = use_case unless use_case.nil?
+      body[:useCaseSummary] = use_case_summary unless use_case_summary.nil?
+      body[:sampleMessages] = sample_messages unless sample_messages.nil?
+      body[:optInWorkflow] = opt_in_workflow unless opt_in_workflow.nil?
+      body[:privacyUrl] = privacy_url unless privacy_url.nil?
+      body[:termsUrl] = terms_url unless terms_url.nil?
+      body[:additionalInformation] = additional_information unless additional_information.nil?
+      body[:ageGatedContent] = age_gated_content unless age_gated_content.nil?
+      body
+    end
+
+    # POST a multipart/form-data request with the given fields plus an
+    # optional +einDoc+ file part. Mirrors the JSON-vs-multipart flexibility
+    # the server expects: if no EIN doc is supplied and there are no fields,
+    # we still send an empty multipart body (the server is configured for
+    # +multer+ on these routes).
+    def post_multipart_with_fields(path, fields, ein_doc_path:, ein_doc:,
+                                   ein_doc_filename:, ein_doc_content_type:)
+      if !ein_doc_path.nil? && !ein_doc.nil?
+        raise ArgumentError, "Provide ein_doc_path OR ein_doc, not both"
+      end
+
+      file_bytes = nil
+      filename = ein_doc_filename || "ein-doc.pdf"
+      content_type = ein_doc_content_type || "application/pdf"
+
+      if ein_doc_path
+        raise ArgumentError, "File not found: #{ein_doc_path}" unless File.exist?(ein_doc_path)
+        file_bytes = File.binread(ein_doc_path)
+        filename = ein_doc_filename || File.basename(ein_doc_path)
+      elsif ein_doc
+        file_bytes = ein_doc.is_a?(String) ? ein_doc : ein_doc.read
+      end
+
+      boundary = "SendlyRuby#{SecureRandom.hex(16)}"
+      body_parts = []
+
+      fields.each do |k, v|
+        next if v.nil?
+        body_parts << "--#{boundary}\r\n"
+        body_parts << "Content-Disposition: form-data; name=\"#{k}\"\r\n\r\n"
+        body_parts << (v == true || v == false ? v.to_s : v.to_s)
+        body_parts << "\r\n"
+      end
+
+      if file_bytes
+        body_parts << "--#{boundary}\r\n"
+        body_parts << "Content-Disposition: form-data; name=\"einDoc\"; filename=\"#{filename}\"\r\n"
+        body_parts << "Content-Type: #{content_type}\r\n\r\n"
+        body_parts << file_bytes
+        body_parts << "\r\n"
+      end
+
+      body_parts << "--#{boundary}--\r\n"
+
+      uri = URI.parse("#{@client.base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 10
+      http.read_timeout = @client.timeout
+
+      req = Net::HTTP::Post.new(uri)
+      req["Authorization"] = "Bearer #{@client.api_key}"
+      req["Accept"] = "application/json"
+      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
+      req.body = body_parts.join
+
+      begin
+        response = http.request(req)
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise Sendly::TimeoutError, "Request timed out after #{@client.timeout} seconds"
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError => e
+        raise Sendly::NetworkError, "Connection failed: #{e.message}"
+      end
+
+      status = response.code.to_i
+      body = response.body.nil? || response.body.empty? ? {} : (JSON.parse(response.body) rescue { "message" => response.body })
+
+      return body if status >= 200 && status < 300
+
+      raise Sendly::ErrorFactory.from_response(status, body)
+    end
+  end
+end

data/lib/sendly/client.rb

@@ -150,6 +150,20 @@ module Sendly
       @enterprise ||= EnterpriseResource.new(self)
     end
 
+    # Access the Business Upgrade resource (entity-upgrade flow)
+    #
+    # @return [Sendly::BusinessUpgradeResource]
+    def business_upgrade
+      @business_upgrade ||= BusinessUpgradeResource.new(self)
+    end
+
+    # Access the Numbers resource
+    #
+    # @return [Sendly::NumbersResource]
+    def numbers
+      @numbers ||= NumbersResource.new(self)
+    end
+
     # Make a GET request
     #
     # @param path [String] API path

data/lib/sendly/conversations_resource.rb

@@ -107,6 +107,14 @@ module Sendly
       ConversationContext.new(response)
     end
 
+    def suggest_replies(id)
+      raise ValidationError, "Conversation ID is required" if id.nil? || id.empty?
+
+      encoded_id = URI.encode_www_form_component(id)
+      response = @client.post("/conversations/#{encoded_id}/suggest-replies")
+      SuggestRepliesResponse.new(response)
+    end
+
     def each(status: nil, batch_size: 100, &block)
       return enum_for(:each, status: status, batch_size: batch_size) unless block_given?
 

data/lib/sendly/numbers_resource.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module Sendly
+  # A country in which numbers can be searched and purchased, along with the
+  # number types available there (e.g. "mobile", "local", "toll_free").
+  class NumberCountry
+    attr_reader :code, :name, :number_types
+
+    def initialize(data)
+      @code = data["code"]
+      @name = data["name"]
+      @number_types = data["numberTypes"] || data["number_types"] || []
+    end
+
+    def to_h
+      { code: code, name: name, number_types: number_types }.compact
+    end
+  end
+
+  # A number that is available to purchase. The monthly cost is already
+  # customer-priced and returned as a string in the given currency.
+  class AvailableNumber
+    attr_reader :phone_number, :country, :number_type, :monthly_cost, :currency
+
+    def initialize(data)
+      @phone_number = data["phoneNumber"] || data["phone_number"]
+      @country = data["country"]
+      @number_type = data["numberType"] || data["number_type"]
+      @monthly_cost = data["monthlyCost"] || data["monthly_cost"]
+      @currency = data["currency"]
+    end
+
+    def to_h
+      {
+        phone_number: phone_number, country: country,
+        number_type: number_type, monthly_cost: monthly_cost,
+        currency: currency
+      }.compact
+    end
+  end
+
+  # A number owned by the account.
+  class PhoneNumber
+    attr_reader :id, :phone_number, :status, :source, :country_code,
+                :phone_number_type, :monthly_cost_cents
+
+    def initialize(data)
+      @id = data["id"]
+      @phone_number = data["phoneNumber"] || data["phone_number"]
+      @status = data["status"]
+      @source = data["source"]
+      @country_code = data["countryCode"] || data["country_code"]
+      @phone_number_type = data["phoneNumberType"] || data["phone_number_type"]
+      @monthly_cost_cents = data["monthlyCostCents"] || data["monthly_cost_cents"]
+    end
+
+    def to_h
+      {
+        id: id, phone_number: phone_number, status: status, source: source,
+        country_code: country_code, phone_number_type: phone_number_type,
+        monthly_cost_cents: monthly_cost_cents
+      }.compact
+    end
+  end
+
+  # The result of a buy request. The API responds 202 with one of three
+  # statuses:
+  #
+  # - +"provisioning"+: the purchase succeeded and the number is being
+  #   provisioned. +number+ carries the new {PhoneNumber}.
+  # - +"documents_required"+ / +"payment_required"+: the purchase is paused
+  #   pending a hosted Sendly step. +action+ carries the hand-off object,
+  #   which holds TWO distinct identifiers:
+  #   - +actionCode+ — a 32-hex action identifier (read via {#action_identifier}).
+  #     Use THIS to poll the action and to re-call +buy+ (pass it as the
+  #     +action_code:+ argument).
+  #   - +code+ — a short user code (read via {#action_code}). DISPLAY ONLY:
+  #     show it to the human to type on the hosted page to prove terminal
+  #     access. Never pass it back as +action_code:+.
+  #   Hand the user +action_url+ + {#action_code}, wait for completion, then
+  #   re-call +buy+ with the same body plus +action_code:+ set to
+  #   {#action_identifier}. +requirements+ describes what's missing (a JSON
+  #   array).
+  #
+  # The raw parsed response is preserved verbatim on +#raw+ so callers can
+  # read any field the server adds.
+  class NumberPurchase
+    attr_reader :status, :number, :requirements, :action, :raw
+
+    def initialize(data)
+      @raw = data
+      @status = data["status"]
+      @number = data["number"] ? PhoneNumber.new(data["number"]) : nil
+      @requirements = data["requirements"]
+      @action = data["action"]
+    end
+
+    def provisioning?
+      status == "provisioning"
+    end
+
+    def documents_required?
+      status == "documents_required"
+    end
+
+    def payment_required?
+      status == "payment_required"
+    end
+
+    # @return [String, nil] The hosted Sendly page URL the user must visit.
+    def action_url
+      action && (action["url"] || action[:url])
+    end
+
+    # The 32-hex action identifier. Use THIS to poll the action's status and
+    # to re-call +buy+ (pass it as the +action_code:+ argument). NOT for
+    # display.
+    #
+    # @return [String, nil]
+    def action_identifier
+      action && (action["actionCode"] || action["action_code"] || action[:actionCode] || action[:action_code])
+    end
+
+    # The short user code shown to the human to type on the hosted page to
+    # prove terminal access. DISPLAY ONLY — to re-buy/poll, use
+    # {#action_identifier}, not this.
+    #
+    # @return [String, nil]
+    def action_code
+      action && (action["code"] || action[:code])
+    end
+
+    # Expiry of the action, as an epoch-milliseconds number (the server sends
+    # a number, not an ISO-8601 string). Older payloads may carry it under
+    # +expires_at+; both are accepted.
+    #
+    # @return [Integer, String, nil]
+    def action_expires_at
+      action && (action["expiresAt"] || action["expires_at"] || action[:expiresAt] || action[:expires_at])
+    end
+
+    def to_h
+      {
+        status: status, number: number&.to_h,
+        requirements: requirements, action: action
+      }.compact
+    end
+  end
+
+  # Numbers resource — search, list, and purchase phone numbers.
+  #
+  # @example List supported countries
+  #   result = client.numbers.list_countries
+  #   result[:countries].each { |c| puts "#{c.code} #{c.name}" }
+  #
+  # @example Find available mobile numbers in the UK
+  #   result = client.numbers.list_available(country: "GB", type: "mobile")
+  #   number = result[:numbers].first
+  #
+  # @example Buy a number (may pause for a hosted step)
+  #   purchase = client.numbers.buy(
+  #     phone_number: number.phone_number,
+  #     country_code: number.country,
+  #     phone_number_type: number.number_type,
+  #     monthly_cost: number.monthly_cost
+  #   )
+  #   if purchase.documents_required? || purchase.payment_required?
+  #     # Show the user the URL + display code; keep the 32-hex identifier for re-buy
+  #     puts "Visit #{purchase.action_url} and enter code #{purchase.action_code}"
+  #     # ...once they finish, re-call buy with action_code: purchase.action_identifier
+  #   end
+  class NumbersResource
+    def initialize(client)
+      @client = client
+    end
+
+    # List the countries in which numbers can be searched and purchased,
+    # along with the number types available in each.
+    #
+    # @return [Hash] +{ countries: Array<NumberCountry> }+
+    def list_countries
+      response = @client.get("/numbers/countries")
+      countries = (response["countries"] || []).map { |c| NumberCountry.new(c) }
+      { countries: countries }
+    end
+
+    # Search for numbers available to purchase in a country.
+    #
+    # @param country [String] ISO country code (e.g. "GB")
+    # @param type [String] Number type (e.g. "mobile", "local", "toll_free")
+    # @param contains [String, nil] Optional digit/letter filter
+    # @return [Hash] +{ numbers: Array<AvailableNumber> }+
+    def list_available(country:, type:, contains: nil)
+      raise ValidationError, "country is required" if country.nil? || country.to_s.empty?
+      raise ValidationError, "type is required" if type.nil? || type.to_s.empty?
+
+      params = { country: country, type: type }
+      params[:contains] = contains if contains
+
+      response = @client.get("/numbers/available", params)
+      numbers = (response["numbers"] || []).map { |n| AvailableNumber.new(n) }
+      { numbers: numbers }
+    end
+
+    # List the numbers owned by the account.
+    #
+    # @return [Hash] +{ numbers: Array<PhoneNumber> }+
+    def list
+      response = @client.get("/numbers")
+      numbers = (response["numbers"] || []).map { |n| PhoneNumber.new(n) }
+      { numbers: numbers }
+    end
+
+    # Buy a number.
+    #
+    # Returns a {NumberPurchase}. When its status is +documents_required+ or
+    # +payment_required+, hand the user +purchase.action_url+ +
+    # +purchase.action_code+ (the short display code), wait for that hosted
+    # step to complete, then re-call +buy+ with the SAME arguments plus
+    # +action_code:+ set to +purchase.action_identifier+ (the 32-hex action
+    # identifier) — NOT the display code.
+    #
+    # @param phone_number [String]
+    # @param country_code [String]
+    # @param phone_number_type [String]
+    # @param monthly_cost [String] Customer-priced monthly cost (as returned by {#list_available})
+    # @param action_code [String, nil] The 32-hex action identifier of a
+    #   completed hosted action (see {NumberPurchase#action_identifier}), on re-call
+    # @return [NumberPurchase]
+    def buy(phone_number:, country_code:, phone_number_type:, monthly_cost:, action_code: nil)
+      raise ValidationError, "phone_number is required" if phone_number.nil? || phone_number.to_s.empty?
+      raise ValidationError, "country_code is required" if country_code.nil? || country_code.to_s.empty?
+      raise ValidationError, "phone_number_type is required" if phone_number_type.nil? || phone_number_type.to_s.empty?
+      raise ValidationError, "monthly_cost is required" if monthly_cost.nil? || monthly_cost.to_s.empty?
+
+      body = {
+        phoneNumber: phone_number,
+        countryCode: country_code,
+        phoneNumberType: phone_number_type,
+        monthlyCost: monthly_cost
+      }
+      body[:actionCode] = action_code if action_code
+
+      response = @client.post("/numbers/buy", body)
+      NumberPurchase.new(response)
+    end
+  end
+end

data/lib/sendly/types.rb

@@ -596,6 +596,75 @@ module Sendly
     end
   end
 
+  # ============================================================================
+  # Suggested Replies
+  # ============================================================================
+
+  class SuggestedReply
+    # @return [String] Suggested reply text
+    attr_reader :text
+
+    # @return [String] Tone of the suggestion (professional, friendly, concise)
+    attr_reader :tone
+
+    TONES = %w[professional friendly concise].freeze
+
+    def initialize(data)
+      @text = data["text"]
+      @tone = data["tone"]
+    end
+
+    def to_h
+      { text: text, tone: tone }.compact
+    end
+  end
+
+  class SuggestRepliesResponse
+    include Enumerable
+
+    # @return [Array<SuggestedReply>] AI-generated reply suggestions
+    attr_reader :suggestions
+
+    # @return [String, nil] ID of the inbound message the suggestions are based on
+    attr_reader :based_on_message_id
+
+    # @return [String, nil] Model that generated the suggestions
+    attr_reader :model
+
+    def initialize(data)
+      @suggestions = (data["suggestions"] || []).map { |s| SuggestedReply.new(s) }
+      @based_on_message_id = data["basedOnMessageId"] || data["based_on_message_id"]
+      @model = data["model"]
+    end
+
+    def each(&block)
+      suggestions.each(&block)
+    end
+
+    def count
+      suggestions.length
+    end
+
+    alias size count
+    alias length count
+
+    def empty?
+      suggestions.empty?
+    end
+
+    def first
+      suggestions.first
+    end
+
+    def to_h
+      {
+        suggestions: suggestions.map(&:to_h),
+        based_on_message_id: based_on_message_id,
+        model: model
+      }.compact
+    end
+  end
+
   # ============================================================================
   # Labels
   # ============================================================================

data/lib/sendly/version.rb

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

data/lib/sendly.rb

@@ -21,6 +21,8 @@ require_relative "sendly/labels_resource"
 require_relative "sendly/drafts_resource"
 require_relative "sendly/rules_resource"
 require_relative "sendly/enterprise"
+require_relative "sendly/business_upgrade_resource"
+require_relative "sendly/numbers_resource"
 
 # Sendly Ruby SDK
 #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendly
 version: !ruby/object:Gem::Version
-  version: 3.31.0
+  version: 3.34.0
 platform: ruby
 authors:
 - Sendly
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-05-16 00:00:00.000000000 Z
+date: 2026-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -125,6 +125,7 @@ files:
 - examples/send_sms.rb
 - lib/sendly.rb
 - lib/sendly/account_resource.rb
+- lib/sendly/business_upgrade_resource.rb
 - lib/sendly/campaigns_resource.rb
 - lib/sendly/client.rb
 - lib/sendly/contacts_resource.rb
@@ -135,6 +136,7 @@ files:
 - lib/sendly/labels_resource.rb
 - lib/sendly/media.rb
 - lib/sendly/messages.rb
+- lib/sendly/numbers_resource.rb
 - lib/sendly/rules_resource.rb
 - lib/sendly/templates_resource.rb
 - lib/sendly/types.rb