twilio-ruby 5.5.1 → 5.58.3

data/lib/twilio-ruby/rest/wireless/v1/usage_record.rb

@@ -0,0 +1,229 @@
+##
+# This code was generated by
+# \ / _    _  _|   _  _
+#  | (_)\/(_)(_|\/| |(/_  v1.0.0
+#       /       /
+#
+# frozen_string_literal: true
+
+module Twilio
+  module REST
+    class Wireless < Domain
+      class V1 < Version
+        class UsageRecordList < ListResource
+          ##
+          # Initialize the UsageRecordList
+          # @param [Version] version Version that contains the resource
+          # @return [UsageRecordList] UsageRecordList
+          def initialize(version)
+            super(version)
+
+            # Path Solution
+            @solution = {}
+            @uri = "/UsageRecords"
+          end
+
+          ##
+          # Lists UsageRecordInstance records from the API as a list.
+          # Unlike stream(), this operation is eager and will load `limit` records into
+          # memory before returning.
+          # @param [Time] end_ Only include usage that has occurred on or before this date.
+          #   Format is {ISO 8601}[https://www.iso.org/iso-8601-date-and-time-format.html].
+          # @param [Time] start Only include usage that has occurred on or after this date.
+          #   Format is {ISO 8601}[https://www.iso.org/iso-8601-date-and-time-format.html].
+          # @param [usage_record.Granularity] granularity How to summarize the usage by
+          #   time. Can be: `daily`, `hourly`, or `all`. A value of `all` returns one Usage
+          #   Record that describes the usage for the entire period.
+          # @param [Integer] limit Upper limit for the number of records to return. stream()
+          #    guarantees to never return more than limit.  Default is no limit
+          # @param [Integer] page_size Number of records to fetch per request, when
+          #    not set will use the default value of 50 records.  If no page_size is defined
+          #    but a limit is defined, stream() will attempt to read the limit with the most
+          #    efficient page size, i.e. min(limit, 1000)
+          # @return [Array] Array of up to limit results
+          def list(end_: :unset, start: :unset, granularity: :unset, limit: nil, page_size: nil)
+            self.stream(
+                end_: end_,
+                start: start,
+                granularity: granularity,
+                limit: limit,
+                page_size: page_size
+            ).entries
+          end
+
+          ##
+          # Streams UsageRecordInstance records from the API as an Enumerable.
+          # This operation lazily loads records as efficiently as possible until the limit
+          # is reached.
+          # @param [Time] end_ Only include usage that has occurred on or before this date.
+          #   Format is {ISO 8601}[https://www.iso.org/iso-8601-date-and-time-format.html].
+          # @param [Time] start Only include usage that has occurred on or after this date.
+          #   Format is {ISO 8601}[https://www.iso.org/iso-8601-date-and-time-format.html].
+          # @param [usage_record.Granularity] granularity How to summarize the usage by
+          #   time. Can be: `daily`, `hourly`, or `all`. A value of `all` returns one Usage
+          #   Record that describes the usage for the entire period.
+          # @param [Integer] limit Upper limit for the number of records to return. stream()
+          #    guarantees to never return more than limit. Default is no limit.
+          # @param [Integer] page_size Number of records to fetch per request, when
+          #    not set will use the default value of 50 records. If no page_size is defined
+          #    but a limit is defined, stream() will attempt to read the limit with the most
+          #    efficient page size, i.e. min(limit, 1000)
+          # @return [Enumerable] Enumerable that will yield up to limit results
+          def stream(end_: :unset, start: :unset, granularity: :unset, limit: nil, page_size: nil)
+            limits = @version.read_limits(limit, page_size)
+
+            page = self.page(end_: end_, start: start, granularity: granularity, page_size: limits[:page_size], )
+
+            @version.stream(page, limit: limits[:limit], page_limit: limits[:page_limit])
+          end
+
+          ##
+          # When passed a block, yields UsageRecordInstance records from the API.
+          # This operation lazily loads records as efficiently as possible until the limit
+          # is reached.
+          def each
+            limits = @version.read_limits
+
+            page = self.page(page_size: limits[:page_size], )
+
+            @version.stream(page,
+                            limit: limits[:limit],
+                            page_limit: limits[:page_limit]).each {|x| yield x}
+          end
+
+          ##
+          # Retrieve a single page of UsageRecordInstance records from the API.
+          # Request is executed immediately.
+          # @param [Time] end_ Only include usage that has occurred on or before this date.
+          #   Format is {ISO 8601}[https://www.iso.org/iso-8601-date-and-time-format.html].
+          # @param [Time] start Only include usage that has occurred on or after this date.
+          #   Format is {ISO 8601}[https://www.iso.org/iso-8601-date-and-time-format.html].
+          # @param [usage_record.Granularity] granularity How to summarize the usage by
+          #   time. Can be: `daily`, `hourly`, or `all`. A value of `all` returns one Usage
+          #   Record that describes the usage for the entire period.
+          # @param [String] page_token PageToken provided by the API
+          # @param [Integer] page_number Page Number, this value is simply for client state
+          # @param [Integer] page_size Number of records to return, defaults to 50
+          # @return [Page] Page of UsageRecordInstance
+          def page(end_: :unset, start: :unset, granularity: :unset, page_token: :unset, page_number: :unset, page_size: :unset)
+            params = Twilio::Values.of({
+                'End' => Twilio.serialize_iso8601_datetime(end_),
+                'Start' => Twilio.serialize_iso8601_datetime(start),
+                'Granularity' => granularity,
+                'PageToken' => page_token,
+                'Page' => page_number,
+                'PageSize' => page_size,
+            })
+
+            response = @version.page('GET', @uri, params: params)
+
+            UsageRecordPage.new(@version, response, @solution)
+          end
+
+          ##
+          # Retrieve a single page of UsageRecordInstance records from the API.
+          # Request is executed immediately.
+          # @param [String] target_url API-generated URL for the requested results page
+          # @return [Page] Page of UsageRecordInstance
+          def get_page(target_url)
+            response = @version.domain.request(
+                'GET',
+                target_url
+            )
+            UsageRecordPage.new(@version, response, @solution)
+          end
+
+          ##
+          # Provide a user friendly representation
+          def to_s
+            '#<Twilio.Wireless.V1.UsageRecordList>'
+          end
+        end
+
+        class UsageRecordPage < Page
+          ##
+          # Initialize the UsageRecordPage
+          # @param [Version] version Version that contains the resource
+          # @param [Response] response Response from the API
+          # @param [Hash] solution Path solution for the resource
+          # @return [UsageRecordPage] UsageRecordPage
+          def initialize(version, response, solution)
+            super(version, response)
+
+            # Path Solution
+            @solution = solution
+          end
+
+          ##
+          # Build an instance of UsageRecordInstance
+          # @param [Hash] payload Payload response from the API
+          # @return [UsageRecordInstance] UsageRecordInstance
+          def get_instance(payload)
+            UsageRecordInstance.new(@version, payload, )
+          end
+
+          ##
+          # Provide a user friendly representation
+          def to_s
+            '<Twilio.Wireless.V1.UsageRecordPage>'
+          end
+        end
+
+        class UsageRecordInstance < InstanceResource
+          ##
+          # Initialize the UsageRecordInstance
+          # @param [Version] version Version that contains the resource
+          # @param [Hash] payload payload that contains response from Twilio
+          # @return [UsageRecordInstance] UsageRecordInstance
+          def initialize(version, payload)
+            super(version)
+
+            # Marshaled Properties
+            @properties = {
+                'account_sid' => payload['account_sid'],
+                'period' => payload['period'],
+                'commands' => payload['commands'],
+                'data' => payload['data'],
+            }
+          end
+
+          ##
+          # @return [String] The SID of the Account that created the resource
+          def account_sid
+            @properties['account_sid']
+          end
+
+          ##
+          # @return [Hash] The time period for which usage is reported
+          def period
+            @properties['period']
+          end
+
+          ##
+          # @return [Hash] An object that describes the aggregated Commands usage for all SIMs during the specified period
+          def commands
+            @properties['commands']
+          end
+
+          ##
+          # @return [Hash] An object that describes the aggregated Data usage for all SIMs over the period
+          def data
+            @properties['data']
+          end
+
+          ##
+          # Provide a user friendly representation
+          def to_s
+            "<Twilio.Wireless.V1.UsageRecordInstance>"
+          end
+
+          ##
+          # Provide a detailed, user friendly representation
+          def inspect
+            "<Twilio.Wireless.V1.UsageRecordInstance>"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/twilio-ruby/rest/wireless/v1.rb

