wowsql-sdk 1.3.0 → 3.0.1

data/lib/wowsql/client.rb

@@ -5,27 +5,54 @@ require_relative 'table'
 
 module WOWSQL
   # WOWSQL client for interacting with your database via REST API.
-  # 
+  #
   # This client is used for DATABASE OPERATIONS (CRUD on tables).
   # Use Service Role Key or Anonymous Key for authentication.
+  #
+  # Key Types:
+  #   - Service Role Key: Full access to all database operations (server-side)
+  #   - Anonymous Key: Public access with limited permissions (client-side)
+  #
+  # @example
+  #   client = WOWSQL::WOWSQLClient.new(
+  #     "myproject",
+  #     "wowbase_service_..."
+  #   )
+  #   users = client.table("users").get
   class WOWSQLClient
-    def initialize(project_url, api_key, timeout = 30)
+    attr_reader :api_url, :api_key, :timeout, :verify_ssl
+
+    # @param project_url [String] Project subdomain or full URL
+    # @param api_key [String] API key for database operations
+    # @param base_domain [String] Base domain (default: "wowsql.com")
+    # @param secure [Boolean] Use HTTPS (default: true)
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param verify_ssl [Boolean] Verify SSL certificates (default: true)
+    def initialize(project_url, api_key, base_domain: 'wowsql.com', secure: true, timeout: 30, verify_ssl: true)
       @api_key = api_key
       @timeout = timeout
+      @verify_ssl = verify_ssl
 
-      # Build API URL
       if project_url.start_with?('http://') || project_url.start_with?('https://')
         base_url = project_url.chomp('/')
         if base_url.include?('/api')
-          @api_url = base_url.sub('/api', '') + '/api/v2'
+          base_url = base_url.split('/api').first
+          @api_url = "#{base_url}/api/v2"
         else
-          @api_url = base_url + '/api/v2'
+          @api_url = "#{base_url}/api/v2"
         end
       else
-        @api_url = "https://#{project_url}.wowsql.com/api/v2"
+        protocol = secure ? 'https' : 'http'
+        if project_url.include?(".#{base_domain}") || project_url.end_with?(base_domain)
+          @api_url = "#{protocol}://#{project_url}/api/v2"
+        else
+          @api_url = "#{protocol}://#{project_url}.#{base_domain}/api/v2"
+        end
       end
 
-      @conn = Faraday.new(url: @api_url) do |f|
+      ssl_options = verify_ssl ? {} : { verify: false }
+
+      @conn = Faraday.new(url: @api_url, ssl: ssl_options) do |f|
         f.request :json
         f.response :json
         f.adapter Faraday.default_adapter
@@ -37,7 +64,7 @@ module WOWSQL
     end
 
     # Get a table interface for fluent API.
-    # 
+    #
     # @param table_name [String] Name of the table
     # @return [Table] Table instance for the specified table
     def table(table_name)
@@ -45,7 +72,7 @@ module WOWSQL
     end
 
     # List all tables in the database.
-    # 
+    #
     # @return [Array<String>] List of table names
     def list_tables
       response = request('GET', '/tables', nil, nil)
@@ -53,32 +80,34 @@ module WOWSQL
     end
 
     # Get table schema information.
-    # 
+    #
     # @param table_name [String] Name of the table
     # @return [Hash] Table schema with columns and primary key
     def get_table_schema(table_name)
       request('GET', "/tables/#{table_name}/schema", nil, nil)
     end
 
+    # Close the HTTP connection.
+    def close
+      @conn.close if @conn.respond_to?(:close)
+    end
+
     # Make HTTP request to API.
     def request(method, path, params = nil, json = nil)
-      begin
-        response = @conn.public_send(method.downcase, path) do |req|
-          req.params = params if params
-          req.body = json if json
-        end
-
-        if response.status >= 400
-          error_data = response.body.is_a?(Hash) ? response.body : {}
-          error_msg = error_data['detail'] || error_data['message'] || "Request failed with status #{response.status}"
-          raise WOWSQLException.new(error_msg, response.status, error_data)
-        end
+      response = @conn.public_send(method.downcase, path) do |req|
+        req.params = params if params
+        req.body = json if json
+      end
 
