kinetic_sdk 0.1.1

data/lib/kinetic_sdk/bridgehub/lib/access_keys.rb

@@ -0,0 +1,67 @@
+module KineticSdk
+  class Bridgehub
+
+    # Add an Access Key for a Bridge
+    #
+    # @param slug [String] slug of the bridge
+    # @param payload [Hash] properties for the access key
+    #   - +description+
+    #   - +id+
+    #   - +secret+
+    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def add_access_key(slug, payload, headers=default_headers)
+      info("Adding Access Key for Bridge \"#{slug}\"")
+      post("#{@api_url}/bridges/#{slug}/access-keys", payload, headers)
+    end
+
+    # Delete an Access Key for a Bridge
+    #
+    # @param slug [String] slug of the bridge
+    # @param id [String] id (key) of the access key
+    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def delete_access_key(slug, id, headers=default_headers)
+      info("Deleting Access Key #{id} for Bridge \"#{slug}\"")
+      delete("#{@api_url}/bridges/#{slug}/access-keys/#{id}", headers)
+    end
+
+    # Find Access Keys for a Bridge
+    #
+    # @param slug [String] slug of the bridge
+    # @param params [Hash] Query parameters that are added to the URL, such as +include+
+    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def find_access_keys(slug, params={}, headers=default_headers)
+      info("Finding Access Keys for Bridge \"#{slug}\"")
+      get("#{@api_url}/bridges/#{slug}/access-keys", params, headers)
+    end
+
+    # Find an Access Key for a Bridge
+    #
+    # @param slug [String] slug of the bridge
+    # @param id [String] id (key) of the access key
+    # @param params [Hash] Query parameters that are added to the URL, such as +include+
+    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def find_access_key(slug, id, params={}, headers=default_headers)
+      info("Finding Access Key \"#{id}\" for Bridge \"#{slug}\"")
+      get("#{@api_url}/bridges/#{slug}/access-keys/#{id}", params, headers)
+    end
+
+    # Update a Bridge Access Key
+    #
+    # @param slug [String] slug of the bridge
+    # @param id [String] id (key) of the access key
+    # @param payload [Hash] properties for the access key
+    #   - +description+
+    #   - +secret+
+    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def update_access_key(slug, id, payload, headers=default_headers)
+      info("Updating Access Key \"#{id}\" for Bridge \"#{slug}\"")
+      put("#{@api_url}/bridges/#{slug}/access-keys/#{id}", payload, headers)
+    end
+
+  end
+end

data/lib/kinetic_sdk/bridgehub/lib/bridge.rb

@@ -0,0 +1,69 @@
+module KineticSdk
+  class Bridgehub
+
+    # Add a Bridge
+    #
+    # @param payload [Hash] properties for the bridge
+    #   - +adapterClass+
+    #   - +name+
+    #   - +slug+
+    #   - +ipAddresses+
+    #   - +useAccessKeys+
+    #   - +properties+
+    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def add_bridge(payload, headers=default_headers)
+      info("Adding Bridge \"#{payload['name']}\" with slug \"#{payload['slug']}\"")
+      post("#{@api_url}/bridges", payload, headers)
+    end
+
+    # Delete a Bridge
+    #
+    # @param slug [String] slug of the bridge
+    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def delete_bridge(slug, headers=default_headers)
+      info("Deleting Bridge \"#{slug}\"")
+      delete("#{@api_url}/bridges/#{slug}", headers)
+    end
+
+    # Find Bridges
+    #
+    # @param params [Hash] Query parameters that are added to the URL, such as +include+
+    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def find_bridges(params={}, headers=default_headers)
+      info("Finding Bridges")
+      get("#{@api_url}/bridges", params, headers)
+    end
+
+    # Find a Bridge
+    #
+    # @param slug [String] slug of the bridge
+    # @param params [Hash] Query parameters that are added to the URL, such as +include+
+    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def find_bridge(slug, params={}, headers=default_headers)
+      info("Finding Bridge \"#{slug}\"")
+      get("#{@api_url}/bridges/#{slug}", params, headers)
+    end
+
+    # Update a Bridge
+    #
+    # @param slug [String] slug of the bridge
+    # @param payload [Hash] properties for the bridge
+    #   - +adapterClass+
+    #   - +name+
+    #   - +slug+
+    #   - +ipAddresses+
+    #   - +useAccessKeys+
+    #   - +properties+
+    # @param headers [Hash] hash of headers to send, default is basic authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def update_bridge(slug, payload, headers=default_headers)
+      info("Updating Bridge \"#{slug}\"")
+      put("#{@api_url}/bridges/#{slug}", payload, headers)
+    end
+
+  end
+end

