telerivet 1.0.2

data/lib/telerivet/scheduledmessage.rb

@@ -0,0 +1,185 @@
+
+module Telerivet
+
+#
+# Represents a scheduled message within Telerivet.
+# 
+# Fields:
+# 
+#   - id (string, max 34 characters)
+#       * ID of the scheduled message
+#       * Read-only
+#   
+#   - content
+#       * Text content of the scheduled message
+#       * Read-only
+#   
+#   - rrule
+#       * Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or
+#           'FREQ=WEEKLY;INTERVAL=2'; see <https://tools.ietf.org/html/rfc2445#section-4.3.10>
+#       * Read-only
+#   
+#   - timezone_id
+#       * Timezone ID used to compute times for recurring messages; see
+#           <http://en.wikipedia.org/wiki/List_of_tz_database_time_zones>
+#       * Read-only
+#   
+#   - group_id
+#       * ID of the group to send the message to (null if scheduled to an individual contact)
+#       * Read-only
+#   
+#   - contact_id
+#       * ID of the contact to send the message to (null if scheduled to a group)
+#       * Read-only
+#   
+#   - to_number
+#       * Phone number to send the message to (null if scheduled to a group)
+#       * Read-only
+#   
+#   - route_id
+#       * ID of the phone or route to the message will be sent from
+#       * Read-only
+#   
+#   - message_type
+#       * Type of scheduled message
+#       * Allowed values: sms, ussd
+#       * Read-only
+#   
+#   - time_created (UNIX timestamp)
+#       * Time the scheduled message was created in Telerivet
+#       * Read-only
+#   
+#   - start_time (UNIX timestamp)
+#       * The time that the message will be sent (or first sent for recurring messages)
+#       * Read-only
+#   
+#   - end_time (UNIX timestamp)
+#       * Time after which a recurring message will stop (not applicable to non-recurring
+#           scheduled messages)
+#       * Read-only
+#   
+#   - prev_time (UNIX timestamp)
+#       * The most recent time that Telerivet has sent this scheduled message (null if it has
+#           never been sent)
+#       * Read-only
+#   
+#   - next_time (UNIX timestamp)
+#       * The next upcoming time that Telerivet will sent this scheduled message (null if it
+#           will not be sent again)
+#       * Read-only
+#   
+#   - occurrences (int)
+#       * Number of times this scheduled message has already been sent
+#       * Read-only
+#   
+#   - is_template
+#       * Set to true if Telerivet will render variables like [[contact.name]] in the message
+#           content, false otherwise
+#       * Read-only
+#   
+#   - vars (Hash)
+#       * Custom variables stored for this scheduled message (copied to Message when sent)
+#       * Updatable via API
+#   
+#   - label_ids (array)
+#       * IDs of labels to add to the Message
+#       * Read-only
+#   
+#   - project_id
+#       * ID of the project this scheduled message belongs to
+#       * Read-only
+#
+class ScheduledMessage < Entity
+    #
+    # Saves any fields or custom variables that have changed for this scheduled message.
+    #
+    def save()
+        super
+    end
+
+    #
+    # Cancels this scheduled message.
+    #
+    def delete()
+        @api.do_request("DELETE", get_base_api_path())
+    end
+
+    def id
+        get('id')
+    end
+
+    def content
+        get('content')
+    end
+
+    def rrule
+        get('rrule')
+    end
+
+    def timezone_id
+        get('timezone_id')
+    end
+
+    def group_id
+        get('group_id')
+    end
+
+    def contact_id
+        get('contact_id')
+    end
+
+    def to_number
+        get('to_number')
+    end
+
+    def route_id
+        get('route_id')
+    end
+
+    def message_type
+        get('message_type')
+    end
+
+    def time_created
+        get('time_created')
+    end
+
+    def start_time
+        get('start_time')
+    end
+
+    def end_time
+        get('end_time')
+    end
+
+    def prev_time
+        get('prev_time')
+    end
+
+    def next_time
+        get('next_time')
+    end
+
+    def occurrences
+        get('occurrences')
+    end
+
+    def is_template
+        get('is_template')
+    end
+
+    def label_ids
+        get('label_ids')
+    end
+
+    def project_id
+        get('project_id')
+    end
+
+    def get_base_api_path()
+        "/projects/#{get('project_id')}/scheduled/#{get('id')}"
+    end
+ 
+end
+
+end