@@ -3,6 +3,8 @@
 # \ / _    _  _|   _  _
 #  | (_)\/(_)(_|\/| |(/_  v1.0.0
 #       /       /
+#
+# frozen_string_literal: true
 
 module Twilio
   module REST
@@ -13,50 +15,60 @@ module Twilio
         def initialize(domain)
           super
           @version = 'v1'
+          @usage_records = nil
           @commands = nil
           @rate_plans = nil
           @sims = nil
         end
 
         ##
-        # @param [String] sid The sid
+        # @return [Twilio::REST::Wireless::V1::UsageRecordContext]
+        def usage_records
+          @usage_records ||= UsageRecordList.new self
+        end
+
+        ##
+        # @param [String] sid The SID of the Command resource to fetch.
         # @return [Twilio::REST::Wireless::V1::CommandContext] if sid was passed.
         # @return [Twilio::REST::Wireless::V1::CommandList]
         def commands(sid=:unset)
           if sid.nil?
-            raise ArgumentError, 'sid cannot be nil'
-          elsif sid == :unset
-            @commands ||= CommandList.new self
+              raise ArgumentError, 'sid cannot be nil'
+          end
+          if sid == :unset
+              @commands ||= CommandList.new self
           else
-            CommandContext.new(self, sid)
+              CommandContext.new(self, sid)
           end
         end
 
         ##