data/lib/kinetic_sdk/discussions/discussions-sdk.rb

@@ -0,0 +1,165 @@
+Dir[File.join(File.dirname(File.expand_path(__FILE__)), "lib", "**", "*.rb")].each {|file| require file }
+
+module KineticSdk
+
+  # Discussions is a Ruby class that acts as a wrapper for the Kinetic Discussions REST API
+  # without having to make explicit HTTP requests.
+  #
+  class Discussions
+
+    # Include the KineticHttpUtils module
+    include KineticSdk::Utils::KineticHttpUtils
+
+    attr_reader :api_url, :username, :jwt, :options, :space_slug,
+                :server, :topics_ws_server, :version
+
+    # Initalize the Discussions SDK with the web server URL and configuration user
+    # credentials, along with any custom option values.
+    #
+    # @param opts [Hash] Kinetic Discussions properties
+    # @option opts [String] :config_file optional - path to the YAML configuration file
+    #
+    #   * Ex: /opt/config/discussions-configuration1.yaml
+    #
+    # @option opts [String] :app_server_url the URL to the Kinetic Request CE web space
+    #
+    #   * Ex: <http://192.168.0.1:8080/kinetic/acme> - space slug (`acme`)
+    #   * Ex: <http://acme.server.io/kinetic> - space slug (`acme`) as subdomain
+    #
+    # @option opts [String] :space_slug the slug that identifies the Space
+    # @option opts [String] :username the username for the user
+    # @option opts [String] :password the password for the user
+    # @option opts [Hash<Symbol, Object>] :options ({}) optional settings
+    #
+    #   * :log_level (String) (_defaults to: off_) level of logging - off | info | debug | trace
+    #   * :export_directory (String) (_example: /opt/exports/kinetic-task) directory to write file attachments when exporting,
+    #   * :max_redirects (Fixnum) (_defaults to: 10_) maximum number of redirects to follow
+    #   * :oauth_client_id (String) id of the Kinetic Core oauth client
+    #   * :oauth_client_secret (String) secret of the Kinetic Core oauth client
+    #   * :ssl_ca_file (String) full path to PEM certificate used to verify the server
+    #   * :ssl_verify_mode (String) (_defaults to: none_) - none | peer
+    #
+    # Example: using a configuration file
+    #
+    #     KineticSdk::Discussions.new({
+    #       config_file: "/opt/config1.yaml"
+    #     })
+    #
+    # Example: space user properties hash
+    #
+    #     KineticSdk::Discussions.new({
+    #       app_server_url: "http://localhost:8080",
+    #       space: "foo",
+    #       username: "admin",
+    #       password: "admin",
+    #       options: {
+    #         log_level: "debug",
+    #         export_directory: "/opt/exports/discussions",
+    #         oauth_client_id: "my-oauth-client-id",
+    #         oauth_client_secret: "secret",
+    #         ssl_verify_mode: "peer",
+    #         ssl_ca_file: "/usr/local/self_signing_ca.pem"
+    #       }
+    #     })
+    #
+    #
+    # Example: system user properties hash
+    #
+    #     KineticSdk::Discussions.new({
+    #       app_server_url: "http://localhost:8080",
+    #       username: "admin",
+    #       password: "password",
+    #       options: {
+    #           log_level: "debug",
+    #           oauth_client_id: "my-oauth-client-id",
+    #           oauth_client_secret: "secret",
+    #           ssl_verify_mode: "peer",
+    #           ssl_ca_file: "/usr/local/self_signing_ca.pem"
+    #       }
+    #     })
+    #
+    #
+    # If the +config_file+ option is present, it will be loaded first, and any additional
+    # options will overwrite any values in the config file
+    #
+    def initialize(opts)
+      # initialize any variables
+      options = {}
+
+      # process the configuration file if it was provided
+      unless opts[:config_file].nil?
+        options.merge!(YAML::load_file opts[:config_file])
+      end
+
+      # process the configuration hash if it was provided
+      options.merge!(opts)
+
+      # allow either :app_server_url or :space_server_url, but not both
+      if options[:app_server_url] && options[:space_server_url]
+        raise StandardError.new "Expecting one of :app_server_url or :space_server_url, but not both."
+      end
+      if options[:app_server_url].nil? && options[:space_server_url].nil?
+        raise StandardError.new "Expecting one of :app_server_url or :space_server_url."
+      end
+
+      # process any individual options
+      @options = options[:options] || {}
+      @username = options[:username]
+      @space_slug = options[:space_slug]
+
+      if options[:topics_server_url]
+        @topics_ws_server = "#{options[:topics_server_url].gsub('http', 'ws')}/#{@space_slug}/socket"
+      end
+
+      if options[:discussions_server_url]
+        @server = options[:discussions_server_url].chomp('/')
+        @api_url = "#{@server}/#{@space_slug}/app/api/v1"
+        if @topics_ws_server.nil?
+          @topics_ws_server = "#{@server.gsub('http', 'ws')}/app/topics/socket"
+        end
+      elsif options[:app_server_url]
+        @server = options[:app_server_url].chomp('/')
+        @api_url = "#{@server}/#{@space_slug}/app/api/v1"
+        if @topics_ws_server.nil?
+          @topics_ws_server = "#{@server.gsub('http', 'ws')}/#{@space_slug}/app/topics/socket"
+        end
+      else
+        raise StandardError.new "The :space_slug option is required when using the :space_server_url option" if @space_slug.nil?
+        @server = options[:space_server_url].chomp('/')
+        @api_url = "#{@server}/app/discussions/api/v1"
+        if @topics_ws_server.nil?
+          @topics_ws_server = "#{@server.gsub('http', 'ws')}/app/topics/socket"
+        end
+      end
+      @jwt = @space_slug.nil? ? nil : generate_jwt(options)
+      @version = 1
+    end
+
+    # Generate a JWT for bearer authentication based on the user credentials,
+    # and oauth client configuration.
+    def generate_jwt(options={})
+      oauth_client_id = options[:options][:oauth_client_id]
+      oauth_client_secret = options[:options][:oauth_client_secret]
+
+      jwt_response = kinetic_core_sdk(options).jwt_token(oauth_client_id, oauth_client_secret)
+      jwt_response.content['access_token']
+    end
+
+    # Creates a reference to the Kinetic Request CE SDK
+    def kinetic_core_sdk(options)
+      kinetic_core_options = {
+        space_slug: options[:space_slug],
+        username: options[:username],
+        password: options[:password],
+        options: options[:options] || {}
+      }
+      if options[:app_server_url]
+        kinetic_core_options[:app_server_url] = options[:app_server_url]
+      else
+        kinetic_core_options[:space_server_url] = options[:space_server_url]
+      end
+      KineticSdk::RequestCe.new(kinetic_core_options)
+    end
+    
+  end
+end