data/lib/telerivet/service.rb

@@ -0,0 +1,296 @@
+module Telerivet
+
+#
+# Represents an automated service on Telerivet, for example a poll, auto-reply, webhook
+# service, etc.
+# 
+# A service, generally, defines some automated behavior that can be
+# invoked/triggered in a particular context, and may be invoked either manually or when a
+# particular event occurs.
+# 
+# Most commonly, services work in the context of a particular message, when
+# the message is originally received by Telerivet.
+# 
+# Fields:
+# 
+#   - id (string, max 34 characters)
+#       * ID of the service
+#       * Read-only
+#   
+#   - name
+#       * Name of the service
+#       * Updatable via API
+#   
+#   - active (bool)
+#       * Whether the service is active or inactive. Inactive services are not automatically
+#           triggered and cannot be invoked via the API.
+#       * Updatable via API
+#   
+#   - priority (int)
+#       * A number that determines the order that services are triggered when a particular
+#           event occurs (smaller numbers are triggered first). Any service can determine whether
+#           or not execution "falls-through" to subsequent services (with larger priority values)
+#           by setting the return_value variable within Telerivet's Rules Engine.
+#       * Updatable via API
+#   
+#   - contexts (Hash)
+#       * A key/value map where the keys are the names of contexts supported by this service
+#           (e.g. message, contact), and the values are themselves key/value maps where the keys
+#           are event names and the values are all true. (This structure makes it easy to test
+#           whether a service can be invoked for a particular context and event.)
+#       * Read-only
+#   
+#   - vars (Hash)
+#       * Custom variables stored for this service
+#       * Updatable via API
+#   
+#   - project_id
+#       * ID of the project this service belongs to
+#       * Read-only
+#   
+#   - label_id
+#       * ID of the label containing messages sent or received by this service (currently only
+#           used for polls)
+#       * Read-only
+#   
+#   - response_table_id
+#       * ID of the data table where responses to this service will be stored (currently only
+#           used for polls)
+#       * Read-only
+#   
+#   - sample_group_id
+#       * ID of the group containing contacts that have been invited to interact with this
+#           service (currently only used for polls)
+#       * Read-only
+#   
+#   - respondent_group_id
+#       * ID of the group containing contacts that have completed an interaction with this
+#           service (currently only used for polls)
+#       * Read-only
+#
+class Service < Entity
+
+    #
+    # Manually invoke this service in a particular context.
+    # 
+    # For example, to send a poll to a particular contact (or resend the
+    # current question), you can invoke the poll service with context=contact, and contact_id as
+    # the ID of the contact to send the poll to.
+    # 
+    # Or, to manually apply a service for an incoming message, you can
+    # invoke the service with context=message, event=incoming\_message, and message_id as the ID
+    # of the incoming message. (This is normally not necessary, but could be used if you want to
+    # override Telerivet's standard priority-ordering of services.)
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #       * Required
+    #     
+    #     - context
+    #         * The name of the context in which this service is invoked
+    #         * Allowed values: message, contact, project, receipt
+    #         * Required
+    #     
+    #     - event
+    #         * The name of the event that is triggered (must be supported by this service)
+    #         * Default: default
+    #     
+    #     - message_id
+    #         * The ID of the message this service is triggered for
+    #         * Required if context is 'message'
+    #     
+    #     - contact_id
+    #         * The ID of the contact this service is triggered for
+    #         * Required if context is 'contact'
+    #
+    def invoke(options)        
+        invoke_result = @api.do_request('POST', get_base_api_path() + '/invoke', options)
+        
+        if invoke_result.has_key?('sent_messages')
+            require_relative 'message'
+        
+            sent_messages = []
+            
+            invoke_result['sent_messages'].each { |sent_message_data|
+                sent_messages.push(Message.new(@api, sent_message_data))
+            }
+            
+            invoke_result['sent_messages'] = sent_messages
+        end
+            
+        return invoke_result
+    end
+    
+    #
+    # Gets the current state for a particular contact for this service.
+    # 
+    # If the contact doesn't already have a state, this method will return
+    # a valid state object with id=null. However this object would not be returned by
+    # queryContactStates() unless it is saved with a non-null state id.
+    # 
+    # Arguments:
+    #   - contact (Telerivet::Contact)
+    #       * The contact whose state you want to retrieve.
+    #       * Required
+    #   
+    # Returns:
+    #     Telerivet::ContactServiceState
+    #
+    def get_contact_state(contact)
+        require_relative 'contactservicestate'
+        ContactServiceState.new(@api, @api.do_request('GET', get_base_api_path() + '/states/' + contact.id))
+    end
+
+    #
+    # Initializes or updates the current state for a particular contact for the given service. If
+    # the state id is null, the contact's state will be reset.
+    # 
+    # Arguments:
+    #   - contact (Telerivet::Contact)
+    #       * The contact whose state you want to update.
+    #       * Required
+    #   
+    #   - options (Hash)
+    #       * Required
+    #     
+    #     - id (string, max 63 characters)
+    #         * Arbitrary string representing the contact's current state for this service, e.g.
+    #             'q1', 'q2', etc.
+    #         * Required
+    #     
+    #     - vars (Hash)
+    #         * Custom variables stored for this contact's state
+    #   
+    # Returns:
+    #     Telerivet::ContactServiceState
+    #
+    def set_contact_state(contact, options)
+        require_relative 'contactservicestate'
+        ContactServiceState.new(@api, @api.do_request('POST', get_base_api_path() + '/states/' + contact.id, options))
+    end
+    
+    #
+    # Resets the current state for a particular contact for the given service.
+    # 
+    # Arguments:
+    #   - contact (Telerivet::Contact)
+    #       * The contact whose state you want to reset.
+    #       * Required
+    #   
+    # Returns:
+    #     Telerivet::ContactServiceState
+    #
+    def reset_contact_state(contact)
+        require_relative 'contactservicestate'
+        ContactServiceState.new(@api, @api.do_request('DELETE', get_base_api_path() + '/states/' + contact.id))
+    end
+
+    #
+    # Query the current states of contacts for this 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_contact_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 service.
+    #
+    def save()
+        super
+    end
+
+    def id
+        get('id')
+    end
+
+    def name
+        get('name')
+    end
+
+    def name=(value)
+        set('name', value)
+    end
+
+    def active
+        get('active')
+    end
+
+    def active=(value)
+        set('active', value)
+    end
+
+    def priority
+        get('priority')
+    end
+
+    def priority=(value)
+        set('priority', value)
+    end
+
+    def contexts
+        get('contexts')
+    end
+
+    def project_id
+        get('project_id')
+    end
+
+    def label_id
+        get('label_id')
+    end
+
+    def response_table_id
+        get('response_table_id')
+    end
+
+    def sample_group_id
+        get('sample_group_id')
+    end
+
+    def respondent_group_id
+        get('respondent_group_id')
+    end
+
+    def get_base_api_path()
+        "/projects/#{get('project_id')}/services/#{get('id')}"
+    end
+ 
+end
+
+end

