wowsql-sdk 1.2.0 → 3.0.1

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,187 +4,322 @@ 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
 
-    def eq(column, value)
-      add_filter(column, 'eq', value)
+    # 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] "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)
+      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 in(column, values)
-      @filters << { column: column, operator: 'in', value: values, logical_op: 'AND' }
-      self
+    def is_not_null(column)
+      filter(column, 'is_not', nil)
+    end
+
+    # 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
 
-    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
 
-      if has_advanced_features
-        # Use POST endpoint for advanced queries
-        body = build_query_body
-        @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)
-      end
-    end
-
-    def first
-      result = limit(1).get
-      result['data']&.first
-    end
+      body = {}
 
-    private
+      if final_options['select']
+        sel = final_options['select']
+        body['select'] = sel.is_a?(String) ? sel.split(',').map(&:strip) : Array(sel)
+      end
 
-    def add_filter(column, op, value)
-      @filters << { column: column, operator: op, value: value, logical_op: 'AND' }
-    end
+      if final_options['filter']
+        filters = final_options['filter']
+        body['filters'] = filters.is_a?(Array) ? filters : [filters]
+      end
 
-    def build_query_body
-      body = {}
+      if final_options['group_by']
+        gb = final_options['group_by']
+        body['group_by'] = gb.is_a?(String) ? gb.split(',').map(&:strip) : Array(gb)
+      end
 
-      body['select'] = @select_columns if @select_columns && !@select_columns.empty?
+      if final_options['having']
+        hv = final_options['having']
+        body['having'] = hv.is_a?(Array) ? hv : [hv]
+      end
 
-      body['filters'] = @filters if !@filters.empty?
+      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['group_by'] = @group_by if @group_by && !@group_by.empty?
+      body['limit'] = final_options['limit'] if final_options['limit']
+      body['offset'] = final_options['offset'] if final_options['offset']
 
-      body['having'] = @having if !@having.empty?
+      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 @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] }
+      if has_advanced
+        @client.request('POST', "/#{@table_name}/query", nil, body)
+      else
+        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
-      elsif @params['order']
-        body['order_by'] = @params['order']
-        body['order_direction'] = @params['order_direction'] || 'asc'
+        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
 
-      body['limit'] = @params['limit'].to_i if @params['limit']
-      body['offset'] = @params['offset'].to_i if @params['offset']
+    # Execute the query (alias for get).
+    def execute
+      get
+    end
 
-      body
+    # Get first record matching query.
+    #
+    # @return [Hash, nil] First record or nil
+    def first
+      result = limit(1).get
+      data = result['data']
+      data && !data.empty? ? data[0] : nil
     end
 
-    def build_get_params
-      @params['select'] = @select_columns.join(',') if @select_columns && !@select_columns.empty?
+    # 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
 
-      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}"
+    # 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
-        @params['filter'] = filter_strings.join(',')
+        @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
+
+      data = result['data']
+      data && !data.empty? ? data[0]['count'].to_i : 0
+    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
-