telnyx 0.0.1

data/lib/telnyx/api_resource.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Telnyx
+  class APIResource < TelnyxObject
+    include Telnyx::APIOperations::Request
+
+    # A flag that can be set a behavior that will cause this resource to be
+    # encoded and sent up along with an update of its parent resource. This is
+    # usually not desirable because resources are updated individually on their
+    # own endpoints, but there are certain cases where this is allowed.
+    attr_accessor :save_with_parent
+
+    def self.class_name
+      name.split("::")[-1]
+    end
+
+    def self.resource_url
+      if self == APIResource
+        raise NotImplementedError, "APIResource is an abstract class. You should perform actions on its subclasses"
+      end
+      # Namespaces are separated in object names with periods (.) and in URLs
+      # with forward slashes (/), so replace the former with the latter.
+      "/v2/#{self::OBJECT_NAME.downcase.tr('.', '/')}s"
+    end
+
+    # A metaprogramming call that specifies that a field of a resource can be
+    # its own type of API resource (say a nested card under an account for
+    # example), and if that resource is set, it should be transmitted to the
+    # API on a create or update. Doing so is not the default behavior because
+    # API resources should normally be persisted on their own RESTful
+    # endpoints.
+    def self.save_nested_resource(name)
+      define_method(:"#{name}=") do |value|
+        super(value)
+
+        # The parent setter will perform certain useful operations like
+        # converting to an APIResource if appropriate. Refresh our argument
+        # value to whatever it mutated to.
+        value = send(name)
+
+        # Note that the value may be subresource, but could also be a scalar
+        # (like a tokenized card's ID for example), so we check the type before
+        # setting #save_with_parent here.
+        value.save_with_parent = true if value.is_a?(APIResource)
+
+        value
+      end
+    end
+
+    def resource_url
+      unless (id = self["id"])
+        raise InvalidRequestError, "Could not determine which URL to request: #{self.class} instance has invalid ID: #{id.inspect}"
+      end
+      "#{self.class.resource_url}/#{CGI.escape(id)}"
+    end
+
+    def refresh
+      resp, opts = request(:get, resource_url, @retrieve_params, @opts)
+      initialize_from(resp.data[:data], opts)
+    end
+
+    def self.retrieve(id, opts = {})
+      opts = Util.normalize_opts(opts)
+      instance = new(id, opts)
+      instance.refresh
+      instance
+    end
+  end
+end

data/lib/telnyx/available_phone_number.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Telnyx
+  class AvailablePhoneNumber < APIResource
+    extend Telnyx::APIOperations::List
+
+    OBJECT_NAME = "available_phone_number".freeze
+  end
+end