data/lib/telerivet.rb

@@ -0,0 +1,193 @@
+require 'net/http'
+require 'json'
+require_relative 'telerivet/entity'
+require_relative 'telerivet/apicursor'
+
+module Telerivet
+
+#
+# 
+#
+class API    
+    attr_reader :num_requests
+
+    @@client_version = '1.0.2'
+    
+    #
+    # Initializes a client handle to the Telerivet REST API.
+    # 
+    # Each API key is associated with a Telerivet user account, and all
+    # API actions are performed with that user's permissions. If you want to restrict the
+    # permissions of an API client, simply add another user account at
+    # <https://telerivet.com/dashboard/users> with the desired permissions.
+    # 
+    # Arguments:
+    #   - api_key (Your Telerivet API key; see <https://telerivet.com/dashboard/api>)
+    #       * Required
+    #
+    def initialize(api_key, api_url = 'https://api.telerivet.com/v1')
+        @api_key = api_key
+        @api_url = api_url
+        @num_requests = 0
+        @session = nil
+    end
+
+    public
+    
+    def do_request(method, path, params = nil)
+        
+        has_post_data = (method == 'POST' || method == 'PUT')
+
+        url = @api_url + path
+        
+        if !has_post_data and params != nil && params.length > 0
+            url += '?' + URI.encode_www_form(get_url_params(params))
+        end
+        
+        uri = URI(url)
+        
+        if @session == nil            
+            @session = Net::HTTP.start(uri.host, uri.port,
+              :use_ssl => @api_url.start_with?("https://"),
+              :ca_file => File.dirname(__FILE__) + '/cacert.pem',
+              :read_timeout => 35,
+              :open_timeout => 20,
+            )
+        end
+                
+        cls = get_request_class(method)        
+        request = cls.new(uri)
+
+        request['User-Agent'] = "Telerivet Ruby Client/#{@@client_version} Ruby/#{RUBY_VERSION} OS/#{RUBY_PLATFORM}"
+        request.basic_auth(@api_key, "")
+
+        if has_post_data
+            request.set_content_type("application/json")           
+            request.body = JSON.dump(params)            
+        end
+            
+        @num_requests += 1
+
+        response = @session.request(request)       
+        
+        res = JSON.parse(response.body)
+        
+        if res.has_key?("error")
+            error = res['error']
+            error_code = error['code']
+            
+            if error_code == 'invalid_param'
+                raise InvalidParameterException, error['message'] #, error['code'], error['param'])
+            elsif error_code == 'not_found'
+                raise NotFoundException, error['message'] #, error['code']);
+            else
+                raise APIException, error['message'] #, error['code'])               
+            end
+        else
+            return res    
+        end
+    end
+    
+    #
+    # Retrieves the Telerivet project with the given ID.
+    # 
+    # Arguments:
+    #   - id
+    #       * ID of the project -- see <https://telerivet.com/dashboard/api>
+    #       * Required
+    #   
+    # Returns:
+    #     Telerivet::Project
+    #
+    def get_project_by_id(id)
+        require_relative 'telerivet/project'
+        Project.new(self, {'id' => id}, false)
+    end
+    
+    #
+    # Queries projects accessible to the current user account.
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #     
+    #     - name
+    #         * Filter projects 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::Project)
+    #
+    def query_projects(options = nil)
+        require_relative 'telerivet/project'
+        cursor(Project, '/projects', options)
+    end
+        
+    def cursor(item_cls, path, options)
+        APICursor.new(self, item_cls, path, options)
+    end
+    
+    private
+    
+    def encode_params_rec(param_name, value, res)
+        return if value == nil
+        
+        if value.kind_of?(Array)
+            value.each_index { |i| encode_params_rec("#{param_name}[#{i}]", value[i], res) }            
+        elsif value.kind_of?(Hash)
+            value.each { |k,v| encode_params_rec("#{param_name}[#{k}]", v, res) }            
+        elsif !!value == value
+            res[param_name] = value ? 1 : 0
+        else
+            res[param_name] = value
+        end
+    end
+            
+    def get_url_params(params)
+        res = {}
+        if params != nil
+            params.each { |key,value| encode_params_rec(key, value, res) }
+        end
+        return res    
+    end
+    
+    def get_request_class(method)
+        case method
+        when 'GET' then return Net::HTTP::Get
+        when 'POST' then return Net::HTTP::Post
+        when 'DELETE' then return Net::HTTP::Delete
+        when 'PUT' then return Net::HTTP::Put
+        else return nil
+        end
+    end
+    
+end
+
+class APIException < Exception
+end
+
+class NotFoundException < APIException
+end
+
+class InvalidParameterException < APIException
+end
+
+end