mode-sdk 0.0.1

data/lib/mode/sdk/client/response.rb

@@ -0,0 +1,83 @@
+# encoding: utf-8
+#
+require 'json'
+
+module Mode
+  module Sdk
+    class Client
+      # The Response class wraps a Mode API response
+      #
+      class Response
+        attr_reader :http_response, :expected_codes
+
+        # Construct a new Response instance
+        #
+        # @param http_response [Net::HTTPResponse] the HTTP response
+        # @param expected_codes [optional, Array<Integer>] array of expected
+        #   HTTP response codes
+        #
+        # @return [Mode::Sdk::Client::Response] the instance
+        #
+        def initialize(http_response, expected_codes = [])
+          @http_response  = http_response
+          @expected_codes = expected_codes
+        end
+
+        # The HTTP response code
+        #
+        # @return [Integer] the response code
+        #
+        def code
+          http_response.code.to_i
+        end
+
+        # The parsed HTTP response body
+        #
+        # @return [Hash] the JSON response hash
+        #
+        def body
+          JSON.parse(http_response.body)
+        end
+
+        # Validate the HTTP response code
+        #
+        # @return [true]
+        #
+        def validate!
+          raise_unexpected_code if unexpected_code?
+
+          true
+        end
+
+        # Raise exception due to an unexpected response code
+        #
+        # @raise [Mode::Sdk::Client::AuthenticationError if the response is 401
+        # @raise [Mode::Sdk::Client::AuthorizationError if the response is 403
+        # @raise [Mode::Sdk::Client::ResponseError] for other unexpected
+        #   responses
+        #
+        def raise_unexpected_code
+          case code
+          when 401
+            fail Mode::Sdk::Client::AuthenticationError
+          when 403
+            fail Mode::Sdk::Client::AuthorizationError
+          else
+            fail Mode::Sdk::Client::ResponseError,
+                 "Unexpected response code: #{code}"
+          end
+        end
+
+        private
+
+        def unexpected_code?
+          expected_codes.any? && !expected_codes.include?(code)
+        end
+      end
+
+      class ResponseError       < StandardError; end
+      class AuthenticationError < StandardError; end
+      class AuthorizationError  < StandardError; end
+    end
+  end
+end

data/lib/mode/sdk/column.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+#
+require 'mode/sdk/hash_util'
+require 'mode/sdk/warehouse_util'
+
+module Mode
+  module Sdk
+    # Represents a single column of a table stored in the Mode public data
+    # warehouse
+    #
+    # @attr [Hash] attributes hash of column attributes
+    #
+    class Column
+      extend Mode::Sdk::WarehouseUtil
+      include Mode::Sdk::HashUtil
+
+      attr_reader :attributes
+
+      # Construct a new Column instance
+      #
+      # @param attributes [Hash] hash of column attributes
+      #
+      # @return [Mode::Sdk::Column] the instance
+      #
+      def initialize(attributes)
+        @attributes = stringify_keys(attributes)
+      end
+
+      # Validate the provided column attributes
+      #
+      # @return [true]
+      #
+      def validate!
+        validate_keys!
+        validate_name!
+        validate_type!
+
+        true
+      end
+
+      private
+
+      KEYS  = %w(name type)
+      TYPES = %w(serial string integer number date time datetime boolean)
+
+      NAME_PATTERN = /\A[a-z][a-z0-9_]{0,62}[a-z0-9]\z/
+
+      def name
+        attributes.fetch('name').to_s
+      end
+
+      def type
+        attributes.fetch('type').to_s
+      end
+
+      def keys
+        attributes.keys
+      end
+
+      def validate_keys!
+        KEYS.each do |key|
+          next if keys.include?(key)
+
+          invalid! "Column missing required key '#{key}': #{attributes.inspect}"
+        end
+
+        extra = keys - KEYS
+
+        invalid! "Column has unexpected keys: #{extra.inspect}" if extra.any?
+
+        true
+      end
+
+      def validate_name!
+        invalid! "Column name is invalid: #{name}" unless name =~ NAME_PATTERN
+
+        true
+      end
+
+      def validate_type!
+        unless TYPES.include?(type)
+          invalid! "Column type is invalid: #{type} (valid: #{TYPES.inspect})"
+        end
+
+        true
+      end
+
+      def invalid!(message)
+        fail InvalidError, message
+      end
+
+      class InvalidError < StandardError; end
+    end
+  end
+end

data/lib/mode/sdk/column_set.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+#
+module Mode
+  module Sdk
+    # Represents a set of Mode::Column instances
+    #
+    class ColumnSet
+      attr_reader :original_columns
+
+      # Construct a new ColumnSet instance
+      #
+      # @param original_columns [Array<Hash>] an array of hashes defining
+      #   column names and types
+      #
+      # @return [Mode::Sdk::ColumnSet] the instance
+      #
+      def initialize(original_columns)
+        @original_columns = original_columns
+      end
+
+      # Build an array of Mode::Sdk::Column instances
+      #
+      # @return [Array<Mode::Sdk::Column>] array of columns
+      #
+      def columns
+        @columns ||= (original_columns || []).map do |column|
+          Mode::Sdk::Column.new(column)
+        end
+      end
+
+      # Validate the provided columns
+      #
+      # @raise [Mode::Sdk::ColumnSet::InvalidError] if no columns are provided
+      #
+      # @return [true]
+      #
+      def validate!
+        fail InvalidError, 'No columns provided' unless columns.any?
+
+        columns.each(&:validate!)
+
+        true
+      end
+
+      # Convert columns to array of hashes
+      #
+      # @return [Array<Hash>] array of column attribute hashes
+      #
+      def to_array
+        columns.map(&:attributes)
+      end
+
+      class InvalidError < StandardError; end
+    end
+  end
+end