-        response.body
-      rescue Faraday::Error => e
-        raise WOWSQLException.new("Request failed: #{e.message}")
+      if response.status >= 400
+        error_data = response.body.is_a?(Hash) ? response.body : {}
+        error_msg = error_data['detail'] || error_data['message'] || "Request failed with status #{response.status}"
+        raise WOWSQLError.new(error_msg, response.status, error_data)
       end
+
+      response.body
+    rescue Faraday::Error => e
+      raise WOWSQLError.new("Request failed: #{e.message}")
     end
   end
 end
-

data/lib/wowsql/exceptions.rb

@@ -1,6 +1,5 @@
 module WOWSQL
-  # Base exception for WOWSQL SDK errors.
-  class WOWSQLException < StandardError
+  class WOWSQLError < StandardError
     attr_reader :status_code, :response
 
     def initialize(message, status_code = nil, response = nil)
@@ -10,22 +9,24 @@ module WOWSQL
     end
   end
 
-  # Storage-specific exception.
-  class StorageException < WOWSQLException
-  end
+  WOWSQLException = WOWSQLError
+
+  class StorageError < WOWSQLError; end
 
-  # Exception raised when storage limit would be exceeded.
-  class StorageLimitExceededException < StorageException
-    def initialize(message, response = nil)
-      super(message, 413, response)
+  class StorageLimitExceededError < StorageError
+    def initialize(message, status_code = 413, response = nil)
+      super(message, status_code, response)
     end
   end
 
-  # Exception raised when operation requires service role key but anonymous key was used.
-  class PermissionException < WOWSQLException
-    def initialize(message)
-      super(message, 403)
+  StorageException = StorageError
+  StorageLimitExceededException = StorageLimitExceededError
+
+  class SchemaPermissionError < WOWSQLError
+    def initialize(message, status_code = 403, response = nil)
+      super(message, status_code, response)
     end
   end
-end
 
+  PermissionException = SchemaPermissionError
+end

data/lib/wowsql/query_builder.rb

@@ -4,152 +4,246 @@ module WOWSQL
     def initialize(client, table_name)
       @client = client
       @table_name = table_name
-      @params = {}
-      @select_columns = nil
-      @filters = []
-      @group_by = nil
-      @having = []
-      @order_items = nil
+      @options = {}
     end
 
+    # Select specific columns or expressions.
+    #
+    # @param columns [Array<String>] Column names or expressions
+    # @return [QueryBuilder] self for chaining
     def select(*columns)
-      @select_columns = columns
+      if columns.length == 1 && columns[0].is_a?(Array)
+        @options['select'] = columns[0]
+      else
+        @options['select'] = columns.length > 1 ? columns.map(&:to_s) : (columns.first || '*')
+      end
       self
     end
 
-    # Add a filter condition (generic method).
-    # 
-    # @param column [String] Column name
-    # @param operator [String] Operator (eq, neq, gt, gte, lt, lte, like, in, not_in, between, not_between, is, is_not)
+    # Add a filter condition.
+    #
+    # @param column [String, Hash] Column name or filter hash
+    # @param operator [String, nil] Operator (eq, neq, gt, gte, lt, lte, like, in, not_in, between, not_between, is, is_not)
     # @param value [Object] Filter value
-    # @param logical_op [String] Logical operator for combining with previous filters ("AND" or "OR")
-    def filter(column, operator, value, logical_op = 'AND')
-      add_filter(column, operator, value, logical_op)
+    # @param logical_op [String] "AND" or "OR"
+    # @return [QueryBuilder] self for chaining
+    def filter(column, operator = nil, value = nil, logical_op: 'AND')
+      @options['filter'] ||= []
+
+      if column.is_a?(Hash)
+        if column.key?('column') || column.key?(:column)
+          col = column['column'] || column[:column]
+          op = column['operator'] || column[:operator]
+          val = column['value'] || column[:value]
+          lo = column['logical_op'] || column[:logical_op] || logical_op
+          @options['filter'] << { column: col, operator: op, value: val, logical_op: lo }
+        else
+          column.each do |col_name, col_value|
+            @options['filter'] << { column: col_name.to_s, operator: 'eq', value: col_value, logical_op: logical_op }
+          end
+        end
+      else
+        raise ArgumentError, "filter() missing required argument: 'operator'" if operator.nil?
+        @options['filter'] << { column: column, operator: operator, value: value, logical_op: logical_op }
+      end
+
       self
     end
 
     def eq(column, value)
