zoho-sdk 0.1.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85e89249820cbabe7bc43696d07a2348c3e7cd668008998926ec75693d7e96f8
-  data.tar.gz: 92f8fbdd810ee95460be4373b40b7f15ec9d06335f43543294114be8aa8ec0f3
+  metadata.gz: f5bfe9a0df77523a51afe859e60c155efc81d9d2ae0cc07d27fd1c2b3a50c0ef
+  data.tar.gz: e6808c7cb78263263a3db89b22a8ef7cac77f1a6c1a27fef95ed8c1c48c5c056
 SHA512:
-  metadata.gz: 8df3d8ff1363dbcf72f9ed1a0d9a15e9d3cf1d35932333e38b517f8508a7d7544128ef4e84a5803ebf1fe081ebd3b59a6cb198156a0dff67039df0a61ecb47ba
-  data.tar.gz: de35dc2a2ce57f9bd0837ffddb77e2818a1a613e068796cfef3161afb1c4ae942237873badc57a655f03336c5d470f3951072f188eb3d5e4f49a957bd83993cf
+  metadata.gz: 585d362f0b1625eee9aa7f597212a51defcf57f8baa7023745885cd42e9a6d8885706e9ece975b803e65eba45f8c3dcaf0b98add3914519bad8db59b2f96fdac
+  data.tar.gz: aa5ede9e43b6ef3695354bb35222a50d08c22534988ad87d2e7af14d82f11526c0094222c951a085298b4078c96ea703e2e9a4f4dde73d8180d2b9cb6d4adf43

data/lib/zoho-sdk/analytics/client.rb

@@ -8,25 +8,64 @@ module ZohoSdk::Analytics
   API_PATH = "api".freeze
   API_BASE_URL = "#{API_HOSTNAME}/#{API_PATH}".freeze
 
+  # URL to retrieve access token
+  API_AUTH_HOSTNAME = "https://accounts.zoho.com".freeze
+  API_AUTH_PATH = "oauth/v2/token".freeze
+  API_AUTH_BASE_URL = "#{API_AUTH_HOSTNAME}/#{API_AUTH_PATH}".freeze
+
+  # Allows retrieving workspaces, metadata, and other general data not tied
+  # to a specific resource.
   class Client
-    def initialize(email, auth_token)
+    def initialize(email, client_id, client_secret, refresh_token)
       @email = email
-      @auth_token = auth_token
+      @client_id = client_id
+      @client_secret = client_secret
+      @refresh_token = refresh_token
+
+      # Retrieves access token to authenticate all API requests
+      conn =
+        Faraday.new(url: API_AUTH_BASE_URL) { |conn| conn.adapter :net_http }
+      res =
+        conn.post do |req|
+          payload = {
+            "client_id" => @client_id,
+            "client_secret" => @client_secret,
+            "refresh_token" => @refresh_token,
+            "grant_type" => "refresh_token"
+          }
+          payload.each { |key, value| req.params[key] = value }
+        end
+      if res.success?
+        data = JSON.parse(res.body)
+        if data["access_token"]
+          @access_token = data["access_token"]
+        else
+          nil
+        end
+      else
+        nil
+      end
     end
 
     def workspace_metadata
       get params: {
-        "ZOHO_ACTION" => "DATABASEMETADATA",
-        "ZOHO_METADATA" => "ZOHO_CATALOG_LIST"
-      }
+            "ZOHO_ACTION" => "DATABASEMETADATA",
+            "ZOHO_METADATA" => "ZOHO_CATALOG_LIST"
+          }
     end
 
+    # Create a new Zoho Analytics workspace
+    # @param name [String] Workspace name
+    # @param opts [Hash] Optional arguments
+    # @option opts [String] :description Workspace description
+    # @return [Workspace] Newly created Workspace
     def create_workspace(name, **opts)
-      res = get params: {
-        "ZOHO_ACTION" => "CREATEBLANKDB",
-        "ZOHO_DATABASE_NAME" => name,
-        "ZOHO_DATABASE_DESC" => opts[:description] || ""
-      }
+      res =
+        get params: {
+              "ZOHO_ACTION" => "CREATEBLANKDB",
+              "ZOHO_DATABASE_NAME" => name,
+              "ZOHO_DATABASE_DESC" => opts[:description] || ""
+            }
       if res.success?
         data = JSON.parse(res.body)
         Workspace.new(name, self)