-        # @param [String] sid The sid
+        # @param [String] sid The SID of the RatePlan resource to fetch.
         # @return [Twilio::REST::Wireless::V1::RatePlanContext] if sid was passed.
         # @return [Twilio::REST::Wireless::V1::RatePlanList]
         def rate_plans(sid=:unset)
           if sid.nil?
-            raise ArgumentError, 'sid cannot be nil'
-          elsif sid == :unset
-            @rate_plans ||= RatePlanList.new self
+              raise ArgumentError, 'sid cannot be nil'
+          end
+          if sid == :unset
+              @rate_plans ||= RatePlanList.new self
           else
-            RatePlanContext.new(self, sid)
+              RatePlanContext.new(self, sid)
           end
         end
 
         ##
-        # @param [String] sid The sid
+        # @param [String] sid The SID or the `unique_name` of the Sim resource to fetch.
         # @return [Twilio::REST::Wireless::V1::SimContext] if sid was passed.
         # @return [Twilio::REST::Wireless::V1::SimList]
         def sims(sid=:unset)
           if sid.nil?
-            raise ArgumentError, 'sid cannot be nil'
-          elsif sid == :unset
-            @sims ||= SimList.new self
+              raise ArgumentError, 'sid cannot be nil'
+          end
+          if sid == :unset
+              @sims ||= SimList.new self
           else
-            SimContext.new(self, sid)
+              SimContext.new(self, sid)
           end
         end
 

data/lib/twilio-ruby/rest/wireless.rb

@@ -3,6 +3,8 @@
 # \ / _    _  _|   _  _
 #  | (_)\/(_)(_|\/| |(/_  v1.0.0
 #       /       /
+#
+# frozen_string_literal: true
 
 module Twilio
   module REST
@@ -27,7 +29,14 @@ module Twilio
       end
 
       ##
-      # @param [String] sid The sid
+      # @return [Twilio::REST::Wireless::V1::UsageRecordInstance]
+      def usage_records
+        self.v1.usage_records()
+      end
+
+      ##
+      # @param [String] sid The unique string that we created to identify the Command
+      #   resource.
       # @return [Twilio::REST::Wireless::V1::CommandInstance] if sid was passed.
       # @return [Twilio::REST::Wireless::V1::CommandList]
       def commands(sid=:unset)
