voicetel 2.2.10 → 2.2.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c70dc67d349736fd88fd576459960103bcb4afbc7e9bb1512eb80569a7ad020
-  data.tar.gz: 6b3cb14e263751cb26e572d73cb511920af75047f84a9f4b2bb6f5bcef72550e
+  metadata.gz: cd5f5ccd7a80002a64926f5f66347782ab00b632e69d2f95edd362f0c92b6b92
+  data.tar.gz: '096b5af3dad422f37189da7840bd343278ea2c2302a9a353b0d9a83f03b71709'
 SHA512:
-  metadata.gz: 011706d8c9b695a96e2ad2e8b9594f6916b268565c81ffaf2b598bd5ce3e009c4205594e525bb8fe5501b169dd1679e4934bde97a2d1fb490ec948037c2c5578
-  data.tar.gz: a1349e176f37078243b4a295ea9180c031707e529ad8f109eb3a08567526d3d0817fde73efd4fd4da65c6c4629a118b7fa38e1e80c4e9857992767233a666278
+  metadata.gz: '088e89700e06dad3a4be905b29b7588cd70db76d574fbc25be78ec764f7873bdfe87d15edc07a028579b8aa978e704c711d795faab285375f749cfb33bcfb3e0'
+  data.tar.gz: e1439a7218f43a85bb60bcab70f3d7ff191a4af727336412cb7a6e440a0a2a4738efb717cbaf2a0cae35f8d751d360aa9252d2d26ca023b016daa4ba647ba829

data/README.md