data/lib/telnyx/errors.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Telnyx
+  # TelnyxError is the base error from which all other more specific Telnyx
+  # errors derive.
+  class TelnyxError < StandardError
+    # Full details for all errors returned in response
+    attr_reader :errors
+
+    # Response contains a TelnyxResponse object that has some basic information
+    # about the response that conveyed the error.
+    attr_accessor :response
+
+    attr_reader :http_body
+    attr_reader :http_headers
+    attr_reader :http_status
+    attr_reader :json_body # equivalent to #data
+    attr_reader :request_id
+
+    # Initializes a TelnyxError.
+    def initialize(errors = nil, http_status: nil, http_body: nil, json_body: nil, http_headers: nil)
+      @http_status = http_status
+      @http_body = http_body
+      @http_headers = http_headers || {}
+      @json_body = json_body
+      @request_id = @http_headers[:request_id]
+      @errors = stringify_errors(errors)
+    end
+
+    def to_s
+      status_string = @http_status.nil? ? "" : "(Status #{@http_status}) "
+      id_string = @request_id.nil? ? "" : "(Request #{@request_id}) "
+      instruction = "Full details: #{@errors}"
+      "#{status_string}#{id_string}#{message}#{other_errors_message}#{instruction}"
+    end
+
+    def other_errors_message
+      count = error_count
+      if count > 2
+        "plus #{count} other errors. "
+      elsif count == 2
+        "plus 1 other error. "
+      end
+    end
+
+    def message
+      case @errors
+      when Array
+        @errors[0]["title"] + " "
+      else
+        @errors
+      end
+    end
+
+    def error_count
+      case @errors
+      when Array
+        @errors.count
+      else
+        1
+      end
+    end
+
+    def stringify_hash(h)
+      str_hash = {}
+      h.each_key do |k|
+        str_hash[k.to_s] = h[k]
+      end
+      str_hash
+    end
+
+    def stringify_errors(errors)
+      if errors.is_a? Array
+        errors.map { |h| stringify_hash(h) }
+      elsif errors.is_a? Hash
+        stringify_hash errors
+      else
+        errors
+      end
+    end
+  end
+
+  # InvalidRequestError is raised when a request cannot be parsed by Telnyx
+  class InvalidRequestError < TelnyxError
+    STATUS_CODE = 400
+  end
+
+  # AuthenticationError is raised when invalid credentials are used to connect
+  # to Telnyx's servers.
+  class AuthenticationError < TelnyxError
+    STATUS_CODE = 401
+  end
+
+  # PermissionError is raised in cases where access was attempted on a resource
+  # that wasn't allowed.
+  class PermissionError < TelnyxError
+    STATUS_CODE = 403
+  end
+
+  # ResourceNotFoundError is raised when a resource or path does not exist.
+  # that wasn't allowed.
+  class ResourceNotFoundError < TelnyxError
+    STATUS_CODE = 404
+  end
+
+  # MethodNotSupportedError is raised a request is made using a method that
+  # is not supported by the endpoint.
+  class MethodNotSupportedError < TelnyxError
+    STATUS_CODE = 405
+  end
+
+  # TimeoutError is raised when the request times out while being processed by
+  # Telnyx's servers.
+  class TimeoutError < TelnyxError
+    STATUS_CODE = 408
+  end
+
+  # UnsupportedMediaTypeError is raised when the media type of the request is
+  # not supported.
+  class UnsupportedMediaTypeError < TelnyxError
+    STATUS_CODE = 415
+  end
+
+  # InvalidParametersError is raised when a request is made with invaid parameters
+  class InvalidParametersError < TelnyxError
+    STATUS_CODE = 422
+  end
+
+  # RateLimitError is raised in cases where an account is putting too much load
+  # on Telnyx's API servers (usually by performing too many requests). Please
+  # back off on request rate.
+  class RateLimitError < TelnyxError
+    STATUS_CODE = 429
+  end
+
+  # APIError is a generic error that may be raised in cases where none of the
+  # other named errors cover the problem. It could also be raised in the case
+  # that a new error has been introduced in the API, but this version of the
+  # Ruby SDK doesn't know how to handle it.
+  class APIError < TelnyxError
+    STATUS_CODE = 500
+  end
+
+  # Service unavailable error is raise when a request receives a response status
+  # code of 503 Service Unavailable.
+  class ServiceUnavailableError < TelnyxError
+    STATUS_CODE = 503
+  end
+
+  # APIConnectionError is raised in the event that the SDK can't connect to
+  # Telnyx's servers. That can be for a variety of different reasons from a
+  # downed network to a bad TLS certificate.
+  class APIConnectionError < TelnyxError
+  end
+
+  # SignatureVerificationError is raised when the signature verification for a
+  # webhook fails
+  class SignatureVerificationError < TelnyxError
+    attr_accessor :sig_header
+
+    def initialize(message, sig_header, http_body: nil)
+      super(message, http_body: http_body)
+      @sig_header = sig_header
+    end
+  end
+end

data/lib/telnyx/event.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Telnyx
+  class Event < APIResource
+    extend Telnyx::APIOperations::List
+
+    OBJECT_NAME = "event".freeze
+  end
+end

