telerivet 1.0.2

data/lib/telerivet/apicursor.rb

@@ -0,0 +1,156 @@
+module Telerivet
+
+#
+# An easy-to-use interface for interacting with API methods that return collections of objects
+# that may be split into multiple pages of results.
+# 
+# Using the APICursor, you can easily iterate over query results without
+# having to manually fetch each page of results.
+#
+class APICursor
+
+    include Enumerable
+
+    def initialize(api, item_cls, path, params = nil)
+        params ||= {}
+    
+        if params.has_key?('count')
+            raise Exception, "Cannot construct APICursor with 'count' parameter. Call the count() method instead."
+        end
+    
+        @api = api
+        @item_cls = item_cls
+        @path = path
+        @params = params
+        
+        @count = -1
+        @pos = nil
+        @data = nil
+        @truncated = nil
+        @next_marker = nil
+        @limit = nil
+        @offset = 0
+    end
+    
+    def each()
+        loop do
+            item = self.next()
+            return if item == nil               
+            yield item
+        end
+    end
+    
+    #
+    # Limits the maximum number of entities fetched by this query.
+    # 
+    # By default, iterating over the cursor will automatically fetch
+    # additional result pages as necessary. To prevent fetching more objects than you need, call
+    # this method to set the maximum number of objects retrieved from the API.
+    # 
+    # Arguments:
+    #   - limit (int)
+    #       * The maximum number of entities to fetch from the server (may require multiple API
+    #           calls if greater than 200)
+    #       * Required
+    #   
+    # Returns:
+    #     the current APICursor object
+    #
+    def limit(_limit)
+        @limit = _limit
+        self
+    end
+    
+    #
+    # Returns the total count of entities matching the current query, without actually fetching
+    # the entities themselves.
+    # 
+    # This is much more efficient than all() if you only need the count,
+    # as it only results in one API call, regardless of the number of entities matched by the
+    # query.
+    # 
+    # Returns:
+    #     int
+    #
+    def count()
+        if @count == -1
+            params = @params.clone
+            params['count'] = 1
+            
+            res = @api.do_request("GET", @path, params)
+            @count = res['count'].to_i
+        end
+        @count
+    end
+    
+    def all()
+        to_a
+    end
+
+    #
+    # Returns true if there are any more entities in the result set, false otherwise
+    # 
+    # Returns:
+    #     bool
+    #
+    def has_next?()
+        return false if @limit != nil && @offset >= @limit
+
+        load_next_page() if @data == nil
+            
+        return true if @pos < @data.length
+        
+        return false if !@truncated
+            
+        load_next_page()
+        
+        @pos < @data.length
+    end
+    
+    #
+    # Returns the next entity in the result set.
+    # 
+    # Returns:
+    #     Telerivet::Entity
+    #
+    def next()             
+        if @limit != nil && @offset >= @limit
+            return nil
+        end
+        
+        if @data == nil || (@pos >= @data.length && @truncated)
+            load_next_page()
+        end
+        
+        if @pos < @data.length
+            item_data = @data[@pos]
+            @pos += 1
+            @offset += 1
+            cls = @item_cls
+            return cls.new(@api, item_data, true)
+        else
+            return nil
+        end
+    end
+
+    def load_next_page()
+        request_params = @params.clone
+                
+        if @next_marker != nil
+            request_params['marker'] = @next_marker
+        end
+        
+        if @limit != nil && !request_params.has_key?("page_size")
+            request_params['page_size'] = [@limit, 200].min
+        end
+        
+        response = @api.do_request("GET", @path, request_params)
+        
+        @data = response['data']
+        @truncated = response['truncated']
+        @next_marker = response['next_marker']
+        @pos = 0
+    end
+end
+
+end

data/lib/telerivet/contact.rb