-      add_filter(column, 'eq', value)
-      self
+      filter(column, 'eq', value)
     end
 
     def neq(column, value)
-      add_filter(column, 'neq', value)
-      self
+      filter(column, 'neq', value)
     end
 
     def gt(column, value)
-      add_filter(column, 'gt', value)
-      self
+      filter(column, 'gt', value)
     end
 
     def gte(column, value)
-      add_filter(column, 'gte', value)
-      self
+      filter(column, 'gte', value)
     end
 
     def lt(column, value)
-      add_filter(column, 'lt', value)
-      self
+      filter(column, 'lt', value)
     end
 
     def lte(column, value)
-      add_filter(column, 'lte', value)
-      self
+      filter(column, 'lte', value)
     end
 
     def like(column, pattern)
-      add_filter(column, 'like', pattern)
-      self
+      filter(column, 'like', pattern)
     end
 
     def is_null(column)
-      @filters << { column: column, operator: 'is', value: nil, logical_op: 'AND' }
-      self
+      filter(column, 'is', nil)
     end
 
     def is_not_null(column)
-      @filters << { column: column, operator: 'is_not', value: nil, logical_op: 'AND' }
-      self
+      filter(column, 'is_not', nil)
     end
 
-    def in(column, values)
-      @filters << { column: column, operator: 'in', value: values, logical_op: 'AND' }
-      self
+    # Filter where column is in list of values.
+    def in_list(column, values)
+      filter(column, 'in', values)
     end
 
     def not_in(column, values)
-      @filters << { column: column, operator: 'not_in', value: values, logical_op: 'AND' }
-      self
+      filter(column, 'not_in', values)
     end
 
-    def between(column, min, max)
-      @filters << { column: column, operator: 'between', value: [min, max], logical_op: 'AND' }
-      self
+    def between(column, min_val, max_val)
+      filter(column, 'between', [min_val, max_val])
     end
 
-    def not_between(column, min, max)
-      @filters << { column: column, operator: 'not_between', value: [min, max], logical_op: 'AND' }
-      self
+    def not_between(column, min_val, max_val)
+      filter(column, 'not_between', [min_val, max_val])
     end
 
-    def or(column, operator, value)
-      @filters << { column: column, operator: operator, value: value, logical_op: 'OR' }
-      self
+    # Add an OR filter condition.
+    def or_filter(column, operator, value)
+      filter(column, operator, value, logical_op: 'OR')
     end
 
-    def group_by(*columns)
-      @group_by = columns
+    # Order results by column(s).
+    #
+    # @param column [String, Array] Column name or array of order items
+    # @param direction [String, nil] 'asc' or 'desc'
+    # @return [QueryBuilder] self for chaining
+    def order_by(column, direction = nil)
+      if column.is_a?(String)
+        @options['order'] = column
+        @options['order_direction'] = direction if direction
+      else
+        order_items = column.map do |item|
+          if item.is_a?(Hash)
+            item
+          elsif item.is_a?(Array) && item.length == 2
+            { column: item[0], direction: item[1] }
+          end
+        end.compact
+        @options['order'] = order_items
+      end
       self
     end
 
-    def having(column, operator, value)
-      @having << { column: column, operator: operator, value: value }
-      self
+    # Order results by a single column (alias for order_by).
+    def order(column, direction = 'asc')
+      order_by(column, direction)
     end
 
-    def order_by_multiple(*items)
-      @order_items = items
+    # Limit number of results.
+    def limit(n)
+      @options['limit'] = n
       self
     end
 
-    def order_by(column, desc: false)
-      @params['order'] = column
-      @params['order_direction'] = desc ? 'desc' : 'asc'
+    # Skip records (pagination).
+    def offset(n)
+      @options['offset'] = n
       self
     end
 