@@ -35,11 +74,11 @@ module ZohoSdk::Analytics
       end
     end
 
+    # Retrieve a workspace by name
+    # @param name [String] The workspace name
+    # @return [Workspace]
     def workspace(name)
-      res = get params: {
-        "ZOHO_ACTION" => "ISDBEXIST",
-        "ZOHO_DB_NAME" => name
-      }
+      res = get params: { "ZOHO_ACTION" => "ISDBEXIST", "ZOHO_DB_NAME" => name }
       if res.success?
         data = JSON.parse(res.body)
         if data.dig("response", "result", "isdbexist") == "true"
@@ -52,49 +91,63 @@ module ZohoSdk::Analytics
       end
     end
 
+    # Wrapper for an HTTP GET request via Faraday
+    # @param path [String] URL path component
+    # @param params [Hash] Query parameters for the request
+    # @return [Faraday::Response]
     def get(path: nil, params: {})
-      conn = Faraday.new(url: url_for(path))
-      res = conn.get do |req|
-        req.params["ZOHO_OUTPUT_FORMAT"] = "JSON"
-        req.params["ZOHO_ERROR_FORMAT"] = "JSON"
-        req.params["ZOHO_API_VERSION"] = "1.0"
-        req.params["authtoken"] = @auth_token
-        params.each { |key, value|
-          req.params[key] = value
-        }
-      end
+      conn =
+        Faraday.new(url: url_for(path)) do |conn|
+          conn.adapter :net_http
+          conn.headers = {
+            "Authorization" => "Zoho-oauthtoken #{@access_token}"
+          }
+        end
+      res =
+        conn.get do |req|
+          req.params["ZOHO_OUTPUT_FORMAT"] = "JSON"
+          req.params["ZOHO_ERROR_FORMAT"] = "JSON"
+          req.params["ZOHO_API_VERSION"] = "1.0"
+          params.each { |key, value| req.params[key] = value }
+        end
     end
 
+    # Wrapper for posting JSON via Faraday. Used primarily for IMPORT tasks.
+    # @param path [String] URL path component
+    # @param io [IO] A readable IO object
+    # @param params [Hash] Query parameters for the request
+    # @return [Faraday::Response]
     def post_json(path: nil, io:, params: {})
-      conn = Faraday.new(url: url_for(path)) do |conn|
-        conn.request :multipart
-        conn.adapter :net_http
-        conn.headers = {
-          'Content-Type' => 'multipart/form-data'
-        }
-      end
-      res = conn.post do |req|
-        payload = {
-          "ZOHO_OUTPUT_FORMAT" => "JSON",
-          "ZOHO_ERROR_FORMAT" => "JSON",
-          "ZOHO_API_VERSION" => "1.0",
-          "authtoken" => @auth_token
-        }
-        params.merge(payload).each { |key, value|
-          req.params[key] = value
-        }
-        req.body = {
-          "ZOHO_FILE" => Faraday::FilePart.new(io, "application/json", "ZOHO_FILE.json")
-        }
-      end
+      conn =
+        Faraday.new(url: url_for(path)) do |conn|
+          conn.request :multipart
+          conn.adapter :net_http
+          conn.headers = {
+            "Authorization" => "Zoho-oauthtoken #{@access_token}",
+            "Content-Type" => "multipart/form-data"
+          }
+        end
+      res =
+        conn.post do |req|
+          payload = {
+            "ZOHO_OUTPUT_FORMAT" => "JSON",
+            "ZOHO_ERROR_FORMAT" => "JSON",
+            "ZOHO_API_VERSION" => "1.0"
+          }
+          params.merge(payload).each { |key, value| req.params[key] = value }
+          req.body = {
+            "ZOHO_FILE" =>
+              Faraday::FilePart.new(io, "application/json", "ZOHO_FILE.json")
+          }
+        end
     end
 
+    # Helper function to build a complete URL path that includes email ID
+    # and encodes path elements.
     def url_for(path = nil)
       parts = [API_BASE_URL, @email]
       if !path.nil?