@@ -0,0 +1,403 @@
+module Telerivet
+
+#
+# Fields:
+# 
+#   - id (string, max 34 characters)
+#       * ID of the contact
+#       * Read-only
+#   
+#   - name
+#       * Name of the contact
+#       * Updatable via API
+#   
+#   - phone_number (string)
+#       * Phone number of the contact
+#       * Updatable via API
+#   
+#   - time_created (UNIX timestamp)
+#       * Time the contact was added in Telerivet
+#       * Read-only
+#   
+#   - last_message_time (UNIX timestamp)
+#       * Last time the contact sent or received a message (null if no messages have been sent
+#           or received)
+#       * Read-only
+#   
+#   - last_message_id
+#       * ID of the last message sent or received by this contact (null if no messages have
+#           been sent or received)
+#       * Read-only
+#   
+#   - default_route_id
+#       * ID of the phone or route that Telerivet will use by default to send messages to this
+#           contact (null if using project default route)
+#       * Updatable via API
+#   
+#   - group_ids (array of strings)
+#       * List of IDs of groups that this contact belongs to
+#       * Read-only
+#   
+#   - vars (Hash)
+#       * Custom variables stored for this contact
+#       * Updatable via API
+#   
+#   - project_id
+#       * ID of the project this contact belongs to
+#       * Read-only
+#
+class Contact < Entity
+
+    #
+    # Returns true if this contact is in a particular group, false otherwise.
+    # 
+    # Arguments:
+    #   - group (Telerivet::Group)
+    #       * Required
+    #   
+    # Returns:
+    #     bool
+    #
+    def is_in_group?(group)
+        load_data()
+        return @group_ids_set.has_key?(group.id)
+    end
+      
+    #
+    # Adds this contact to a group.
+    # 
+    # Arguments:
+    #   - group (Telerivet::Group)
+    #       * Required
+    #
+    def add_to_group(group)
+        @api.do_request("PUT", group.get_base_api_path() + "/contacts/" + get('id'));
+        @group_ids_set[group.id] = true
+    end
+    
+    #
+    # Removes this contact from a group.
+    # 
+    # Arguments:
+    #   - group (Telerivet::Group)
+    #       * Required
+    #
+    def remove_from_group(group)
+        @api.do_request("DELETE", group.get_base_api_path() + "/contacts/" + get('id'))
+        if @group_ids_set.has_key?(group.id)
+            @group_ids_set.delete(group.id)
+        end
+    end
+
+    #
+    # Queries messages sent or received by this contact.
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #     
+    #     - direction
+    #         * Filter messages by direction
+    #         * Allowed values: incoming, outgoing
+    #     
+    #     - message_type
+    #         * Filter messages by message_type
+    #         * Allowed values: sms, mms, ussd, call
+    #     
+    #     - source
+    #         * Filter messages by source
+    #         * Allowed values: phone, provider, web, api, service, webhook, scheduled
+    #     
+    #     - starred (bool)
+    #         * Filter messages by starred/unstarred
+    #     
+    #     - status
+    #         * Filter messages by status
+    #         * Allowed values: ignored, processing, received, sent, queued, failed,
+    #             failed_queued, cancelled, delivered, not_delivered
+    #     
+    #     - time_created[min] (UNIX timestamp)
+    #         * Filter messages created on or after a particular time
+    #     
+    #     - time_created[max] (UNIX timestamp)
+    #         * Filter messages created before a particular time
+    #     
+    #     - contact_id
+    #         * ID of the contact who sent/received the message
+    #     
+    #     - phone_id
+    #         * ID of the phone that sent/received the message
+    #     
+    #     - sort
+    #         * Sort the results based on a field
+    #         * Allowed values: default
+    #         * Default: default
+    #     
+    #     - sort_dir
+    #         * Sort the results in ascending or descending order
+    #         * Allowed values: asc, desc
+    #         * Default: asc
+    #     
+    #     - page_size (int)
+    #         * Number of results returned per page (max 200)
+    #         * Default: 50
+    #     
+    #     - offset (int)
+    #         * Number of items to skip from beginning of result set
+    #         * Default: 0
+    #   
+    # Returns:
+    #     Telerivet::APICursor (of Telerivet::Message)
+    #
+    def query_messages(options = nil)
+        require_relative 'message'
+        @api.cursor(Message, get_base_api_path() + "/messages", options)
+    end
+
+    #
+    # Queries groups for which this contact is a member.
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #     
+    #     - name
+    #         * Filter groups by name
+    #         * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
+    #             name[lt], name[lte]
+    #     
+    #     - sort
+    #         * Sort the results based on a field
+    #         * Allowed values: default, name
+    #         * Default: default
+    #     
+    #     - sort_dir
+    #         * Sort the results in ascending or descending order
+    #         * Allowed values: asc, desc
+    #         * Default: asc
+    #     
+    #     - page_size (int)
+    #         * Number of results returned per page (max 200)
+    #         * Default: 50
+    #     
+    #     - offset (int)
+    #         * Number of items to skip from beginning of result set
+    #         * Default: 0
+    #   
+    # Returns:
+    #     Telerivet::APICursor (of Telerivet::Group)
+    #
+    def query_groups(options = nil)
+        require_relative 'group'
+        @api.cursor(Group, get_base_api_path() + "/groups", options)
+    end
+
+    #
+    # Queries messages scheduled to this contact (not including messages scheduled to groups that
+    # this contact is a member of)
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #     
+    #     - message_type
+    #         * Filter scheduled messages by message_type
+    #         * Allowed values: sms, mms, ussd, call
+    #     
+    #     - time_created (UNIX timestamp)
+    #         * Filter scheduled messages by time_created
+    #         * Allowed modifiers: time_created[ne], time_created[min], time_created[max]
+    #     
+    #     - next_time (UNIX timestamp)
+    #         * Filter scheduled messages by next_time
+    #         * Allowed modifiers: next_time[exists], next_time[ne], next_time[min],
+    #             next_time[max]
+    #     
+    #     - sort
+    #         * Sort the results based on a field
+    #         * Allowed values: default, name
+    #         * Default: default
+    #     
+    #     - sort_dir
+    #         * Sort the results in ascending or descending order
+    #         * Allowed values: asc, desc
+    #         * Default: asc
+    #     
+    #     - page_size (int)
+    #         * Number of results returned per page (max 200)
+    #         * Default: 50
+    #     
+    #     - offset (int)
+    #         * Number of items to skip from beginning of result set
+    #         * Default: 0
+    #   
+    # Returns:
+    #     Telerivet::APICursor (of Telerivet::ScheduledMessage)
+    #
+    def query_scheduled_messages(options = nil)
+        require_relative 'scheduledmessage'
+        @api.cursor(ScheduledMessage, get_base_api_path() + "/scheduled", options)
+    end
+
+    #
+    # Queries data rows associated with this contact (in any data table).
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #     
+    #     - time_created (UNIX timestamp)
+    #         * Filter data rows by the time they were created
+    #         * Allowed modifiers: time_created[ne], time_created[min], time_created[max]
+    #     
+    #     - vars (Hash)
+    #         * Filter data rows by value of a custom variable (e.g. vars[q1], vars[foo], etc.)
+    #         * Allowed modifiers: vars[foo][exists], vars[foo][ne], vars[foo][prefix],
+    #             vars[foo][not_prefix], vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte],
+    #             vars[foo][min], vars[foo][max]
+    #     
+    #     - sort
+    #         * Sort the results based on a field
+    #         * Allowed values: default
+    #         * Default: default
+    #     
+    #     - sort_dir
+    #         * Sort the results in ascending or descending order
+    #         * Allowed values: asc, desc
+    #         * Default: asc
+    #     
+    #     - page_size (int)
+    #         * Number of results returned per page (max 200)
+    #         * Default: 50
+    #     
+    #     - offset (int)
+    #         * Number of items to skip from beginning of result set
+    #         * Default: 0
+    #   
+    # Returns:
+    #     Telerivet::APICursor (of Telerivet::DataRow)
+    #
+    def query_data_rows(options = nil)
+        require_relative 'datarow'
+        @api.cursor(DataRow, get_base_api_path() + "/rows", options)
+    end
+
+    #
+    # Queries this contact's current states for any service
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #     
+    #     - id
+    #         * Filter states by id
+    #         * Allowed modifiers: id[ne], id[prefix], id[not_prefix], id[gte], id[gt], id[lt],
+    #             id[lte]
+    #     
+    #     - vars (Hash)
+    #         * Filter states by value of a custom variable (e.g. vars[email], vars[foo], etc.)
+    #         * Allowed modifiers: vars[foo][exists], vars[foo][ne], vars[foo][prefix],
+    #             vars[foo][not_prefix], vars[foo][gte], vars[foo][gt], vars[foo][lt], vars[foo][lte],
+    #             vars[foo][min], vars[foo][max]
+    #     
+    #     - sort
+    #         * Sort the results based on a field
+    #         * Allowed values: default
+    #         * Default: default
+    #     
+    #     - sort_dir
+    #         * Sort the results in ascending or descending order
+    #         * Allowed values: asc, desc
+    #         * Default: asc
+    #     
+    #     - page_size (int)
+    #         * Number of results returned per page (max 200)
+    #         * Default: 50
+    #     
+    #     - offset (int)
+    #         * Number of items to skip from beginning of result set
+    #         * Default: 0
+    #   
+    # Returns:
+    #     Telerivet::APICursor (of Telerivet::ContactServiceState)
+    #
+    def query_service_states(options = nil)
+        require_relative 'contactservicestate'
+        @api.cursor(ContactServiceState, get_base_api_path() + "/states", options)
+    end
+
+    #
+    # Saves any fields or custom variables that have changed for this contact.
+    #
+    def save()
+        super
+    end
+
+    #
+    # Deletes this contact.
+    #
+    def delete()
+        @api.do_request("DELETE", get_base_api_path())
+    end
+
+    def id
+        get('id')
+    end
+
+    def name
+        get('name')
+    end
+
+    def name=(value)
+        set('name', value)
+    end
+
+    def phone_number
+        get('phone_number')
+    end
+
+    def phone_number=(value)
+        set('phone_number', value)
+    end
+
+    def time_created
+        get('time_created')
+    end
+
+    def last_message_time
+        get('last_message_time')
+    end
+
+    def last_message_id
+        get('last_message_id')
+    end
+
+    def default_route_id
+        get('default_route_id')
+    end
+
+    def default_route_id=(value)
+        set('default_route_id', value)
+    end
+
+    def group_ids
+        get('group_ids')
+    end
+
+    def project_id
+        get('project_id')
+    end
+
+    def get_base_api_path()
+        "/projects/#{get('project_id')}/contacts/#{get('id')}"
+    end
+ 
+    
+    def set_data(data)
+        super
+        
+        @group_ids_set = {}
+        
+        if data.has_key?('group_ids')
+            data['group_ids'].each { |id| @group_ids_set[id] = true }
+        end
+    end
+
+end
+
+end

data/lib/telerivet/contactservicestate.rb

@@ -0,0 +1,108 @@
+
+module Telerivet
+
+#
+# Represents the current state of a particular contact for a particular Telerivet service.
+# 
+# Some automated services (including polls) are 'stateful'. For polls,
+# Telerivet needs to keep track of which question the contact is currently answering, and
+# stores store the ID of each contact's current question (e.g. 'q1' or 'q2') as the ID of the
+# contact's state for the poll service. Any type of conversation-like service will also need
+# to store state for each contact.
+# 
+# For this type of entity, the 'id' field is NOT a read-only unique ID (unlike
+# all other types of entities). Instead it is an arbitrary string that identifies the
+# contact's current state within your poll/conversation; many contacts may have the same state
+# ID, and it may change over time. Additional custom fields may be stored in the 'vars'.
+# 
+# Initially, the state 'id' for any contact is null. When saving the state,
+# setting the 'id' to null is equivalent to resetting the state (so all 'vars' will be
+# deleted); if you want to save custom variables, the state 'id' must be non-null.
+# 
+# Many Telerivet services are stateless, such as auto-replies or keyword-based
+# services where the behavior only depends on the current message, and not any previous
+# messages sent by the same contact. Telerivet doesn't store any state for contacts that
+# interact with stateless services.
+# 
+# Fields:
+# 
+#   - id (string, max 63 characters)
+#       * Arbitrary string representing the contact's current state for this service, e.g.
+#           'q1', 'q2', etc.
+#       * Updatable via API
+#   
+#   - contact_id
+#       * ID of the contact
+#       * Read-only
+#   
+#   - service_id
+#       * ID of the service
+#       * Read-only
+#   
+#   - vars (Hash)
+#       * Custom variables stored for this contact/service state
+#       * Updatable via API
+#   
+#   - time_created (UNIX timestamp)
+#       * Time the state was first created in Telerivet
+#       * Read-only
+#   
+#   - time_updated (UNIX timestamp)
+#       * Time the state was last updated in Telerivet
+#       * Read-only
+#   
+#   - project_id
+#       * ID of the project this contact/service state belongs to
+#       * Read-only
+#
+class ContactServiceState < Entity
+    #
+    # Saves the state id and any custom variables for this contact. If the state id is null, this
+    # is equivalent to calling reset().
+    #
+    def save()
+        super
+    end
+
+    #
+    # Resets the state for this contact for this service.
+    #
+    def reset()
+        @api.do_request("DELETE", get_base_api_path())
+    end
+
+    def id
+        get('id')
+    end
+
+    def id=(value)
+        set('id', value)
+    end
+
+    def contact_id
+        get('contact_id')
+    end
+
+    def service_id
+        get('service_id')
+    end
+
+    def time_created
+        get('time_created')
+    end
+
+    def time_updated
+        get('time_updated')
+    end
+
+    def project_id
+        get('project_id')
+    end
+
+    def get_base_api_path()
+        "/projects/#{get('project_id')}/services/#{get('service_id')}/states/#{get('contact_id')}"
+    end
+ 
+end
+
+end