@@ -35,7 +44,8 @@ module Twilio
       end
 
       ##
-      # @param [String] sid The sid
+      # @param [String] sid The unique string that we created to identify the RatePlan
+      #   resource.
       # @return [Twilio::REST::Wireless::V1::RatePlanInstance] if sid was passed.
       # @return [Twilio::REST::Wireless::V1::RatePlanList]
       def rate_plans(sid=:unset)
@@ -43,7 +53,8 @@ module Twilio
       end
 
       ##
-      # @param [String] sid The sid
+      # @param [String] sid The unique string that we created to identify the Sim
+      #   resource.
       # @return [Twilio::REST::Wireless::V1::SimInstance] if sid was passed.
       # @return [Twilio::REST::Wireless::V1::SimList]
       def sims(sid=:unset)

data/lib/twilio-ruby/rest.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Dir[File.join(__dir__, 'framework/rest/*.rb')].sort.each do |file|
+  require file
+end
+
+Dir[File.join(__dir__, 'rest/*.rb')].sort.each do |file|
+  require file
+end
+
+Dir[File.join(__dir__, 'rest/**/*.rb')].sort.each do |file|
+  require file
+end

data/lib/twilio-ruby/security/request_validator.rb

@@ -1,21 +1,73 @@
+# frozen_string_literal: true
+
 module Twilio
   module Security
     class RequestValidator
+      ##
+      # Initialize a Request Validator. auth_token will either be grabbed from the global Twilio object or you can
+      # pass it in here.
+      #
+      # @param [String] auth_token Your account auth token, used to sign requests
       def initialize(auth_token = nil)
         @auth_token = auth_token || Twilio.auth_token
         raise ArgumentError, 'Auth token is required' if @auth_token.nil?
       end
 
+      ##
+      # Validates that after hashing a request with Twilio's request-signing algorithm
+      # (https://www.twilio.com/docs/usage/security#validating-requests), the hash matches the signature parameter
+      #
+      # @param [String] url The url sent to your server, including any query parameters
+      # @param [String, Hash, #to_unsafe_h] params In most cases, this is the POST parameters as a hash. If you received
+      #   a bodySHA256 parameter in the query string, this parameter can instead be the POST body as a string to
+      #   validate JSON or other text-based payloads that aren't x-www-form-urlencoded.
+      # @param [String] signature The expected signature, from the X-Twilio-Signature header of the request
+      #
+      # @return [Boolean] whether or not the computed signature matches the signature parameter
       def validate(url, params, signature)
-        params_hash = params_to_hash(params)
-        expected = build_signature_for(url, params_hash)
-        secure_compare(expected, signature)
+        parsed_url = URI(url)
+        url_with_port = add_port(parsed_url)
+        url_without_port = remove_port(parsed_url)
+
+        valid_body = true # default succeed, since body not always provided
+        params_hash = body_or_hash(params)
+        unless params_hash.is_a? Enumerable
+          body_hash = URI.decode_www_form(parsed_url.query).to_h['bodySHA256']
+          params_hash = build_hash_for(params)
+          valid_body = !(params_hash.nil? || body_hash.nil?) && secure_compare(params_hash, body_hash)
+          params_hash = {}
+        end
+
+        # Check signature of the url with and without port numbers
+        # since signature generation on the back end is inconsistent
+        valid_signature_with_port = secure_compare(build_signature_for(url_with_port, params_hash), signature)
+        valid_signature_without_port = secure_compare(build_signature_for(url_without_port, params_hash), signature)
+
+        valid_body && (valid_signature_with_port || valid_signature_without_port)
       end
 
+      ##
+      # Build a SHA256 hash for a body string
+      #
+      # @param [String] body String to hash
+      #
+      # @return [String] A hex-encoded SHA256 of the body string
+      def build_hash_for(body)
+        hasher = OpenSSL::Digest.new('sha256')
+        hasher.hexdigest(body)
+      end
+
+      ##
+      # Build a SHA1-HMAC signature for a url and parameter hash
+      #
+      # @param [String] url The request url, including any query parameters
+      # @param [#join] params The POST parameters
+      #
+      # @return [String] A base64 encoded SHA1-HMAC
       def build_signature_for(url, params)
         data = url + params.sort.join
         digest = OpenSSL::Digest.new('sha1')