data/lib/kinetic_sdk/discussions/lib/discussions.rb

@@ -0,0 +1,107 @@
+module KineticSdk
+  class Discussions
+
+    # Add a Discussion
+    #
+    # @param properties [Hash] discussion properties
+    #   - +title+ [String]
+    #   - +description+ [String]
+    #   - +joinPolicy+ [String] name of the security policy that defines who can join
+    #   - +owningUsers+ [Array] array of user usernames
+    #   - +owningTeams+ [Array] array of team names
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def add_discussion(properties={}, headers=default_jwt_headers)
+      info("Adding the #{properties['title']} discussion")
+      post("#{@api_url}/discussions", properties, headers)
+    end
+
+    # Delete a Discussion
+    #
+    # @param discussion_id [String] discussion_id of the discussion
+    # @param headers [Hash] hash of headers to send, default is bearer authentication
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def delete_discussion(discussion_id, headers=header_bearer_auth)
+      info("Deleting Discussion \"#{discussion_id}\"")
+      delete("#{@api_url}/discussions/#{discussion_id}", headers)
+    end
+
+    # Find Discussions
+    #
+    # @param params [Hash] Query parameters that are added to the URL, such as +include+
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def find_discussions(params={}, headers=default_jwt_headers)
+      info("Finding Discussions.")
+      get("#{@api_url}/discussions", params, headers)
+    end
+
+    # Find a Discussion
+    #
+    # @param discussion_id [String] id of the Discussion
+    # @param params [Hash] Query parameters that are added to the URL, such as +include+
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def find_discussion(discussion_id, params={}, headers=default_jwt_headers)
+      info("Finding the \"#{discussion_id}\" Discussion.")
+      get("#{@api_url}/discussions/#{discussion_id}", params, headers)
+    end
+
+    # Update a Discussion
+    #
+    # @param discussion_id [String] id of the Discussion
+    # @param properties [Hash] form properties to update
+    #   - +title+ [String]
+    #   - +description+ [String]
+    #   - +isArchived+ [Boolean]
+    #   - +joinPolicy+ [String] name of the security policy that defines who can join
+    #   - +owningUsers+ [Array] array of user usernames
+    #   - +owningTeams+ [Array] array of team names
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def update_discussion(discussion_id, properties={}, headers=default_jwt_headers)
+      info("Updating the \"#{discussion_id}\" Discussion.")
+      put("#{@api_url}/discussions/#{discussion_id}", properties, headers)
+    end
+
+    # Export all discussion attachments
+    #
+    # This method streams the attachments in chunks to avoid consuming large
+    # amounts of memory.
+    #
+    # The message attachments will be saved to the 
+    # `{export_directory}/{discussion_id}/files/{message_id}` directory, where:
+    #
+    #   * +export_directory+: the directory specified in the SDK configuration
+    #   * +discussion_id+: the id of the discussion
+    #   * +message_id+: the id of the message that contains the attachment
+    #
+    # @param discussion_id [String] id of the discussion
+    # @param params [Hash] Query parameters that are added to the URL, such as +include+
+    # @param headers [Hash] hash of headers to send, default is bearer authentication
+    def export_discussion_attachments(discussion_id, params={}, headers=header_bearer_auth)
+      raise StandardError.new "An export directory must be defined to export a file attachment." if @options[:export_directory].nil?
+      info("Exporting all file attachments in the #{discussion_id} Discussion.")
+      info("This may take a while.")
+      # File Counter
+      counter = 0
+      # write the files
+      find_messages(discussion_id, params, headers).content['messages'].each do |m|
+        message_id = m['id']
+        updated_at = m['updatedAt']
+        m['content'].each do |item|
+          if (item['type'] == "attachment")
+            document_id = item['value']['documentId']
+            filename = item['value']['filename']
+            # count the files
+            counter = counter + 1
+            # export the file attachments
+            export_message_attachment(discussion_id, message_id, document_id, filename, params, headers)
+          end
+        end
+      end
+      info("Exported #{counter} file attachments for the #{discussion_id} Discussion")
+    end 
+
+  end
+end