-    # Order results by column (alias for order_by, backward compatibility).
-    def order(column, direction = 'asc')
-      order_by(column, desc: direction.downcase == 'desc')
-    end
-
-    def limit(limit)
-      @params['limit'] = limit.to_s
+    # Group results by column(s).
+    #
+    # @param columns [String, Array<String>] Column(s) to group by
+    # @return [QueryBuilder] self for chaining
+    def group_by(*columns)
+      if columns.length == 1 && columns[0].is_a?(Array)
+        @options['group_by'] = columns[0]
+      elsif columns.length == 1 && columns[0].is_a?(String)
+        @options['group_by'] = [columns[0]]
+      else
+        @options['group_by'] = columns.map(&:to_s)
+      end
       self
     end
 
-    def offset(offset)
-      @params['offset'] = offset.to_s
+    # Add a HAVING clause filter.
+    #
+    # @param column [String] Column or aggregate expression
+    # @param operator [String] Operator (eq, neq, gt, gte, lt, lte)
+    # @param value [Object] Filter value
+    # @return [QueryBuilder] self for chaining
+    def having(column, operator, value)
+      @options['having'] ||= []
+      @options['having'] << { column: column, operator: operator, value: value }
       self
     end
 
-    def get
-      # Check if we need POST endpoint (advanced features)
-      has_advanced_features = 
-        (@group_by && !@group_by.empty?) ||
-        !@having.empty? ||
-        (@order_items && !@order_items.empty?) ||
-        @filters.any? { |f| ['in', 'not_in', 'between', 'not_between'].include?(f[:operator]) }
+    # Execute the query.
+    #
+    # @return [Hash] Query response with data and metadata
+    def get(additional_options = nil)
+      final_options = @options.dup
+      final_options.merge!(additional_options) if additional_options
+
+      body = {}
+
+      if final_options['select']
+        sel = final_options['select']
+        body['select'] = sel.is_a?(String) ? sel.split(',').map(&:strip) : Array(sel)
+      end
+
+      if final_options['filter']
+        filters = final_options['filter']
+        body['filters'] = filters.is_a?(Array) ? filters : [filters]
+      end
+
+      if final_options['group_by']
+        gb = final_options['group_by']
+        body['group_by'] = gb.is_a?(String) ? gb.split(',').map(&:strip) : Array(gb)
+      end
 
-      if has_advanced_features
-        # Use POST endpoint for advanced queries
-        body = build_query_body
+      if final_options['having']
+        hv = final_options['having']
+        body['having'] = hv.is_a?(Array) ? hv : [hv]
+      end
+
+      if final_options['order']
+        ord = final_options['order']
+        if ord.is_a?(String)
+          body['order_by'] = ord
+          body['order_direction'] = final_options['order_direction'] || 'asc'
+        else
+          body['order_by'] = ord
+        end
+      end
+
+      body['limit'] = final_options['limit'] if final_options['limit']
+      body['offset'] = final_options['offset'] if final_options['offset']
+
+      has_advanced = body.key?('group_by') ||
+                     body.key?('having') ||
+                     body['order_by'].is_a?(Array) ||
+                     (body['filters'] || []).any? { |f| %w[in not_in between not_between].include?(f[:operator]) }
+
+      if has_advanced
         @client.request('POST', "/#{@table_name}/query", nil, body)
       else
-        # Use GET endpoint for simple queries (backward compatibility)
-        build_get_params
-        @client.request('GET', "/#{@table_name}", @params, nil)
+        params = {}
+        if body['select']
+          params['select'] = body['select'].is_a?(Array) ? body['select'].join(',') : body['select']
+        end
+        if body['filters']
+          filter_strs = body['filters'].map do |f|
+            if f[:value].is_a?(Array)
+              return @client.request('POST', "/#{@table_name}/query", nil, body)
+            end
+            "#{f[:column]}.#{f[:operator]}.#{f[:value]}"
+          end
+          params['filter'] = filter_strs.join(',')
+        end
+        if body['order_by'].is_a?(String)
+          params['order'] = body['order_by']
+          params['order_direction'] = body['order_direction'] || 'asc'
+        end
+        params['limit'] = body['limit'] if body['limit']
+        params['offset'] = body['offset'] if body['offset']
+        @client.request('GET', "/#{@table_name}", params, nil)
       end
     end
 