-        Base64.encode64(OpenSSL::HMAC.digest(digest, @auth_token, data)).strip
+        Base64.strict_encode64(OpenSSL::HMAC.digest(digest, @auth_token, data))
       end
 
       private
@@ -42,13 +94,57 @@ module Twilio
       #
       # We use `to_unsafe_h` as `to_h` returns a hash of the permitted
       # parameters only and we need all the parameters to create the signature.
-      def params_to_hash(params)
-        if params.respond_to?(:to_unsafe_h)
-          params.to_unsafe_h
+      def body_or_hash(params_or_body)
+        if params_or_body.respond_to?(:to_unsafe_h)
+          params_or_body.to_unsafe_h
+        else
+          params_or_body
+        end
+      end
+
+      ##
+      # Adds the standard port to the url if it doesn't already have one
+      #
+      # @param [URI] parsed_url The parsed request url
+      #
+      # @return [String] The URL with a port number
+      def add_port(parsed_url)
+        if parsed_url.port.nil? || parsed_url.port == parsed_url.default_port
+          build_url_with_port_for(parsed_url)
         else
-          params
+          parsed_url.to_s
         end
       end
+
+      ##
+      # Removes the port from the url
+      #
+      # @param [URI] parsed_url The parsed request url
+      #
+      # @return [String] The URL without a port number
+      def remove_port(parsed_url)
+        parsed_url.port = nil
+        parsed_url.to_s
+      end
+
+      ##
+      # Builds the url from its component pieces, with the standard port
+      #
+      # @param [URI] parsed_url The parsed request url
+      #
+      # @return [String] The URL with the standard port number
+      def build_url_with_port_for(parsed_url)
+        url = ''
+
+        url += parsed_url.scheme ? "#{parsed_url.scheme}://" : ''
+        url += parsed_url.userinfo ? "#{parsed_url.userinfo}@" : ''
+        url += parsed_url.host ? "#{parsed_url.host}:#{parsed_url.port}" : ''
+        url += parsed_url.path
+        url += parsed_url.query ? "?#{parsed_url.query}" : ''
+        url += parsed_url.fragment ? "##{parsed_url.fragment}" : ''
+
+        url
+      end
     end
   end
 end

data/lib/twilio-ruby/twiml/fax_response.rb

@@ -3,6 +3,8 @@
 # \ / _    _  _|   _  _
 #  | (_)\/(_)(_|\/| |(/_  v1.0.0
 #       /       /
+#
+# frozen_string_literal: true
 
 module Twilio
   module TwiML
@@ -20,9 +22,12 @@ module Twilio
       # Create a new <Receive> element
       # action:: Receive action URL
       # method:: Receive action URL method
+      # media_type:: The media type used to store media in the fax media store
+      # page_size:: What size to interpret received pages as
+      # store_media:: Whether or not to store received media in the fax media store
       # keyword_args:: additional attributes
-      def receive(action: nil, method: nil, **keyword_args)
-        append(Receive.new(action: action, method: method, **keyword_args))
+      def receive(action: nil, method: nil, media_type: nil, page_size: nil, store_media: nil, **keyword_args)
+        append(Receive.new(action: action, method: method, media_type: media_type, page_size: page_size, store_media: store_media, **keyword_args))
       end
     end
 

data/lib/twilio-ruby/twiml/messaging_response.rb

@@ -3,6 +3,8 @@
 # \ / _    _  _|   _  _
 #  | (_)\/(_)(_|\/| |(/_  v1.0.0
 #       /       /
+#
+# frozen_string_literal: true
 
 module Twilio
   module TwiML
@@ -23,9 +25,10 @@ module Twilio
       # from:: Phone Number to send Message from
       # action:: Action URL
       # method:: Action URL Method