data/lib/telnyx/list_object.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Telnyx
+  class ListObject < TelnyxObject
+    include Enumerable
+    include Telnyx::APIOperations::List
+    include Telnyx::APIOperations::Request
+    include Telnyx::APIOperations::Create
+
+    # This accessor allows a `ListObject` to inherit various filters that were
+    # given to a predecessor. This allows for things like consistent limits,
+    # expansions, and predicates as a user pages through resources.
+    attr_accessor :filters
+
+    # An empty list object. This is returned from +next+ when we know that
+    # there isn't a next page in order to replicate the behavior of the API
+    # when it attempts to return a page beyond the last.
+    def self.empty_list(opts = {})
+      ListObject.construct_from({ data: [] }, opts)
+    end
+
+    def initialize(*args)
+      super
+      self.filters = {}
+    end
+
+    def [](k)
+      case k
+      when String, Symbol
+        super
+      else
+        raise ArgumentError, "You tried to access the #{k.inspect} index, but ListObject types only support String keys. (HINT: List calls return an object with a 'data' (which is the data array). You likely want to call #data[#{k.inspect}])"
+      end
+    end
+
+    # Iterates through each resource in the page represented by the current
+    # `ListObject`.
+    #
+    # Note that this method makes no effort to fetch a new page when it gets to
+    # the end of the current page's resources. See also +auto_paging_each+.
+    def each(&blk)
+      data.each(&blk)
+    end
+
+    # Iterates through each resource in all pages, making additional fetches to
+    # the API as necessary.
+    #
+    # Note that this method will make as many API calls as necessary to fetch
+    # all resources. For more granular control, please see +each+ and
+    # +next_page+.
+    def auto_paging_each(&blk)
+      return enum_for(:auto_paging_each) unless block_given?
+
+      page = self
+      loop do
+        page.each(&blk)
+        page = page.next_page
+        break if page.empty?
+      end
+    end
+
+    # Iterates through each resource in all pages, making additional fetches to
+    # the API as necessary.
+    #
+    # Note that this method will make as many API calls as necessary to fetch
+    # all resources. For more granular control, please see +each+ and
+    # +next_page_by_token+.
+    def auto_paging_each_by_token(&blk)
+      return enum_for(:auto_paging_each_by_token) unless block_given?
+
+      page = self
+      loop do
+        page.each(&blk)
+        page = page.next_page_by_token
+        break if page.empty?
+      end
+    end
+
+    # Returns true if the page object contains no elements.
+    def empty?
+      data.empty?
+    end
+
+    def retrieve(id, opts = {})
+      id, retrieve_params = Util.normalize_id(id)
+      resp, opts = request(:get, "#{resource_url}/#{CGI.escape(id)}", retrieve_params, opts)
+      Util.convert_to_telnyx_object(resp.data, opts)
+    end
+
+    def more?
+      !data.empty? && meta[:page_number] && meta[:total_pages] && meta[:total_pages] > meta[:page_number]
+    end
+
+    # Fetches the next page in the resource list (if there is one).
+    #
+    # This method will try to respect the limit of the current page. If none
+    # was given, the default limit will be fetched again.
+    def next_page(params = {}, opts = {})
+      return self.class.empty_list(opts) unless more?
+      next_page_number = page_number.to_i + 1
+      pagination = { number: next_page_number, size: page_size(filters) }
+      params = filters.merge(params).merge(page: pagination)
+
+      list(params, opts)
+    end
+
+    def next_page_by_token(params = {}, opts = {})
+      return self.class.empty_list(opts) unless token
+      pagination = { token: token }
+      params = filters.merge(params).merge(page: pagination)
+
+      list(params, opts)
+    end
+
+    # Fetches the previous page in the resource list (if there is one).
+    #
+    # This method will try to respect the limit of the current page. If none
+    # was given, the default limit will be fetched again.
+    def previous_page(params = {}, opts = {})
+      prev_page_number = page_number.to_i - 1
+      prev_page_number = [prev_page_number, 1].max
+      pagination = { number: prev_page_number, size: page_size(filters) }
+      params = filters.merge(params).merge(page: pagination)
+
+      list(params, opts)
+    end
+
+    # Fetch the current page size
+    def page_size(params)
+      if params && params[:page] && params[:page][:size]
+        params[:page][:size]
+      else
+        20
+      end
+    end
+
+    # Fetch the current page number
+    def page_number
+      if meta && meta[:page_number]
+        meta.page_number
+      else
+        1
+      end
+    end
+
+    def token
+      return meta.next_page_token if meta && meta[:next_page_token]
+    end
+
+    def resource_url
+      url ||
+        raise(ArgumentError, "List object does not contain a 'url' field.")
+    end
+  end
+end

data/lib/telnyx/message.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Telnyx
+  class Message < APIResource
+    extend Telnyx::APIOperations::Create
+
+    OBJECT_NAME = "message".freeze
+  end
+end

data/lib/telnyx/messaging_phone_number.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Telnyx
+  class MessagingPhoneNumber < APIResource
+    include Telnyx::APIOperations::Save
+    extend Telnyx::APIOperations::List
+
+    OBJECT_NAME = "messaging_phone_number".freeze
+  end
+end

data/lib/telnyx/messaging_profile.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Telnyx
+  class MessagingProfile < APIResource
+    include Telnyx::APIOperations::Save
+    include Telnyx::APIOperations::Delete
+    extend Telnyx::APIOperations::List
+    extend Telnyx::APIOperations::Create
+    extend Telnyx::APIOperations::NestedResource
+
+    OBJECT_NAME = "messaging_profile".freeze
+
+    nested_resource_class_methods :phone_number,
+                                  operations: %i[list]
+    nested_resource_class_methods :sender_id,
+                                  operations: %i[list]
+    nested_resource_class_methods :short_code,
+                                  operations: %i[list]
+
+    def phone_numbers(params = {}, opts = {})
+      self.class.list_phone_numbers(id, params, opts)
+    end
+
+    def sender_ids(params = {}, opts = {})
+      self.class.list_sender_ids(id, params, opts)
+    end
+
+    def short_codes(params = {}, opts = {})
+      self.class.list_short_codes(id, params, opts)
+    end
+  end
+end