telerivet 1.0.2

data/lib/telerivet/datarow.rb

@@ -0,0 +1,91 @@
+
+module Telerivet
+
+#
+# Represents a row in a custom data table.
+# 
+# For example, each response to a poll is stored as one row in a data table.
+# If a poll has a question with ID 'q1', the verbatim response to that question would be
+# stored in row.vars.q1, and the response code would be stored in row.vars.q1_code.
+# 
+# Each custom variable name within a data row corresponds to a different
+# column/field of the data table.
+# 
+# Fields:
+# 
+#   - id (string, max 34 characters)
+#       * ID of the data row
+#       * Read-only
+#   
+#   - contact_id
+#       * ID of the contact this row is associated with (or null if not associated with any
+#           contact)
+#       * Updatable via API
+#   
+#   - from_number (string)
+#       * Phone number that this row is associated with (or null if not associated with any
+#           phone number)
+#       * Updatable via API
+#   
+#   - vars (Hash)
+#       * Custom variables stored for this data row
+#       * Updatable via API
+#   
+#   - table_id
+#       * ID of the table this data row belongs to
+#       * Read-only
+#   
+#   - project_id
+#       * ID of the project this data row belongs to
+#       * Read-only
+#
+class DataRow < Entity
+    #
+    # Saves any fields or custom variables that have changed for this data row.
+    #
+    def save()
+        super
+    end
+
+    #
+    # Deletes this data row.
+    #
+    def delete()
+        @api.do_request("DELETE", get_base_api_path())
+    end
+
+    def id
+        get('id')
+    end
+
+    def contact_id
+        get('contact_id')
+    end
+
+    def contact_id=(value)
+        set('contact_id', value)
+    end
+
+    def from_number
+        get('from_number')
+    end
+
+    def from_number=(value)
+        set('from_number', value)
+    end
+
+    def table_id
+        get('table_id')
+    end
+
+    def project_id
+        get('project_id')
+    end
+
+    def get_base_api_path()
+        "/projects/#{get('project_id')}/tables/#{get('table_id')}/rows/#{get('id')}"
+    end
+ 
+end
+
+end

data/lib/telerivet/datatable.rb

@@ -0,0 +1,191 @@
+
+module Telerivet
+
+#
+# Represents a custom data table that can store arbitrary rows.
+# 
+# For example, poll services use data tables to store a row for each response.
+# 
+# 
+# DataTables are schemaless -- each row simply stores custom variables. Each
+# variable name is equivalent to a different "column" of the data table.
+# Telerivet refers to these variables/columns as "fields", and automatically
+# creates a new field for each variable name used in a row of the table.
+# 
+# Fields:
+# 
+#   - id (string, max 34 characters)
+#       * ID of the data table
+#       * Read-only
+#   
+#   - name
+#       * Name of the data table
+#       * Updatable via API
+#   
+#   - num_rows (int)
+#       * Number of rows in the table
+#       * Read-only
+#   
+#   - vars (Hash)
+#       * Custom variables stored for this data table
+#       * Updatable via API
+#   
+#   - project_id
+#       * ID of the project this data table belongs to
+#       * Read-only
+#
+class DataTable < Entity
+    #
+    # Queries rows in this 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_rows(options = nil)
+        require_relative 'datarow'
+        @api.cursor(DataRow, get_base_api_path() + "/rows", options)
+    end
+
+    #
+    # Adds a new row to this data table.
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #     
+    #     - contact_id
+    #         * ID of the contact that this row is associated with (if applicable)
+    #     
+    #     - from_number (string)
+    #         * Phone number that this row is associated with (if applicable)
+    #     
+    #     - vars
+    #         * Custom variables and values to set for this data row
+    #   
+    # Returns:
+    #     Telerivet::DataRow
+    #
+    def create_row(options = nil)
+        require_relative 'datarow'
+        DataRow.new(@api, @api.do_request("POST", get_base_api_path() + "/rows", options))
+    end
+
+    #
+    # Retrieves the row in the given table with the given ID.
+    # 
+    # Note: This does not make any API requests until you access a property of the DataRow.
+    # 
+    # Arguments:
+    #   - id
+    #       * ID of the row
+    #       * Required
+    #   
+    # Returns:
+    #     Telerivet::DataRow
+    #
+    def get_row_by_id(id)
+        require_relative 'datarow'
+        return DataRow.new(@api, {'project_id' => self.project_id, 'table_id' => self.id, 'id' => id}, false)
+    end
+
+    #
+    # Gets a list of all fields (columns) defined for this data table. The return value is an
+    # array of objects with the properties 'name' and 'variable'. (Fields are automatically
+    # created any time a DataRow's 'vars' property is updated.)
+    # 
+    # Returns:
+    #     array
+    #
+    def get_fields()
+        return @api.do_request("GET", get_base_api_path() + "/fields")
+    end
+
+    #
+    # Returns the number of rows for each value of a given variable. This can be used to get the
+    # total number of responses for each choice in a poll, without making a separate query for
+    # each response choice. The return value is an object mapping values to row counts, e.g.
+    # `{"yes":7,"no":3}`
+    # 
+    # Arguments:
+    #   - variable
+    #       * Variable of field to count by.
+    #       * Required
+    #   
+    # Returns:
+    #     object
+    #
+    def count_rows_by_value(variable)
+        return @api.do_request("GET", get_base_api_path() + "/count_rows_by_value", {'variable' => variable})
+    end
+
+    #
+    # Saves any fields that have changed for this data table.
+    #
+    def save()
+        super
+    end
+
+    #
+    # Permanently deletes the given data table, including all its rows
+    #
+    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 num_rows
+        get('num_rows')
+    end
+
+    def project_id
+        get('project_id')
+    end
+
+    def get_base_api_path()
+        "/projects/#{get('project_id')}/tables/#{get('id')}"
+    end
+ 
+end
+
+end