+      # status_callback:: Status callback URL. Deprecated in favor of action.
       # keyword_args:: additional attributes
-      def message(body: nil, to: nil, from: nil, action: nil, method: nil, **keyword_args)
-        message = Message.new(body: body, to: to, from: from, action: action, method: method, **keyword_args)
+      def message(body: nil, to: nil, from: nil, action: nil, method: nil, status_callback: nil, **keyword_args)
+        message = Message.new(body: body, to: to, from: from, action: action, method: method, status_callback: status_callback, **keyword_args)
 
         yield(message) if block_given?
         append(message)

data/lib/twilio-ruby/twiml/twiml.rb

@@ -1,26 +1,49 @@
 require 'nokogiri'
 
-##
-# This code was generated by
-# \ / _    _  _|   _  _
-#  | (_)\/(_)(_|\/| |(/_  v1.0.0
-#       /       /
-
 module Twilio
   module TwiML
+    autoload :FaxResponse, File.join(File.dirname(__FILE__), "fax_response.rb")
+    autoload :MessagingResponse, File.join(File.dirname(__FILE__), "messaging_response.rb")
+    autoload :VoiceResponse, File.join(File.dirname(__FILE__), "voice_response.rb")
+    
     class TwiMLError < StandardError; end
 
+    class LeafNode
+      def initialize(content)
+        @content = content
+      end
+    end
+
+    class Comment < LeafNode
+      def xml(document)
+        Nokogiri::XML::Comment.new(document, @content)
+      end
+    end
+
+    class Text < LeafNode
+      def xml(document)
+        Nokogiri::XML::Text.new(@content, document)
+      end
+    end
+
     class TwiML
         attr_accessor :name
 
         def initialize(**keyword_args)
+          @overrides = {
+              aliasAttribute: 'alias',
+              xmlLang: 'xml:lang',
+              interpretAs: 'interpret-as',
+              for_: 'for',
+          }
           @name = self.class.name.split('::').last
           @value = nil
           @verbs = []
           @attrs = {}
 
           keyword_args.each do |key, val|
-            @attrs[TwiML.to_lower_camel_case(key)] = val unless val.nil?
+            corrected_key = @overrides.fetch(key, TwiML.to_lower_camel_case(key))
+            @attrs[corrected_key] = val unless val.nil?
           end
         end
 
@@ -34,11 +57,14 @@ module Twilio
         end
 
         def to_s(xml_declaration = true)
-          opts = { encoding: 'UTF-8', indent: 0 }
+          save_opts = Nokogiri::XML::Node::SaveOptions::DEFAULT_XML
+          if !xml_declaration
+            save_opts = save_opts | Nokogiri::XML::Node::SaveOptions::NO_DECLARATION
+          end
+          opts = { encoding: 'UTF-8', indent: 0, save_with: save_opts }
           document = Nokogiri::XML::Document.new
-          xml = self.xml(document).to_xml(opts).gsub(/\n/, '')
-          return ('<?xml version="1.0" encoding="UTF-8"?>' + xml) if xml_declaration
-          xml
+          document << self.xml(document)
+          document.to_xml(opts)
         end
 
         def xml(document)
@@ -63,13 +89,38 @@ module Twilio
         end
 
         def append(verb)
-          raise TwiMLError, 'Only appending of TwiML is allowed' unless verb.is_a?(TwiML)
+          unless verb.is_a?(TwiML) || verb.is_a?(LeafNode)
+              raise TwiMLError, 'Only appending of TwiML is allowed'
+          end
 
           @verbs << verb
           self
         end
 
+        def comment(body)
+          append(Comment.new(body))
+        end
+
+        def add_text(content)
+          append(Text.new(content))
+        end
+
+        def add_child(name, value=nil, **keyword_args)
+          node = GenericNode.new(name, value, **keyword_args)
+
+          yield node if block_given?
+          append(node)
+        end
+
       alias to_xml to_s
     end
+
+    class GenericNode < TwiML
+      def initialize(name, value, **keyword_args)
+        super(**keyword_args)
+        @name = name
+        @value = value
+      end
+    end
   end
 end