data/lib/mode/sdk/configuration.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+#
+module Mode
+  module Sdk
+    # Manage Mode API tokens:
+    # [https://modeanalytics.com/settings/access_tokens]
+    # (https://modeanalytics.com/settings/access_tokens)
+    #
+    # API authentication documentation:
+    # [http://developer.modeanalytics.com/#page:authentication]
+    # (http://developer.modeanalytics.com/#page:authentication)
+    #
+    # @attr [String] token Mode API token
+    # @attr [String] secret Mode API secret
+    # @attr [String] host Mode API host
+    #
+    class Configuration
+      attr_accessor :token, :secret, :host
+    end
+  end
+end

data/lib/mode/sdk/hash_util.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+#
+module Mode
+  module Sdk
+    # Provides simple utility methods for manipulating a Hash
+    #
+    module HashUtil
+      # Stringify hash keys
+      #
+      # @param hash [Hash] the original hash
+      #
+      # @return [Hash] a new hash with string keys
+      #
+      def stringify_keys(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value
+        end
+      end
+    end
+  end
+end

data/lib/mode/sdk/table.rb

@@ -0,0 +1,168 @@
+# encoding: utf-8
+#
+require 'mode/sdk/warehouse_util'
+
+module Mode
+  module Sdk
+    # Represents a table stored in the Mode public data warehouse
+    #
+    # @example
+    #   table = Mode::Sdk::Table.new('sf_film_locations')
+    #   table.columns = [
+    #     { name: 'movie_title',  type: 'string' },
+    #     { name: 'release_year', type: 'integer' },
+    #     { name: 'location',     type: 'string' }
+    #   ]
+    #   table.create
+    #
+    # @attr_reader [Array<Hash>] columns an array of hashes defining column
+    #   names and types
+    #
+    # @attr [String] description a brief table description
+    # @attr [String] upload_token the token of the Mode::Sdk::Upload
+    #   containing the CSV with which to populate the table
+    #
+    class Table
+      extend Mode::Sdk::WarehouseUtil
+
+      # Pattern to determine whether a String is a valid table name
+      #
+      NAME_PATTERN = /\A[a-z][a-z0-9_]{2,62}[a-z0-9]\z/
+
+      attr_reader :columns
+
+      attr_accessor :description, :upload_token
+
+      # Construct a new Table instance
+      #
+      # @param name [String] valid table name
+      # @param options [optional, Hash] hash of options
+      #
+      # @option options [String] :owner the username or alias of the Mode
+      #   account associated with the table (defaults to currently
+      #   authenticated account)
+      #
+      # @return [Mode::Sdk::Table] the instance
+      #
+      def initialize(name, options = {})
+        @name    = name
+        @options = options
+      end
+
+      # Determine whether a table with this name already exists for the given
+      # Mode account
+      #
+      # @return [true, false] whether the table exists
+      #
+      def exists?
+        Mode::Sdk::Client.head(resource_path, expect: [200, 404]).code == 200
+      end
+
+      # Create the table in Mode
+      #
+      # @return [Mode::Sdk::Client::Response] the response
+      #
+      def create
+        upsert(:create)
+      end
+
+      # Replace an existing table in Mode
+      #
+      # @return [Mode::Sdk::Client::Response] the response
+      #
+      def replace
+        upsert(:replace)
+      end
+
+      # Assign columns to the table and unmemoize column set, if any
+      #
+      # @param columns [Array<Hash>] an array of hashes defining column names
+      #   and types
+      #
+      # @return [Array<Hash>] the array of columns
+      #
+      def columns=(columns)
+        if instance_variable_defined?(:@column_set)
+          remove_instance_variable(:@column_set)
+        end
+
+        @columns = columns
+      end
+
+      # The full name of the table, including owner schema
+      #
+      # @return [String] the full name
+      #
+      def full_name
+        [owner, name].join('.')
+      end
+
+      private
+
+      attr_reader :name, :options
+
+      def owner
+        options.fetch(:owner, nil) || Mode::Sdk.username
+      end
+
+      def collection_path
+        "/api/#{owner}/tables"
+      end
+
+      def resource_path
+        [collection_path, name].join('/')
+      end
+
+      def column_set
+        @column_set ||= Mode::Sdk::ColumnSet.new(columns)
+      end
+
+      def validate!
+        unless upload_token
+          fail InvalidError, 'Missing required attribute: upload_token'
+        end
+
+        unless name =~ NAME_PATTERN
+          fail InvalidError, "Invalid name: #{name.inspect}"
+        end
+
+        column_set.validate!
+
+        true
+      end
+
+      def upsert(action)
+        validate!
+
+        path = action == :replace ? resource_path : collection_path
+        verb = action == :replace ? :put : :post
+
+        response = Mode::Sdk::Client.send(
+          verb, path, upsert_json, expect: [202, 400])
+
+        if response.code == 400
+          fail InvalidError, "Could not #{action} table: #{response.body}"
+        end
+
+        response
+      end
+
+      def upsert_json
+        upsert_data.to_json
+      end
+
+      def upsert_data
+        {
+          upload_token: upload_token,
+          table: {
+            name:        name,
+            description: description,
+            columns:     column_set.to_array
+          }
+        }
+      end
+
+      class InvalidError < StandardError; end
+    end
+  end
+end