voicetel 2.2.10

data/lib/voicetel/resources/gateways.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VoiceTel
+  module Resources
+    # GatewaysService — outbound termination gateways on the account.
+    class Gateways < Base
+      def list
+        @transport.request(:get, "/v2.2/gateways")
+      end
+
+      def add(body)
+        @transport.request(:post, "/v2.2/gateways", body: body)
+      end
+
+      def get(id)
+        @transport.request(:get, "/v2.2/gateways/#{id}")
+      end
+
+      def update(id, body)
+        @transport.request(:put, "/v2.2/gateways/#{id}", body: body)
+      end
+
+      # Returns nil on 204 No Content.
+      def remove(id)
+        @transport.request(:delete, "/v2.2/gateways/#{id}")
+      end
+
+      def numbers(id)
+        @transport.request(:get, "/v2.2/gateways/#{id}/numbers")
+      end
+    end
+  end
+end

data/lib/voicetel/resources/i_numbering.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VoiceTel
+  module Resources
+    # INumberingService — inventory searches, orders, and port-ins.
+    #
+    # PortAvailability returns the v2.2.10 fields `local_routing_number` and
+    # `rate_center_tier` alongside `number`, `portable`, `losing_carrier`, `reason`.
+    class INumbering < Base
+      # GET /v2.2/inventory — search available TNs.
+      def search_inventory(npa: nil, nxx: nil, state: nil, ratecenter: nil, contains: nil, endswith: nil, limit: nil)
+        q = compact_query(
+          "npa" => npa, "nxx" => nxx, "state" => state, "ratecenter" => ratecenter,
+          "contains" => contains, "endswith" => endswith, "limit" => limit
+        )
+        @transport.request(:get, "/v2.2/inventory", query: q)
+      end
+
+      # GET /v2.2/inventory/coverage — aggregated availability buckets.
+      def coverage(state: nil, ratecenter: nil)
+        q = compact_query("state" => state, "ratecenter" => ratecenter)
+        @transport.request(:get, "/v2.2/inventory/coverage", query: q)
+      end
+
+      # POST /v2.2/orders — purchase new TNs.
+      def order(body)
+        @transport.request(:post, "/v2.2/orders", body: body)
+      end
+
+      # GET /v2.2/ports — list every port-in record.
+      def ports
+        @transport.request(:get, "/v2.2/ports")
+      end
+
+      # GET /v2.2/ports/{id} — detail for one port-in.
+      def port(id)
+        @transport.request(:get, "/v2.2/ports/#{id}")
+      end
+
+      # POST /v2.2/ports — submit a port-in.
+      def submit_port(body)
+        @transport.request(:post, "/v2.2/ports", body: body)
+      end
+
+      # GET /v2.2/ports/availability/{number} — check whether a TN can be ported in.
+      def port_availability(number)
+        @transport.request(:get, "/v2.2/ports/availability/#{number}")
+      end
+    end
+  end
+end

data/lib/voicetel/resources/lookups.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VoiceTel
+  module Resources
+    # LookupsService — CNAM and LRN dips.
+    #
+    # Each call costs money; meter accordingly.
+    class Lookups < Base
+      def cnam(number)
+        @transport.request(:get, "/v2.2/cnam/#{number}")
+      end
+
+      def lrn(number, ani)
+        @transport.request(:get, "/v2.2/lrn/#{number}/#{ani}")
+      end
+    end
+  end
+end

data/lib/voicetel/resources/messaging.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VoiceTel
+  module Resources
+    # MessagingService — SMS/MMS sending and 10DLC brand/campaign registration.
+    #
+    # The message-send wire body uses `fromNumber` / `toNumber`. Pass those
+    # snake_case in your Ruby hash (`from_number`, `to_number`) and the
+    # transport will translate them when serializing.
+    class Messaging < Base
+      # GET /v2.2/messages — fetch message history.
+      def history(number: nil, start: nil, end_at: nil, type: nil)
+        q = compact_query(
+          "number" => number,
+          "start" => start,
+          "end" => end_at,
+          "type" => type
+        )
+        @transport.request(:get, "/v2.2/messages", query: q)
+      end
+
+      # POST /v2.2/messages — send an SMS or MMS.
+      def send_message(body)
+        @transport.request(:post, "/v2.2/messages", body: body)
+      end
+
+      # POST /v2.2/messaging/brands — register a 10DLC brand.
+      def create_brand(body)
+        @transport.request(:post, "/v2.2/messaging/brands", body: body)
+      end
+
+      # GET /v2.2/messaging/campaigns — current 10DLC campaign statuses.
+      def campaign_status
+        @transport.request(:get, "/v2.2/messaging/campaigns")
+      end
+
+      # POST /v2.2/messaging/campaigns — register a 10DLC campaign.
+      def create_campaign(body)
+        @transport.request(:post, "/v2.2/messaging/campaigns", body: body)
+      end
+
+      # GET /v2.2/numbers/messaging — messaging state for many numbers.
+      # Pass an empty array (or omit) for "all numbers on the account".
+      def numbers_state(numbers: nil)
+        q = compact_query(
+          "numbers" => (numbers && !numbers.empty? ? Array(numbers).join(",") : nil)
+        )
+        @transport.request(:get, "/v2.2/numbers/messaging", query: q)
+      end
+    end
+  end
+end