@@ -2,8 +2,8 @@
 
 The official Ruby client for the [VoiceTel REST API](https://voicetel.com/docs/api/v2.2/) — provision numbers, place orders, validate e911, send messages, and manage your account, all with idiomatic Ruby, structured errors, and zero codegen footprint.
 
-![Version](https://img.shields.io/badge/version-2.2.10-blue)
-![Ruby](https://img.shields.io/badge/ruby-3.1%2B-red)
+![Version](https://img.shields.io/badge/version-2.2.14-blue)
+![Ruby](https://img.shields.io/badge/ruby-3.2%2B-red)
 ![License](https://img.shields.io/badge/license-MIT-green)
 ![Coverage](https://img.shields.io/badge/coverage-%E2%89%A585%25-brightgreen)
 ![Gem](https://img.shields.io/badge/gem-voicetel-blue)
@@ -28,6 +28,7 @@ The official Ruby client for the [VoiceTel REST API](https://voicetel.com/docs/a
 ### 🧱 Idiomatic Ruby End-to-End
 - **Resource-style API** — `client.numbers.list`, `client.messaging.send_message(...)`, just like the official SDKs in every other language.
 - **snake_case everywhere**, automatically camelCased on the wire so the spec's `fromNumber` / `toNumber` / `messagingBrandId` look like plain Ruby.
+- **Typed Data models** — every response is an immutable `Data.define` object (`VoiceTel::Models::...`) with snake_case readers; unknown server fields are ignored, so the API can grow without breaking you.
 - **RBS signatures** ship in `sig/` — opt into type-checking with Steep or Sorbet, or ignore them and stay dynamic.
 
 ### 🔁 Production-Grade Transport
@@ -63,10 +64,10 @@ gem install voicetel
 Or in your `Gemfile`:
 
 ```ruby
-gem "voicetel", "~> 2.2.10"
+gem "voicetel", "~> 2.2.14"
 ```
 
-Requires Ruby 3.1 or later. Tested on 3.1, 3.2, 3.3, and 3.4.
+Requires Ruby 3.2 or later. Tested on 3.2, 3.3, and 3.4.
 
 ## 🏁 Quickstart
 
@@ -79,11 +80,11 @@ client = VoiceTel::Client.new
 client.login(username: 1_000_000_001, password: "hunter2")
 
 me = client.account.get
-puts "Balance: $#{me['cash']}  |  Caller ID: #{me['callerId']}"
+puts "Balance: $#{me.cash}  |  Caller ID: #{me.caller_id}"
 
 # List your numbers
-client.numbers.list["numbers"].each do |n|
-  puts "#{n['number']}  route=#{n['route']}  cnam=#{n['cnam']}  sms=#{n['smsEnabled']}"
+client.numbers.list.numbers.each do |n|
+  puts "#{n.number}  route=#{n.route}  cnam=#{n.cnam}  sms=#{n.sms_enabled}"
 end
 ```
 
@@ -93,8 +94,8 @@ Or, if you already have an API key:
 client = VoiceTel::Client.new(api_key: ENV.fetch("VOICETEL_API_KEY"))
 
 coverage = client.i_numbering.coverage(state: "NJ")
-coverage["coverage"].each do |bucket|
-  puts "#{bucket['npa']}-#{bucket['nxx']}: #{bucket['count']} TNs available"
+coverage.coverage.each do |bucket|
+  puts "#{bucket.npa}-#{bucket.nxx}: #{bucket.count} TNs available"
 end
 ```
 
@@ -141,7 +142,7 @@ client.numbers.assign_campaign("2015551234", campaign_id: "CABC123")
 # → PUT /v2.2/numbers/2015551234/messaging-campaign { "campaignId": "CABC123" }
 ```
 
-Responses come back as Hash/Array structures with the API's native (camelCase) keys — easy to pass straight to `to_json` or pretty-print.
+Responses come back as immutable `Data` model classes (`VoiceTel::Models::...`) with `snake_case` readers — `assign_campaign` returns a `Models::NumberMessagingCampaignAssignData` whose `status` is `"enabled"` (bound now, path B), `"already"` (was already bound — idempotent), or `"pending"` (path C, provisioning asynchronously — poll `client.numbers.get_messaging(n).pending` until its `state` is `"done"` or `"failed"`). Any model converts to a plain Hash with `#to_h` when you need to serialize or pretty-print it.
 
 ## 🚨 Error Handling
 
@@ -171,7 +172,7 @@ rescue VoiceTel::ApiError => e
 end
 ```
 
-`ApiError#body` preserves the parsed response payload — useful on 409 ACL conflicts, where the server returns structured `{added, removed, failed}` detail.
+`ApiError#body` preserves the parsed response payload — useful on 409 ACL conflicts, where the server returns structured `{added, removed, failed}` detail (build a `Models::AclConflictData` from it to read the rows).
 
 ## ⏱️ Rate Limits
 

data/lib/voicetel/internal/transport.rb

@@ -64,8 +64,8 @@ module VoiceTel
       end
 
       # Recursively transform a Ruby snake_case key Hash/Array structure into
-      # a Hash with camelCase keys, suitable for JSON serialization. Values
-      # that are already strings/numbers/bools/nil/symbols pass through.
+      # a Hash with camelCase keys, suitable for JSON serialization. Data.define
+      # request models are converted to hashes; plain scalars pass through.
       def camelize_keys(obj)
         case obj
         when Hash
@@ -74,6 +74,8 @@ module VoiceTel
           end
         when Array
           obj.map { |v| camelize_keys(v) }
+        when Data
+          camelize_keys(obj.to_h)
         else
           obj
         end

data/lib/voicetel/models/account.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VoiceTel
+  module Models
+    # --------------------------------------------------------- shared subtypes ---
+    # Per-service rates on an account. Read-only for non-administrators.
+    AccountRates = Data.define(
+      :cnam, :intl_max, :nibble, :lrn, :fax, :tf_adj, :did, :mms, :sms
+    ) do
+      extend Base
+    end
+
+    # Per-service feature flags on an account; true = enabled.
+    AccountServices = Data.define(
+      :e911, :cnam, :bypass_media, :intl, :mms, :dialer, :sms
+    ) do
+      extend Base
+    end
+
+    # A single credit row in AccountCreditsData.
+    CreditEntry = Data.define(:date, :paid, :amount) do
+      extend Base
+    end
+
+    # A single payment row in AccountPaymentsData. status is one of
+    # "Completed", "Pending", "Reversed", "Refunded", "Failed", "Denied",
+    # or "Canceled_Reversal".
+    PaymentEntry = Data.define(:transaction_id, :date, :payer_email, :status, :amount) do
+      extend Base
+    end
+
+    # Per-call billing summary inside a CdrEntry. The numeric-looking fields
+    # (dur, ba, nr) are intentionally strings to preserve exact precision on
+    # the wire.
+    CdrEntryValue = Data.define(:dur, :dst, :ba, :nr, :cn, :ip, :cid) do
+      extend Base
+    end
+
+    # A single CDR row. key is [accountUsername, startEpochUnixSeconds].
+    CdrEntry = Data.define(:id, :key, :value) do
+      extend Base
+
+      def self.nested
+        { value: CdrEntryValue }
+      end
+    end
+
+    # A single monthly-recurring charge row in AccountMrcData.
+    MrcCharge = Data.define(:amount, :description) do
+      extend Base
+    end
+
+    # ------------------------------------------------------------- requests ---
+    # Body for POST /v2.2/account — admin-only sub-account creation.
+    AccountAddRequest = Data.define(:username, :name, :email, :master_account) do
+      include Request
+    end
+
+    # Body for PUT /v2.2/account — partial account-settings update.
+    AccountPutRequest = Data.define(
+      :notify, :notify_threshold, :timezone, :caller_id, :e911, :intl, :sms, :mms, :ccs
+    ) do
+      include Request
+    end
+
+    # Body for POST /v2.2/accounts — public sign-up.
+    AccountSignupRequest = Data.define(:name, :email, :promo) do
+      include Request
+    end
+
+    # Body for POST /v2.2/account/recovery — password recovery (no auth).
+    AccountRecoverRequest = Data.define(:email) do
+      include Request
+    end
+
+    # Body for POST /v2.2/account/api-key — username/password -> bearer.
+    ApiKeyRequest = Data.define(:username, :password) do
+      include Request
+    end
+
+    # ------------------------------------------------------ response data ---
+    # Data payload from POST /v2.2/account (admin create).
+    AccountAddData = Data.define(:password, :email, :master_account, :username, :name) do
+      extend Base
+    end
+
+    # Data payload from POST /v2.2/account/api-key.
+    AccountApiKeyData = Data.define(:apikey) do
+      extend Base
+    end
+
+    # Data payload from GET /v2.2/account/cdr.
+    AccountCdrData = Data.define(:cdr, :start, :end_at) do
+      extend Base
+
+      def self.nested
+        { cdr: CdrEntry }
+      end
+
+      def self.wire_keys
+        { end_at: "end" }
+      end
+    end
+
+    # Data payload from GET /v2.2/account/credits.
+    AccountCreditsData = Data.define(:credits) do
+      extend Base
+
+      def self.nested
+        { credits: CreditEntry }
+      end
+    end
+
+    # Data payload from GET /v2.2/account — the authenticated account's
+    # profile.
+    AccountData = Data.define(
+      :username, :name, :email, :enabled, :created, :cash, :caller_id, :timezone,
+      :auth_type, :ccs, :notify, :notify_threshold, :rates, :services
+    ) do
+      extend Base
+
+      def self.nested
+        { rates: AccountRates, services: AccountServices }
+      end
+    end
+
+    # Data payload from GET /v2.2/account/recurring-charges.
+    AccountMrcData = Data.define(:charges, :total) do
+      extend Base
+
+      def self.nested
+        { charges: MrcCharge }
+      end
+    end
+
+    # Data payload from GET /v2.2/account/payments.
+    AccountPaymentsData = Data.define(:payments) do
+      extend Base
+
+      def self.nested
+        { payments: PaymentEntry }
+      end
+    end
+
+    # Data payload from PUT /v2.2/account.
+    AccountPutData = Data.define(:updated) do
+      extend Base
+    end
+
+    # Data payload from POST /v2.2/account/recovery.
+    AccountRecoverData = Data.define(:message) do
+      extend Base
+    end
+
+    # Data payload from GET /v2.2/account/registration — current SIP
+    # registration.
+    AccountRegistrationData = Data.define(:agent, :uri, :expires) do
+      extend Base
+    end
+
+    # Data payload from POST /v2.2/accounts (public sign-up).
+    AccountSignupData = Data.define(:username, :name, :email, :password) do
+      extend Base
+    end
+  end
+end

data/lib/voicetel/models/acl.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "common"
+
+module VoiceTel
+  module Models
+    # ------------------------------------------------------------- requests ---
+    # Body for POST /v2.2/acl (add) and DELETE /v2.2/acl (remove). Entries
+    # may be CidrEntry objects or plain { cidr: "..." } hashes.
+    AclModifyRequest = Data.define(:acl) do
+      include Request
+    end
+
+    # ------------------------------------------------------ response data ---
+    # Data payload from GET /v2.2/acl.
+    AclListData = Data.define(:acl) do
+      extend Base
+
+      def self.nested
+        { acl: CidrEntry }
+      end
+    end
+
+    # Data payload from POST /v2.2/acl.
+    AclAddData = Data.define(:added) do
+      extend Base
+
+      def self.nested
+        { added: CidrEntry }
+      end
+    end
+
+    # Data payload from DELETE /v2.2/acl.
+    AclRemoveData = Data.define(:removed) do
+      extend Base
+
+      def self.nested
+        { removed: CidrEntry }
+      end
+    end
+
+    # A CIDR that was rejected, with the reason. Appears in 409 bodies.
+    AclFailedEntry = Data.define(:cidr, :reason) do
+      extend Base
+    end
+
+    # Data payload included in a 409 response from POST/DELETE /v2.2/acl.
+    # Surfaces both the entries that succeeded and the ones that failed, so
+    # partial outcomes can be reconciled. Build one from ApiError#body.
+    AclConflictData = Data.define(:added, :removed, :failed) do
+      extend Base
+
+      def self.nested
+        { added: CidrEntry, removed: CidrEntry, failed: AclFailedEntry }
+      end
+    end
+  end
+end

data/lib/voicetel/models/authentication.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "common"
+
+module VoiceTel
+  module Models
+    # ------------------------------------------------------------- requests ---
+    # Body for PUT /v2.2/auth — update authentication mode and/or password.
+    # auth_type: 0=Digest, 1=Lax (Digest | IP), 2=IP, 3=Strict (Digest + IP).
+    AuthPutRequest = Data.define(:auth_type, :password) do
+      include Request
+    end
+
+    # ------------------------------------------------------ response data ---
+    # Data payload from GET /v2.2/auth.
+    AuthGetData = Data.define(:auth_type, :auth_type_description, :acl) do
+      extend Base
+
+      # auth_type — 0=Digest, 1=Lax (Digest | IP), 2=IP, 3=Strict (Digest + IP).
+      def self.nested
+        { acl: CidrEntry }
+      end
+    end
+
+    # One field's change record, returned by PUT /v2.2/auth. field is
+    # "authType" or "password"; value echoes the new setting when safe and
+    # is nil for password.
+    AuthUpdatedEntry = Data.define(:field, :value) do
+      extend Base
+    end
+
+    # Data payload from PUT /v2.2/auth.
+    AuthPutData = Data.define(:updated) do
+      extend Base
+
+      def self.nested
+        { updated: AuthUpdatedEntry }
+      end
+    end
+
+    # Data payload included in a 409 response from PUT /v2.2/auth — same
+    # shape as AuthPutData. Build one from ApiError#body.
+    AuthPutConflictData = Data.define(:updated) do
+      extend Base
+
+      def self.nested
+        { updated: AuthUpdatedEntry }
+      end
+    end
+  end
+end

data/lib/voicetel/models/base.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module VoiceTel
+  # Response and request models, one file per resource. Every model is a
+  # Data.define class whose members are snake_case mirrors of the spec's
+  # camelCase wire fields. Base (class-side) builds responses, Request
+  # (instance-side) renders requests.
+  module Models
+    # Class-side plumbing for response models. .build turns an unwrapped API
+    # payload (a String-keyed, camelCase Hash) into a model instance:
+    #
+    # - Wire keys are mapped onto members by camelCasing the member name
+    #   (campaign_id -> "campaignId"); .wire_keys overrides the exceptions
+    #   (ticket_number -> "number").
+    # - Members declared in .nested are built recursively; a declared member
+    #   accepts either a single object or a list of them on the wire.
+    # - Payload keys without a member are ignored, so the server can add
+    #   fields without breaking this SDK; members absent from the payload
+    #   are set to nil.
+    module Base
+      # Nested model classes by member — { job: MessagingEnablementJob }.
+      def nested
+        {}
+      end
+
+      # Wire-key overrides for members whose spec name is not the camelCase
+      # form of the member — { ticket_number: "number" }.
+      def wire_keys
+        {}
+      end
+
+      # Build a model from an unwrapped payload. nil builds to nil (204
+      # responses) and non-Hash payloads pass through untouched.
+      def build(payload)
+        return nil if payload.nil?
+        return payload unless payload.is_a?(Hash)
+
+        kwargs = {}
+        members.each do |member|
+          key = wire_keys.fetch(member) { Models.wire_key(member) }
+          value = payload.key?(key) ? convert(payload[key], nested[member]) : nil
+          kwargs[member] = value
+        end
+        new(**kwargs)
+      end
+
+      private
+
+      def convert(value, type)
+        return value if type.nil? || value.nil?
+
+        if value.is_a?(Array)
+          value.map { |item| item.is_a?(Hash) ? type.build(item) : item }
+        else
+          type.build(value)
+        end
+      end
+    end
+
+    # Instance-side plumbing for request models. #to_payload renders the
+    # model as a plain snake_case Hash for the transport (which camelCases
+    # the keys on the wire); nil members are omitted so PATCH/PUT bodies keep
+    # "field absent" and "explicit value" distinguishable. There are no
+    # defaults — pass nil for anything you don't want to send.
+    module Request
+      def to_payload
+        self.class.members.each_with_object({}) do |member, out|
+          value = public_send(member)
+          out[member] = Models.plain(value) unless value.nil?
+        end
+      end
+    end
+
+    module_function
+
+    # camelCase wire key for a snake_case member.
+    def wire_key(member)
+      s = member.to_s
+      return s unless s.include?("_")
+
+      head, *rest = s.split("_")
+      head + rest.map(&:capitalize).join
+    end
+
+    # Recursively render nested request models as plain Ruby structures.
+    def plain(value)
+      case value
+      when Hash then value.transform_values { |v| plain(v) }
+      when Array then value.map { |v| plain(v) }
+      else value.respond_to?(:to_payload) ? value.to_payload : value
+      end
+    end
+  end
+end

data/lib/voicetel/models/common.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VoiceTel
+  module Models
+    # A single CIDR row used by the ACL endpoints. Masks must be /8, /16,
+    # /24, or /32 and must describe a routable public address.
+    CidrEntry = Data.define(:cidr) do
+      extend Base
+    end
+
+    # Generic error body returned for non-2xx responses. The SDK raises
+    # ApiError rather than returning this; the model exists so callers can
+    # build one from ApiError#body when it carries a JSON payload.
+    ErrorResponse = Data.define(:status, :code, :message, :error, :details) do
+      extend Base
+    end
+  end
+end

data/lib/voicetel/models/e911.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VoiceTel
+  module Models
+    # Request bodies take a 10-digit TN in `dn`; responses return the
+    # 11-digit E.164 US form (leading 1). This mirrors the spec exactly.
+
+    # ------------------------------------------------------------- requests ---
+    # Body for POST /v2.2/e911/validations — validate an address.
+    E911AddressRequest = Data.define(:address1, :address2, :city, :state, :zip) do
+      include Request
+    end
+
+    # Body for POST /v2.2/e911 — validate and provision in one call.
+    E911CreateRequest = Data.define(
+      :dn, :callername, :address1, :address2, :city, :state, :zip
+    ) do
+      include Request
+    end
+
+    # Body for PUT /v2.2/e911/{dn} — provision using a previously-validated
+    # addressid from POST /v2.2/e911/validations.
+    E911ProvisionByIdRequest = Data.define(:callername, :addressid) do
+      include Request
+    end
+
+    # ---------------------------------------------------- entities & data ---
+    # An e911 record bound to a TN. Returned by GET/POST/PUT /v2.2/e911(/{dn}).
+    E911Entry = Data.define(
+      :dn, :callername, :address1, :address2, :city, :state, :zip
+    ) do
+      extend Base
+    end
+
+    # Validation result from POST /v2.2/e911/validations. addressid is
+    # passed to E911ProvisionByIdRequest to provision the address.
+    E911ValidatedAddress = Data.define(
+      :addressid, :address1, :address2, :city, :state, :zip
+    ) do
+      extend Base
+    end
+
+    # Data payload from GET /v2.2/e911.
+    E911AllData = Data.define(:records) do
+      extend Base
+
+      def self.nested
+        { records: E911Entry }
+      end
+    end
+
+    # Data payload from GET/POST/PUT /v2.2/e911/{dn}.
+    E911RecordData = Data.define(:record) do
+      extend Base
+
+      def self.nested
+        { record: E911Entry }
+      end
+    end
+
+    # Data payload from POST /v2.2/e911/validations.
+    E911ValidateData = Data.define(:address) do
+      extend Base
+
+      def self.nested
+        { address: E911ValidatedAddress }
+      end
+    end
+  end
+end

data/lib/voicetel/models/gateways.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VoiceTel
+  module Models
+    # ------------------------------------------------------------- requests ---
+    # Body for POST /v2.2/gateways.
+    GatewayAddRequest = Data.define(:gateway, :prefix, :limit) do
+      include Request
+    end
+
+    # Body for PUT /v2.2/gateways/{id}.
+    GatewayUpdateRequest = Data.define(:gateway, :prefix, :limit) do
+      include Request
+    end
+
+    # -------------------------------------------------- entities & data ---
+    # A single gateway row. gateway holds an IP:port for customer gateways
+    # or a system route name (USER, T30, VOICEML, DID, T38, RTC_BRIDGE, SDN)
+    # for built-in routes; limit is nil on system routes.
+    GatewayEntry = Data.define(:id, :gateway, :prefix, :limit, :system) do
+      extend Base
+    end
+
+    # One number bound to a gateway, as returned by
+    # GET /v2.2/gateways/{id}/numbers.
+    GatewayNumberSummary = Data.define(
+      :number, :translated, :forward, :forward_to, :cnam, :carrier, :sms_enabled, :fax_enabled
+    ) do
+      extend Base
+    end
+
+    # Data payload from GET /v2.2/gateways.
+    GatewaysListData = Data.define(:gateways) do
+      extend Base
+
+      def self.nested
+        { gateways: GatewayEntry }
+      end
+    end
+
+    # Data payload from GET /v2.2/gateways/{id}/numbers.
+    GatewayNumbersData = Data.define(:numbers) do
+      extend Base
+
+      def self.nested
+        { numbers: GatewayNumberSummary }
+      end
+    end
+  end
+end