-        if path[0] == "/"
-          path = path[1..-1]
-        end
+        path = path[1..-1] if path[0] == "/"
         parts << path
       end
       URI.encode(parts.join("/"))

data/lib/zoho-sdk/analytics/table.rb

@@ -4,13 +4,16 @@ require "uri"
 module ZohoSdk::Analytics
   class Table
     IMPORT_TYPES = {
-      :append => "APPEND",
-      :truncate_add => "TRUNCATEADD",
-      :update_add => "UPDATEADD"
+      append: "APPEND",
+      truncate_add: "TRUNCATEADD",
+      update_add: "UPDATEADD"
     }.freeze
 
+    # @return [Workspace] The table's workspace
     attr_reader :workspace
     attr_reader :columns
+
+    # @return [Client] Client object
     attr_reader :client
 
     def initialize(table_name, workspace, client, columns: [])
@@ -25,18 +28,28 @@ module ZohoSdk::Analytics
       @table_name
     end
 
+    # Create a new column in the table
+    # @param column_name [String] The new column's name
+    # @param type [Symbol] Column data type. See {Column::DATA_TYPES}
+    # @param opts [Hash] Optional arguments
+    # @option opts [Boolean] :required Should the column be mandatory. Defaults to false.
+    # @option opts [String] :description The column's description
     def create_column(column_name, type, **opts)
       if !Column::DATA_TYPES.values.include?(type)
-        raise ArgumentError.new("Column type must be one of: #{Column::DATA_TYPES.values.join(', ')}")
+        raise ArgumentError.new(
+                "Column type must be one of: #{Column::DATA_TYPES.values.join(", ")}"
+              )
       end
       @type = type
       @required = opts[:required] || false
       @description = opts[:description] || ""
-      res = client.get path: "#{workspace.name}/#{name}", params: {
-        "ZOHO_ACTION" => "ADDCOLUMN",
-        "ZOHO_COLUMNNAME" => column_name,
-        "ZOHO_DATATYPE" => type.to_s.upcase
-      }
+      res =
+        client.get path: "#{workspace.name}/#{name}",
+                   params: {
+                     "ZOHO_ACTION" => "ADDCOLUMN",
+                     "ZOHO_COLUMNNAME" => column_name,
+                     "ZOHO_DATATYPE" => type.to_s.upcase
+                   }
       if res.success?
         data = JSON.parse(res.body)
         Column.new(column_name, self, client)
@@ -45,11 +58,16 @@ module ZohoSdk::Analytics
       end
     end
 
+    # Retrieve a table column by name
+    # @param name [String] The column name
+    # @return [Column]
     def column(name)
-      res = client.get path: "#{workspace.name}/#{name}", params: {
-        "ZOHO_ACTION" => "ISCOLUMNEXIST",
-        "ZOHO_COLUMN_NAME" => name
-      }
+      res =
+        client.get path: "#{workspace.name}/#{name}",
+                   params: {
+                     "ZOHO_ACTION" => "ISCOLUMNEXIST",
+                     "ZOHO_COLUMN_NAME" => name
+                   }
       if res.success?
         data = JSON.parse(res.body)
         if data.dig("response", "result", "iscolumnexist") == "true"
@@ -65,14 +83,29 @@ module ZohoSdk::Analytics
     end
 
     def rows
-      res = client.get path: "#{workspace.name}/#{name}", params: {
-        "ZOHO_ACTION" => "EXPORT"
-      }
+      res =
+        client.get path: "#{workspace.name}/#{name}",
+                   params: {
+                     "ZOHO_ACTION" => "EXPORT"
+                   }
     end
 
+    # Import data into the table using one of three methods: :append,
+    # :truncate_add, or :update_add. The :append option simply adds rows to
+    # the end of the table. When using :truncate_add, all rows are first
+    # removed and replaced by the new rows. If :update_add is selected,
+    # the :matching option must be provided to match rows to be updated by
+    # any imported row data.
+    # @param import_type [Symbol] Import type. Must be one of: :append, :truncate_add, :update_add
+    # @param data [Hash] The data to import. Must be a hash with column names as keys and cell contents as values.
+    # @param opts [Hash] Optional arguments
+    # @option opts [Array] :matching Array of column names to match when using :update_add
+    # @raise [ArgumentError]
     def import(import_type, data, **opts)
       if !IMPORT_TYPES.keys.include?(import_type)