data/lib/voicetel/resources/numbers.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VoiceTel
+  module Resources
+    # NumbersService — every operation on a TN owned by the account.
+    #
+    # Most methods take the 10-digit TN as the first argument. Methods that
+    # return 204 No Content return nil. The two exceptions in this resource
+    # — DELETE /v2.2/numbers/{n}/messaging-campaign and
+    # DELETE /v2.2/numbers/messaging-campaign — return 200 with a body and
+    # are exposed via #unassign_campaign and #bulk_unassign_campaign.
+    class Numbers < Base
+      def list
+        @transport.request(:get, "/v2.2/numbers")
+      end
+
+      def add(body)
+        @transport.request(:post, "/v2.2/numbers", body: body)
+      end
+
+      def get(number)
+        @transport.request(:get, "/v2.2/numbers/#{number}")
+      end
+
+      # Returns nil on 204 No Content.
+      def remove(number)
+        @transport.request(:delete, "/v2.2/numbers/#{number}")
+      end
+
+      # PATCH /v2.2/numbers/{number} — move a TN to another account.
+      def move(number, body)
+        @transport.request(:patch, "/v2.2/numbers/#{number}", body: body)
+      end
+
+      # POST /v2.2/numbers/{number}/release — release a TN back to the network.
+      def release(number)
+        @transport.request(:post, "/v2.2/numbers/#{number}/release")
+      end
+
+      def set_route(number, body)
+        @transport.request(:put, "/v2.2/numbers/#{number}/route", body: body)
+      end
+
+      def set_translation(number, body)
+        @transport.request(:put, "/v2.2/numbers/#{number}/translation", body: body)
+      end
+
+      def set_cnam(number, body)
+        @transport.request(:put, "/v2.2/numbers/#{number}/cnam", body: body)
+      end
+
+      def set_lidb(number, body)
+        @transport.request(:put, "/v2.2/numbers/#{number}/lidb", body: body)
+      end
+
+      def get_fax(number)
+        @transport.request(:get, "/v2.2/numbers/#{number}/fax")
+      end
+
+      def set_fax(number, body)
+        @transport.request(:put, "/v2.2/numbers/#{number}/fax", body: body)
+      end
+
+      # Returns nil on 204 No Content.
+      def remove_fax(number)
+        @transport.request(:delete, "/v2.2/numbers/#{number}/fax")
+      end
+
+      def set_forward(number, body)
+        @transport.request(:put, "/v2.2/numbers/#{number}/forward", body: body)
+      end
+
+      # Returns nil on 204 No Content.
+      def remove_forward(number)
+        @transport.request(:delete, "/v2.2/numbers/#{number}/forward")
+      end
+
+      def get_sms(number)
+        @transport.request(:get, "/v2.2/numbers/#{number}/sms")
+      end
+
+      def set_sms(number, body)
+        @transport.request(:put, "/v2.2/numbers/#{number}/sms", body: body)
+      end
+
+      # Returns nil on 204 No Content.
+      def remove_sms(number)
+        @transport.request(:delete, "/v2.2/numbers/#{number}/sms")
+      end
+
+      def get_messaging(number)
+        @transport.request(:get, "/v2.2/numbers/#{number}/messaging")
+      end
+
+      def patch_messaging(number, body)
+        @transport.request(:patch, "/v2.2/numbers/#{number}/messaging", body: body)
+      end
+
+      def assign_campaign(number, body)
+        @transport.request(:put, "/v2.2/numbers/#{number}/messaging-campaign", body: body)
+      end
+
+      # Returns response data (200 with body, not 204).
+      def unassign_campaign(number)
+        @transport.request(:delete, "/v2.2/numbers/#{number}/messaging-campaign")
+      end
+
+      # Returns response data (200 with body, not 204).
+      def bulk_unassign_campaign(numbers)
+        @transport.request(:delete, "/v2.2/numbers/messaging-campaign", body: { numbers: numbers })
+      end
+
+      def set_port_out_pin(number, body)
+        @transport.request(:patch, "/v2.2/numbers/#{number}/port-out-pin", body: body)
+      end
+    end
+  end
+end

data/lib/voicetel/resources/support.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module VoiceTel
+  module Resources
+    # SupportService — support tickets (create, read, update, delete, reply).
+    #
+    # On the wire, SupportConversation.number is a ticket sequence integer
+    # (1015, 2114, ...), NOT a phone number. When the spec uses `number`
+    # in this context, that's the ticket id.
+    class Support < Base
+      def list
+        @transport.request(:get, "/v2.2/support/tickets")
+      end
+
+      def create(body)
+        @transport.request(:post, "/v2.2/support/tickets", body: body)
+      end
+
+      def get(id)
+        @transport.request(:get, "/v2.2/support/tickets/#{id}")
+      end
+
+      def update(id, body)
+        @transport.request(:put, "/v2.2/support/tickets/#{id}", body: body)
+      end
+
+      # Returns nil on 204 No Content.
+      def delete(id)
+        @transport.request(:delete, "/v2.2/support/tickets/#{id}")
+      end
+
+      def messages(id)
+        @transport.request(:get, "/v2.2/support/tickets/#{id}/messages")
+      end
+
+      def reply(id, body)
+        @transport.request(:post, "/v2.2/support/tickets/#{id}/replies", body: body)
+      end
+    end
+  end
+end

data/lib/voicetel/version.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module VoiceTel
+  # The semantic version of the VoiceTel Ruby SDK. This tracks the API version
+  # it targets (currently v2.2.10).
+  VERSION = "2.2.10"
+
+  # The VoiceTel REST API version this SDK targets.
+  API_VERSION = "v2.2.10"
+
+  # Default production API endpoint.
+  DEFAULT_BASE_URL = "https://api.voicetel.com"
+
+  # User-Agent header sent on every request unless overridden.
+  USER_AGENT = "voicetel-ruby/#{VERSION} (+https://github.com/voicetel/ruby-sdk)".freeze
+end

data/lib/voicetel.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "voicetel/version"
+require_relative "voicetel/api_error"
+require_relative "voicetel/internal/transport"
+require_relative "voicetel/resources/account"
+require_relative "voicetel/resources/acl"
+require_relative "voicetel/resources/authentication"
+require_relative "voicetel/resources/e911"
+require_relative "voicetel/resources/gateways"
+require_relative "voicetel/resources/i_numbering"
+require_relative "voicetel/resources/lookups"
+require_relative "voicetel/resources/messaging"
+require_relative "voicetel/resources/numbers"
+require_relative "voicetel/resources/support"
+
+# VoiceTel is the official Ruby SDK for the VoiceTel REST API.
+#
+# See:
+# - https://voicetel.com/docs/api/v2.2/         — full API reference
+# - https://voicetel.com/docs/api/v2.2/playground/ — interactive playground
+# - https://voicetel.com/docs/api/v2.2/credentials/ — obtain credentials
+module VoiceTel
+  # Client is the entry point for the VoiceTel API. Construct with an API key
+  # (or call #login to exchange username/password) and reach the API through
+  # the resource accessors:
+  #
+  #   c = VoiceTel::Client.new(api_key: ENV.fetch("VOICETEL_API_KEY"))
+  #   c.numbers.list
+  #
+  # Client is safe to share across threads as long as you don't reassign
+  # the API key concurrently with in-flight requests.
+  class Client
+    attr_reader :transport
+
+    def initialize(api_key: nil, base_url: nil, timeout: 30, max_retries: 2, user_agent: nil, adapter: nil)
+      @transport = Internal::Transport.new(
+        base_url: base_url,
+        api_key: api_key,
+        timeout: timeout,
+        max_retries: max_retries,
+        user_agent: user_agent,
+        adapter: adapter
+      )
+    end
+
+    # Exchange username + password for a 32-hex API key and install it on
+    # this client. Shares the 6 req/hour/IP rate limit with the rest of the
+    # account/* endpoints.
+    #
+    # @return [String] the freshly exchanged bearer token
+    def login(username:, password:)
+      data = @transport.request(
+        :post, "/v2.2/account/api-key",
+        body: { username: username, password: password },
+        require_auth: false
+      )
+      key = data.is_a?(Hash) ? data["apikey"] : nil
+      if key.nil? || key.empty?
+        raise ApiError.new(
+          "voicetel: api-key response did not contain data.apikey",
+          kind: :authentication,
+          body: data
+        )
+      end
+      @transport.api_key = key
+      key
+    end
+
+    # Currently installed bearer token (nil if none).
+    def api_key
+      @transport.api_key
+    end
+
+    # API endpoint this client is pointed at.
+    def base_url
+      @transport.base_url
+    end
+
+    # --- resource accessors ------------------------------------------------
+
+    def account
+      @account ||= Resources::Account.new(@transport)
+    end
+
+    def acl
+      @acl ||= Resources::Acl.new(@transport)
+    end
+
+    def authentication
+      @authentication ||= Resources::Authentication.new(@transport)
+    end
+
+    def e911
+      @e911 ||= Resources::E911.new(@transport)
+    end
+
+    def gateways
+      @gateways ||= Resources::Gateways.new(@transport)
+    end
+
+    def i_numbering
+      @i_numbering ||= Resources::INumbering.new(@transport)
+    end
+
+    def lookups
+      @lookups ||= Resources::Lookups.new(@transport)
+    end
+
+    def messaging
+      @messaging ||= Resources::Messaging.new(@transport)
+    end
+
+    def numbers
+      @numbers ||= Resources::Numbers.new(@transport)
+    end
+
+    def support
+      @support ||= Resources::Support.new(@transport)
+    end
+  end
+end