data/lib/telerivet/entity.rb

@@ -0,0 +1,124 @@
+module Telerivet
+
+class Entity    
+    
+    def initialize(api, data, is_loaded = true)
+        @api = api
+        @vars = nil
+        @dirty = {}
+        @data = {}
+        set_data(data)
+        @is_loaded = is_loaded        
+    end
+    
+    def set_data(data)
+        @data = data
+        
+        if data.has_key?('vars')
+            @vars = CustomVars.new(data['vars'])
+        else
+            @vars = CustomVars.new({})
+        end
+    end
+    
+    def load_data()    
+        if !@is_loaded
+            @is_loaded = true
+            set_data(@api.do_request('GET', get_base_api_path()))
+        end
+    end
+        
+    def vars
+        @vars
+    end
+        
+    def get(name)        
+        if @data.has_key?(name)
+            return @data[name]
+        elsif @is_loaded
+            return nil
+        end
+
+        load_data()
+        
+        return @data[name]
+    end
+    
+    def set(name, value)
+        if !@is_loaded
+            loadData()
+        end
+        
+        @data[name] = value
+        @dirty[name] = value
+    end
+    
+    def save()    
+        dirty_props = @dirty
+
+        if @vars != nil
+            dirty_vars = @vars.get_dirty_variables()
+            @dirty['vars'] = dirty_vars if dirty_vars.length() > 0
+        end
+            
+        @api.do_request('POST', get_base_api_path(), @dirty)
+        @dirty = {}
+        
+        @vars.clear_dirty_variables() if @vars != nil
+    end
+    
+    def to_s()
+        res = self.class.name
+        
+        if not @is_loaded
+            res += " (not loaded)"
+        end
+
+        res += " JSON: " + JSON.dump(@data)
+        
+        return res
+    end
+    
+    def get_base_api_path()
+        abstract
+    end
+end
+
+class CustomVars
+    def initialize(vars)
+        @vars = vars
+        @dirty = {}
+    end
+    
+    def all()
+        @vars
+    end
+    
+    def get_dirty_variables()
+        @dirty
+    end
+    
+    def clear_dirty_variables()
+        @dirty = {}
+    end
+
+    def get(name)
+        @vars[name]
+    end
+    
+    def set(name, value)
+        @vars[name] = value
+        @dirty[name] = value
+    end
+    
+    def method_missing(m, *args)
+        name = m.to_s
+        if name.end_with?('=')
+            set(name.chop, args[0])
+        else
+            get(name)
+        end
+    end  
+end
+
+end

data/lib/telerivet/group.rb

@@ -0,0 +1,181 @@
+
+module Telerivet
+
+#
+# Represents a group used to organize contacts within Telerivet.
+# 
+# Fields:
+# 
+#   - id (string, max 34 characters)
+#       * ID of the group
+#       * Read-only
+#   
+#   - name
+#       * Name of the group
+#       * Updatable via API
+#   
+#   - num_members (int)
+#       * Number of contacts in the group
+#       * Read-only
+#   
+#   - time_created (UNIX timestamp)
+#       * Time the group was created in Telerivet
+#       * Read-only
+#   
+#   - vars (Hash)
+#       * Custom variables stored for this group
+#       * Updatable via API
+#   
+#   - project_id
+#       * ID of the project this group belongs to
+#       * Read-only
+#
+class Group < Entity
+    #
+    # Queries contacts that are members of the given group.
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #     
+    #     - name
+    #         * Filter contacts by name
+    #         * Allowed modifiers: name[ne], name[prefix], name[not_prefix], name[gte], name[gt],
+    #             name[lt], name[lte]
+    #     
+    #     - phone_number
+    #         * Filter contacts by phone number
+    #         * Allowed modifiers: phone_number[ne], phone_number[prefix],
+    #             phone_number[not_prefix], phone_number[gte], phone_number[gt], phone_number[lt],
+    #             phone_number[lte]
+    #     
+    #     - time_created (UNIX timestamp)
+    #         * Filter contacts by time created
+    #         * Allowed modifiers: time_created[ne], time_created[min], time_created[max]
+    #     
+    #     - last_message_time (UNIX timestamp)
+    #         * Filter contacts by last time a message was sent or received
+    #         * Allowed modifiers: last_message_time[exists], last_message_time[ne],
+    #             last_message_time[min], last_message_time[max]
+    #     
+    #     - vars (Hash)
+    #         * Filter contacts 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, name, phone_number, last_message_time
+    #         * 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::Contact)
+    #
+    def query_contacts(options = nil)
+        require_relative 'contact'
+        @api.cursor(Contact, get_base_api_path() + "/contacts", options)
+    end
+
+    #
+    # Queries scheduled messages to the given group.
+    # 
+    # 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
+
+    #
+    # Saves any fields that have changed for this group.
+    #
+    def save()
+        super
+    end
+
+    #
+    # Deletes this group (Note: no contacts are deleted.)
+    #
+    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 num_members
+        get('num_members')
+    end
+
+    def time_created
+        get('time_created')
+    end
+
+    def project_id
+        get('project_id')
+    end
+
+    def get_base_api_path()
+        "/projects/#{get('project_id')}/groups/#{get('id')}"
+    end
+ 
+end
+
+end

data/lib/telerivet/label.rb

@@ -0,0 +1,134 @@
+
+module Telerivet
+
+#
+# Represents a label used to organize messages within Telerivet.
+# 
+# Fields:
+# 
+#   - id (string, max 34 characters)
+#       * ID of the label
+#       * Read-only
+#   
+#   - name
+#       * Name of the label
+#       * Updatable via API
+#   
+#   - time_created (UNIX timestamp)
+#       * Time the label was created in Telerivet
+#       * Read-only
+#   
+#   - vars (Hash)
+#       * Custom variables stored for this label
+#       * Updatable via API
+#   
+#   - project_id
+#       * ID of the project this label belongs to
+#       * Read-only
+#
+class Label < Entity
+    #
+    # Queries messages with the given label.
+    # 
+    # 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
+
+    #
+    # Saves any fields that have changed for the label.
+    #
+    def save()
+        super
+    end
+
+    #
+    # Deletes the given label (Note: no messages are deleted.)
+    #
+    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 time_created
+        get('time_created')
+    end
+
+    def project_id
+        get('project_id')
+    end
+
+    def get_base_api_path()
+        "/projects/#{get('project_id')}/labels/#{get('id')}"
+    end
+ 
+end
+
+end