@@ -158,59 +252,74 @@ module WOWSQL
       get
     end
 
+    # Get first record matching query.
+    #
+    # @return [Hash, nil] First record or nil
     def first
       result = limit(1).get
-      result['data']&.first
+      data = result['data']
+      data && !data.empty? ? data[0] : nil
     end
 
-    private
-
-    def add_filter(column, op, value)
-      @filters << { column: column, operator: op, value: value, logical_op: 'AND' }
+    # Get exactly one record. Raises if zero or more than one found.
+    #
+    # @return [Hash] The single matching record
+    # @raise [WOWSQLError] If zero or more than one record found
+    def single
+      result = limit(2).get
+      data = result['data'] || []
+      raise WOWSQLError.new('No records found') if data.empty?
+      raise WOWSQLError.new('Multiple records found, expected exactly one') if data.length > 1
+      data[0]
     end
 
-    def build_query_body
-      body = {}
-
-      body['select'] = @select_columns if @select_columns && !@select_columns.empty?
-
-      body['filters'] = @filters if !@filters.empty?
-
-      body['group_by'] = @group_by if @group_by && !@group_by.empty?
-
-      body['having'] = @having if !@having.empty?
-
-      if @order_items && !@order_items.empty?
-        body['order_by'] = @order_items.map do |item|
-          if item.is_a?(Hash)
-            item
-          else
-            { column: item[0], direction: item[1] }
-          end
+    # Get the total count of records matching the current filters.
+    #
+    # @return [Integer] Number of matching records
+    def count
+      saved_select = @options['select']
+      saved_group = @options.delete('group_by')
+      saved_having = @options.delete('having')
+      saved_order = @options.delete('order')
+      saved_dir = @options.delete('order_direction')
+
+      @options['select'] = ['COUNT(*) as count']
+
+      begin
+        result = get
+      ensure
+        if saved_select
+          @options['select'] = saved_select
+        else
+          @options.delete('select')
         end
-      elsif @params['order']
-        body['order_by'] = @params['order']
-        body['order_direction'] = @params['order_direction'] || 'asc'
+        @options['group_by'] = saved_group if saved_group
+        @options['having'] = saved_having if saved_having
+        @options['order'] = saved_order if saved_order
+        @options['order_direction'] = saved_dir if saved_dir
       end
 
-      body['limit'] = @params['limit'].to_i if @params['limit']
-      body['offset'] = @params['offset'].to_i if @params['offset']
-
-      body
+      data = result['data']
+      data && !data.empty? ? data[0]['count'].to_i : 0
     end
 
-    def build_get_params
-      @params['select'] = @select_columns.join(',') if @select_columns && !@select_columns.empty?
-
-      simple_filters = @filters.reject { |f| ['in', 'not_in', 'between', 'not_between'].include?(f[:operator]) }
-      if !simple_filters.empty?
-        filter_strings = simple_filters.map do |f|
-          value_str = f[:value] || 'null'
-          "#{f[:column]}.#{f[:operator]}.#{value_str}"
-        end
-        @params['filter'] = filter_strings.join(',')
-      end
+    # Paginate results with page-based interface.
+    #
+    # @param page [Integer] Page number (1-indexed)
+    # @param per_page [Integer] Records per page
+    # @return [Hash] Hash with data, page, per_page, total, total_pages
+    def paginate(page: 1, per_page: 20)
+      offset_val = ([page, 1].max - 1) * per_page
+      result = limit(per_page).offset(offset_val).get
+      total = result['total'] || result['count'] || 0
+      total_pages = total > 0 ? (total + per_page - 1) / per_page : 0
+      {
+        'data' => result['data'],
+        'page' => page,
+        'per_page' => per_page,
+        'total' => total,
+        'total_pages' => total_pages
+      }
     end
   end
 end
-