data/sig/voicetel.rbs

@@ -0,0 +1,206 @@
+# RBS type signatures for the VoiceTel Ruby SDK.
+#
+# Hashes/Arrays are deliberately typed as untyped throughout — request bodies
+# and response shapes are spec-defined and would explode this file's size if
+# fully modelled. The public API (Client, Resources, ApiError) is statically
+# typed; payloads pass through as `untyped`.
+
+module VoiceTel
+  VERSION: String
+  API_VERSION: String
+  DEFAULT_BASE_URL: String
+  USER_AGENT: String
+
+  class ApiError < StandardError
+    KINDS: Array[Symbol]
+
+    attr_reader kind: Symbol
+    attr_reader status_code: Integer?
+    attr_reader code: String?
+    attr_reader body: untyped
+
+    def initialize: (String message, ?kind: Symbol, ?status_code: Integer?, ?code: String?, ?body: untyped) -> void
+
+    def bad_request?: () -> bool
+    def authentication?: () -> bool
+    def permission_denied?: () -> bool
+    def not_found?: () -> bool
+    def conflict?: () -> bool
+    def rate_limit?: () -> bool
+    def server?: () -> bool
+    def unknown?: () -> bool
+
+    def self.kind_from_status: (Integer) -> Symbol
+    def self.from_response: (Integer status, String? code, String message, untyped body) -> ApiError
+  end
+
+  module Internal
+    class Transport
+      RETRYABLE_STATUSES: Array[Integer]
+
+      attr_reader base_url: String
+      attr_reader user_agent: String
+      attr_reader timeout: Integer | Float
+      attr_reader max_retries: Integer
+      attr_accessor api_key: String?
+
+      def initialize: (
+        base_url: String?,
+        ?api_key: String?,
+        ?timeout: Integer | Float,
+        ?max_retries: Integer,
+        ?user_agent: String?,
+        ?adapter: Symbol?
+      ) -> void
+
+      def request: (
+        Symbol method, String path,
+        ?query: Hash[untyped, untyped]?, ?body: untyped, ?require_auth: bool
+      ) -> untyped
+
+      def camelize_keys: (untyped) -> untyped
+    end
+  end
+
+  module Resources
+    class Base
+      def initialize: (Internal::Transport transport) -> void
+      def compact_query: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
+    end
+
+    class Account < Base
+      def get: () -> untyped
+      def update: (untyped body) -> untyped
+      def add: (untyped body) -> untyped
+      def signup: (untyped body) -> untyped
+      def cdr: (?start: untyped?, ?end_at: untyped?) -> untyped
+      def credits: () -> untyped
+      def recurring_charges: () -> untyped
+      def payments: () -> untyped
+      def registration: () -> untyped
+      def recover: (untyped body) -> untyped
+    end
+
+    class Acl < Base
+      def list: () -> untyped
+      def add: (untyped body) -> untyped
+      def remove: (untyped body) -> untyped
+    end
+
+    class Authentication < Base
+      AUTH_TYPE_DIGEST: Integer
+      AUTH_TYPE_IP: Integer
+      AUTH_TYPE_DIGEST_OR_IP: Integer
+      AUTH_TYPE_DIGEST_AND_IP: Integer
+
+      def get: () -> untyped
+      def update: (untyped body) -> untyped
+    end
+
+    class E911 < Base
+      def list: () -> untyped
+      def create: (untyped body) -> untyped
+      def validate: (untyped body) -> untyped
+      def get: (String dn) -> untyped
+      def provision: (String dn, untyped body) -> untyped
+      def remove: (String dn) -> untyped
+    end
+
+    class Gateways < Base
+      def list: () -> untyped
+      def add: (untyped body) -> untyped
+      def get: (Integer id) -> untyped
+      def update: (Integer id, untyped body) -> untyped
+      def remove: (Integer id) -> untyped
+      def numbers: (Integer id) -> untyped
+    end
+
+    class INumbering < Base
+      def search_inventory: (
+        ?npa: Integer?, ?nxx: Integer?, ?state: String?, ?ratecenter: String?,
+        ?contains: String?, ?endswith: String?, ?limit: Integer?
+      ) -> untyped
+      def coverage: (?state: String?, ?ratecenter: String?) -> untyped
+      def order: (untyped body) -> untyped
+      def ports: () -> untyped
+      def port: (Integer id) -> untyped
+      def submit_port: (untyped body) -> untyped
+      def port_availability: (String number) -> untyped
+    end
+
+    class Lookups < Base
+      def cnam: (String number) -> untyped
+      def lrn: (String number, String ani) -> untyped
+    end
+
+    class Messaging < Base
+      def history: (?number: String?, ?start: Integer?, ?end_at: Integer?, ?type: String?) -> untyped
+      def send_message: (untyped body) -> untyped
+      def create_brand: (untyped body) -> untyped
+      def campaign_status: () -> untyped
+      def create_campaign: (untyped body) -> untyped
+      def numbers_state: (?numbers: Array[String]?) -> untyped
+    end
+
+    class Numbers < Base
+      def list: () -> untyped
+      def add: (untyped body) -> untyped
+      def get: (String number) -> untyped
+      def remove: (String number) -> untyped
+      def move: (String number, untyped body) -> untyped
+      def release: (String number) -> untyped
+      def set_route: (String number, untyped body) -> untyped
+      def set_translation: (String number, untyped body) -> untyped
+      def set_cnam: (String number, untyped body) -> untyped
+      def set_lidb: (String number, untyped body) -> untyped
+      def get_fax: (String number) -> untyped
+      def set_fax: (String number, untyped body) -> untyped
+      def remove_fax: (String number) -> untyped
+      def set_forward: (String number, untyped body) -> untyped
+      def remove_forward: (String number) -> untyped
+      def get_sms: (String number) -> untyped
+      def set_sms: (String number, untyped body) -> untyped
+      def remove_sms: (String number) -> untyped
+      def get_messaging: (String number) -> untyped
+      def patch_messaging: (String number, untyped body) -> untyped
+      def assign_campaign: (String number, untyped body) -> untyped
+      def unassign_campaign: (String number) -> untyped
+      def bulk_unassign_campaign: (Array[String] numbers) -> untyped
+      def set_port_out_pin: (String number, untyped body) -> untyped
+    end
+
+    class Support < Base
+      def list: () -> untyped
+      def create: (untyped body) -> untyped
+      def get: (Integer id) -> untyped
+      def update: (Integer id, untyped body) -> untyped
+      def delete: (Integer id) -> untyped
+      def messages: (Integer id) -> untyped
+      def reply: (Integer id, untyped body) -> untyped
+    end
+  end
+
+  class Client
+    attr_reader transport: Internal::Transport
+
+    def initialize: (
+      ?api_key: String?, ?base_url: String?, ?timeout: Integer | Float,
+      ?max_retries: Integer, ?user_agent: String?, ?adapter: Symbol?
+    ) -> void
+
+    def login: (username: untyped, password: String) -> String
+    def api_key: () -> String?
+    def base_url: () -> String
+
+    def account: () -> Resources::Account
+    def acl: () -> Resources::Acl
+    def authentication: () -> Resources::Authentication
+    def e911: () -> Resources::E911
+    def gateways: () -> Resources::Gateways
+    def i_numbering: () -> Resources::INumbering
+    def lookups: () -> Resources::Lookups
+    def messaging: () -> Resources::Messaging
+    def numbers: () -> Resources::Numbers
+    def support: () -> Resources::Support
+  end
+end