data/lib/kinetic_sdk/discussions/lib/invitations.rb

@@ -0,0 +1,120 @@
+module KineticSdk
+  class Discussions
+
+    # Invite an email that doesn't have a user account
+    #
+    # @param discussion_id [String] id of the discussion
+    # @param email [String] email to invite
+    # @param message [String] message sent with the invitation
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def add_invitation_by_email(discussion_id, email, message=nil, headers=default_jwt_headers)
+      payload = { "email" => email }
+      payload["message"] = message unless message.nil?
+      info("Inviting #{email} to the #{discussion_id} Discussion")
+      post("#{@api_url}/discussions/#{discussion_id}/invitations", payload, headers)
+    end
+
+    # Invite a user that already has an account
+    #
+    # @param discussion_id [String] id of the discussion
+    # @param username [String] username to invite
+    # @param message [String] message sent with the invitation
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def add_invitation_by_username(discussion_id, username, message=nil, headers=default_jwt_headers)
+      payload = { "user" => { "username" => username } }
+      payload["message"] = message unless message.nil?
+      info("Inviting #{username} to the #{discussion_id} Discussion")
+      post("#{@api_url}/discussions/#{discussion_id}/invitations", payload, headers)
+    end
+
+    # Delete an email invitation
+    #
+    # @param discussion_id [String] id of the discussion
+    # @param email [String] email the invitation was sent to
+    # @param headers [Hash] hash of headers to send, default is bearer authentication
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def delete_invitation_by_email(discussion_id, email, headers=header_bearer_auth)
+      info("Deleting the email invitation to the #{discussion_id} Discussion for #{email}")
+      delete("#{@api_url}/discussions/#{discussion_id}/invitations/#{encode(email)}?email=true", headers)
+    end
+
+    # Delete a user invitation
+    #
+    # @param discussion_id [String] id of the discussion
+    # @param username [String] username the invitation was sent to
+    # @param headers [Hash] hash of headers to send, default is bearer authentication
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def delete_invitation_by_username(discussion_id, username, headers=header_bearer_auth)
+      info("Deleting the user invitation to the #{discussion_id} Discussion for #{username}")
+      delete("#{@api_url}/discussions/#{discussion_id}/invitations/#{encode(username)}", headers)
+    end
+
+    # Find invitations in a discussion
+    #
+    # @param discussion_id [String] id of the discussion
+    # @param params [Hash] Query parameters that are added to the URL, such as +include+
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def find_invitations(discussion_id, params={}, headers=default_jwt_headers)
+      info("Finding Invitations in the #{discussion_id} Discussion")
+      get("#{@api_url}/discussions/#{discussion_id}/invitations", params, headers)
+    end
+
+    # Find an invitation in a discussion by email
+    #
+    # @param discussion_id [String] id of the discussion
+    # @param email [String] email the invitation was sent to
+    # @param params [Hash] Query parameters that are added to the URL, such as +include+
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def find_invitation_by_email(discussion_id, email, params={}, headers=default_jwt_headers)
+      params['email'] = 'true' if params['email'].nil?
+      info("Finding the Invitation for email #{email} in the #{discussion_id} Discussion")
+      get("#{@api_url}/discussions/#{discussion_id}/invitations/#{encode(email)}", params, headers)
+    end
+
+    # Find an invitation in a discussion by username
+    #
+    # @param discussion_id [String] id of the discussion
+    # @param username [String] username of the invitation
+    # @param params [Hash] Query parameters that are added to the URL, such as +include+
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def find_invitation_by_username(discussion_id, username, params={}, headers=default_jwt_headers)
+      params.delete('email')
+      info("Finding the Invitation for user #{username} in the #{discussion_id} Discussion")
+      get("#{@api_url}/discussions/#{discussion_id}/invitations/#{encode(username)}", params, headers)
+    end
+
+    # Resend an email invitation
+    #
+    # @param discussion_id [String] id of the discussion
+    # @param email [String] email the invitation was sent to
+    # @param message [String] updated message to send with the invitation
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def resend_invitation_by_email(discussion_id, email, message, headers=default_jwt_headers)
+      payload = {}
+      payload["message"] = message unless message.nil?
+      info("Reinviting #{email} to the #{discussion_id} Discussion")
+      put("#{@api_url}/discussions/#{discussion_id}/invitations/#{encode(email)}?email=true", payload, headers)
+    end
+
+    # Resend a user invitation
+    #
+    # @param discussion_id [String] id of the discussion
+    # @param username [String] username the invitation was sent to
+    # @param message [String] updated message to send with the invitation
+    # @param headers [Hash] hash of headers to send, default is bearer authentication and accept JSON content type
+    # @return [KineticSdk::Utils::KineticHttpResponse] object, with +code+, +message+, +content_string+, and +content+ properties
+    def resend_invitation_by_username(discussion_id, username, message, headers=default_jwt_headers)
+      payload = {}
+      payload["message"] = message unless message.nil?
+      info("Reinviting #{username} to the #{discussion_id} Discussion")
+      put("#{@api_url}/discussions/#{discussion_id}/invitations/#{encode(username)}", payload, headers)
+    end
+
+  end
+end