-        raise ArgumentError.new("import_type must be one of: #{IMPORT_TYPES.keys.join(', ')}")
+        raise ArgumentError.new(
+                "import_type must be one of: #{IMPORT_TYPES.keys.join(", ")}"
+              )
       end
 
       params = {
@@ -87,13 +120,18 @@ module ZohoSdk::Analytics
       if import_type == :update_add
         matching = opts[:matching] || []
         if !matching.is_a?(Array) || matching.size < 1
-          raise ArgumentError.new("Must pass at least one column in `matching` option for UPDATEADD")
+          raise ArgumentError.new(
+                  "Must pass at least one column in `matching` option for UPDATEADD"
+                )
         end
 
-        params["ZOHO_MATCHING_COLUMNS"] = matching.join(',')
+        params["ZOHO_MATCHING_COLUMNS"] = matching.join(",")
       end
 
-      res = client.post_json path: "#{workspace.name}/#{name}", io: StringIO.new(data.to_json), params: params
+      res =
+        client.post_json path: "#{workspace.name}/#{name}",
+                         io: StringIO.new(data.to_json),
+                         params: params
       if res.success?
         data = JSON.parse(res.body)
         data.dig("response", "result", "importSummary", "successRowCount")
@@ -102,6 +140,9 @@ module ZohoSdk::Analytics
       end
     end
 
+    # Safer delete option. Deletes rows from the table based on the given
+    # criteria.
+    # @param criteria [String] The row criteria to match when deleting rows.
     def delete(criteria)
       if criteria.nil?
         raise ArgumentError.new("Delete criteria must be specified")
@@ -110,10 +151,11 @@ module ZohoSdk::Analytics
       delete!(criteria)
     end
 
+    # Unsafe delete. Deletes rows based on the given criteria. If not
+    # provided, all rows are deleted.
+    # @param criteria [String] The row criteria to match when deleting rows.
     def delete!(criteria = nil)
-      params = {
-        "ZOHO_ACTION" => "DELETE"
-      }
+      params = { "ZOHO_ACTION" => "DELETE" }
 
       params["ZOHO_CRITERIA"] = criteria if !criteria.nil?
 
@@ -126,19 +168,21 @@ module ZohoSdk::Analytics
       end
     end
 
+    # Insert a single row into the table
+    # @param row [Hash] Hash of row data. Column names are keys, and cell contents are values.
     def <<(row)
       params = { "ZOHO_ACTION" => "ADDROW" }
-      restricted = %w(
+      restricted = %w[
         ZOHO_ACTION
         ZOHO_API_VERSION
         ZOHO_OUTPUT_FORMAT
         ZOHO_ERROR_FORMAT
-        authtoken
-      )
+      ]
 
-      params = row.reject { |key|
-        !key.is_a?(String) || restricted.include?(key)
-      }.merge(params)
+      params =
+        row.reject do |key|
+          !key.is_a?(String) || restricted.include?(key)
+        end.merge(params)
 
       res = client.get path: "#{workspace.name}/#{name}", params: params
       if res.success?

data/lib/zoho-sdk/analytics/workspace.rb

@@ -33,6 +33,12 @@ module ZohoSdk::Analytics
       end
     end
 
+    # Create a new table in the workspace.
+    # @param table_name [String] The new table's name
+    # @param folder [String] Folder name to create the table under.
+    # @param opts [Hash] Optional arguments
+    # @option opts [String] :description The table's description
+    # @return [Table] Newly created table
     def create_table(table_name, folder = nil, **opts)
       table_design = {
         "TABLENAME" => table_name,
@@ -52,6 +58,9 @@ module ZohoSdk::Analytics
       end
     end
 
+    # Retrieve a table by name from the workspace
+    # @param table_name [String] The table name
+    # @return [Table]
     def table(table_name)
       res = client.get path: name, params: {
         "ZOHO_ACTION" => "ISVIEWEXIST",

data/lib/zoho-sdk/version.rb

@@ -1,3 +1,3 @@
 module ZohoSdk
-  VERSION = "0.1.2"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zoho-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.0
 platform: ruby
 authors:
 - Paul Holden
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-30 00:00:00.000000000 Z
+date: 2021-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday