wowsql-sdk 3.0.1 → 3.1.0

data/lib/wowsql/query_builder.rb

@@ -1,99 +1,70 @@
+require_relative 'exceptions'
+
 module WOWSQL
-  # Fluent query builder for constructing database queries.
+  # Fluent query builder — all operations translate to PostgREST query parameters.
+  #
+  # @example
+  #   result = client.table("users")
+  #     .select("id", "email", "name")
+  #     .eq("is_active", true)
+  #     .order_by("created_at", "desc")
+  #     .limit(20)
+  #     .get
   class QueryBuilder
     def initialize(client, table_name)
-      @client = client
+      @client     = client
       @table_name = table_name
-      @options = {}
+      @filters    = []
+      @select_cols = nil
+      @group_by   = []
+      @having     = []
+      @order      = []
+      @limit_val  = nil
+      @offset_val = nil
     end
 
-    # Select specific columns or expressions.
-    #
-    # @param columns [Array<String>] Column names or expressions
-    # @return [QueryBuilder] self for chaining
+    # ── Column selection ─────────────────────────────────────────
+
     def select(*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
+      cols = columns.length == 1 && columns[0].is_a?(Array) ? columns[0] : columns.map(&:to_s)
+      @select_cols = cols.empty? ? nil : cols
       self
     end
 
-    # 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'] ||= []
+    # ── Filters ──────────────────────────────────────────────────
 
+    def filter(column, operator = nil, value = nil, logical_op: 'AND')
       if column.is_a?(Hash)
         if column.key?('column') || column.key?(:column)
           col = column['column'] || column[:column]
-          op = column['operator'] || column[:operator]
+          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 }
+          lo  = column['logical_op'] || column[:logical_op] || logical_op
+          @filters << { column: col.to_s, operator: op.to_s, 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 }
+            @filters << { 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 }
+        @filters << { column: column.to_s, operator: operator.to_s, value: value, logical_op: logical_op }
       end
-
       self
     end
 
-    def eq(column, value)
-      filter(column, 'eq', value)
-    end
-
-    def neq(column, value)
-      filter(column, 'neq', value)
-    end
-
-    def gt(column, value)
-      filter(column, 'gt', value)
-    end
-
-    def gte(column, value)
-      filter(column, 'gte', value)
-    end
-
-    def lt(column, value)
-      filter(column, 'lt', value)
-    end
-
-    def lte(column, value)
-      filter(column, 'lte', value)
-    end
-
-    def like(column, pattern)
-      filter(column, 'like', pattern)
-    end
-
-    def is_null(column)
-      filter(column, 'is', nil)
-    end
-
-    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)
-      filter(column, 'not_in', values)
-    end
+    def eq(column, value)         filter(column, 'eq',       value) end
+    def neq(column, value)        filter(column, 'neq',      value) end
+    def gt(column, value)         filter(column, 'gt',       value) end
+    def gte(column, value)        filter(column, 'gte',      value) end
+    def lt(column, value)         filter(column, 'lt',       value) end
+    def lte(column, value)        filter(column, 'lte',      value) end
+    def like(column, pattern)     filter(column, 'like',     pattern) end
+    def ilike(column, pattern)    filter(column, 'ilike',    pattern) end
+    def is_null(column)           filter(column, 'is',       nil) end
+    def is_not_null(column)       filter(column, 'is_not',   nil) end
+    def in_list(column, values)   filter(column, 'in',       values) end
+    def not_in(column, values)    filter(column, 'not_in',   values) end
 
     def between(column, min_val, max_val)
       filter(column, 'between', [min_val, max_val])
@@ -103,223 +74,223 @@ module WOWSQL
       filter(column, 'not_between', [min_val, max_val])
     end
 
-    # Add an OR filter condition.
     def or_filter(column, operator, value)
       filter(column, operator, value, logical_op: 'OR')
     end
 
-    # 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|
+    # ── Ordering / grouping ──────────────────────────────────────
+
+    def order_by(column, direction = 'asc')
+      if column.is_a?(Array)
+        column.each do |item|
           if item.is_a?(Hash)
-            item
+            @order << { column: (item[:column] || item['column']).to_s,
+                        direction: (item[:direction] || item['direction'] || 'asc').to_s }
           elsif item.is_a?(Array) && item.length == 2
-            { column: item[0], direction: item[1] }
+            @order << { column: item[0].to_s, direction: item[1].to_s }
           end
-        end.compact
-        @options['order'] = order_items
+        end
+      else
+        @order << { column: column.to_s, direction: (direction || 'asc').to_s }
       end
       self
     end
 
-    # Order results by a single column (alias for order_by).
     def order(column, direction = 'asc')
       order_by(column, direction)
     end
 
-    # Limit number of results.
-    def limit(n)
-      @options['limit'] = n
+    def group_by(*columns)
+      cols = columns.length == 1 && columns[0].is_a?(Array) ? columns[0] : columns
+      @group_by = cols.map(&:to_s)
       self
     end
 
-    # Skip records (pagination).
-    def offset(n)
-      @options['offset'] = n
+    def having(column, operator, value)
+      @having << { column: column.to_s, operator: operator.to_s, value: value }
       self
     end
 
-    # 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
+    # ── Pagination ───────────────────────────────────────────────
+
+    def limit(n)
+      @limit_val = n.to_i
       self
     end
 
-    # 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 }
+    def offset(n)
+      @offset_val = n.to_i
       self
     end
 
-    # 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
+    # ── Execution ────────────────────────────────────────────────
 
-      if final_options['filter']
-        filters = final_options['filter']
-        body['filters'] = filters.is_a?(Array) ? filters : [filters]
+    # Execute the query using PostgREST native query parameters.
+    #
+    # @return [Hash] { data: Array, count: Integer, total: Integer, limit: Integer, offset: Integer }
+    def get(_additional_options = nil)
+      params = {}
+
+      # SELECT
+      sel = @select_cols ? @select_cols.dup : []
+      unless @group_by.empty?
+        sel = (sel + @group_by).uniq
       end
+      params['select'] = sel.join(',') unless sel.empty?
 
-      if final_options['group_by']
-        gb = final_options['group_by']
-        body['group_by'] = gb.is_a?(String) ? gb.split(',').map(&:strip) : Array(gb)
-      end
+      # FILTERS → PostgREST native column=op.value
+      filters_to_params(@filters).each { |k, v| params[k] = v }
 
-      if final_options['having']
-        hv = final_options['having']
-        body['having'] = hv.is_a?(Array) ? hv : [hv]
+      # ORDER → PostgREST: order=col.asc,col2.desc
+      unless @order.empty?
+        parts = @order.map { |o| "#{o[:column]}.#{o[:direction] || 'asc'}" }
+        params['order'] = parts.join(',')
       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
+      params['limit']  = @limit_val.to_s  if @limit_val
+      params['offset'] = @offset_val.to_s if @offset_val
 
-      body['limit'] = final_options['limit'] if final_options['limit']
-      body['offset'] = final_options['offset'] if final_options['offset']
+      result = @client.request('GET', "/#{@table_name}", params, nil, 'Prefer' => 'count=exact')
 
-      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]) }
+      data   = normalise_data(result)
+      total  = WOWSQLClient.parse_total_from_content_range(@client.last_content_range, data.length)
 
-      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
-        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
+      {
+        'data'   => data,
+        'count'  => data.length,
+        'total'  => total,
+        'limit'  => @limit_val || 100,
+        'offset' => @offset_val || 0
+      }
     end
 
-    # Execute the query (alias for get).
-    def execute
-      get
-    end
+    alias execute get
 
-    # Get first record matching query.
-    #
-    # @return [Hash, nil] First record or nil
     def first
       result = limit(1).get
-      data = result['data']
+      data   = result['data']
       data && !data.empty? ? data[0] : nil
     end
 
-    # 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   = result['data'] || []
+      raise WOWSQLError.new('No records found')                      if data.empty?
+      raise WOWSQLError.new('Multiple records found, expected one')  if data.length > 1
       data[0]
     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')
+      saved = [@select_cols, @group_by, @having, @order, @limit_val, @offset_val]
+      @select_cols = nil
+      @group_by    = []
+      @having      = []
+      @order       = []
+      @limit_val   = 0
+      @offset_val  = nil
 
-      @options['select'] = ['COUNT(*) as count']
+      begin
+        params = filters_to_params(@filters)
+        params['limit'] = '0'
+        @client.request('GET', "/#{@table_name}", params, nil, 'Prefer' => 'count=exact')
+        WOWSQLClient.parse_total_from_content_range(@client.last_content_range, 0)
+      ensure
+        @select_cols, @group_by, @having, @order, @limit_val, @offset_val = saved
+      end
+    end
 
+    def sum(column)
+      saved_sel, @select_cols = @select_cols, ["sum(#{column})"]
+      @limit_val  = nil
+      @offset_val = nil
       begin
         result = get
+        (result.dig('data', 0, 'sum') || 0).to_f
       ensure
-        if saved_select
-          @options['select'] = saved_select
-        else
-          @options.delete('select')
-        end
-        @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
+        @select_cols = saved_sel
       end
+    end
 
-      data = result['data']
-      data && !data.empty? ? data[0]['count'].to_i : 0
+    def avg(column)
+      saved_sel, @select_cols = @select_cols, ["avg(#{column})"]
+      @limit_val  = nil
+      @offset_val = nil
+      begin
+        result = get
+        (result.dig('data', 0, 'avg') || 0).to_f
+      ensure
+        @select_cols = saved_sel
+      end
     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
+      page       = [page.to_i, 1].max
+      offset_val = (page - 1) * per_page
+      result     = limit(per_page).offset(offset_val).get
+      total      = result['total'] || result['count'] || 0
       {
-        'data' => result['data'],
-        'page' => page,
-        'per_page' => per_page,
-        'total' => total,
-        'total_pages' => total_pages
+        'data'        => result['data'],
+        'page'        => page,
+        'per_page'    => per_page,
+        'total'       => total,
+        'total_pages' => total > 0 ? (total + per_page - 1) / per_page : 0
       }
     end
+
+    private
+
+    # Translate filter list into PostgREST query parameters.
+    def filters_to_params(filters)
+      params = {}
+      filters.each do |f|
+        col = f[:column]
+        op  = f[:operator]
+        val = f[:value]
+
+        case op
+        when 'eq'          then params[col] = "eq.#{val}"
+        when 'neq'         then params[col] = "neq.#{val}"
+        when 'gt'          then params[col] = "gt.#{val}"
+        when 'gte'         then params[col] = "gte.#{val}"
+        when 'lt'          then params[col] = "lt.#{val}"
+        when 'lte'         then params[col] = "lte.#{val}"
+        when 'like'
+          params[col] = "like.#{val.to_s.gsub('%', '*')}"
+        when 'ilike'
+          params[col] = "ilike.#{val.to_s.gsub('%', '*')}"
+        when 'is'
+          params[col] = val.nil? ? 'is.null' : "is.#{val}"
+        when 'is_not'
+          params[col] = val.nil? ? 'not.is.null' : "not.is.#{val}"
+        when 'in'
+          list = Array(val).join(',')
+          params[col] = "in.(#{list})"
+        when 'not_in'
+          list = Array(val).join(',')
+          params[col] = "not.in.(#{list})"
+        when 'between'
+          if val.is_a?(Array) && val.length == 2
+            params[col]          = "gte.#{val[0]}"
+            params["#{col}_lte"] = "lte.#{val[1]}"
+          end
+        when 'not_between'
+          if val.is_a?(Array) && val.length == 2
+            params["#{col}_lt"] = "lt.#{val[0]}"
+            params["#{col}_gt"] = "gt.#{val[1]}"
+          end
+        end
+      end
+      params
+    end
+
+    def normalise_data(result)
+      case result
+      when Array then result
+      when Hash
+        result['data'] || result['rows'] || (result.key?('id') ? [result] : [])
+      else
+        []
+      end
+    end
   end
 end

data/lib/wowsql/schema.rb

@@ -13,7 +13,7 @@ module WOWSQL
   #     "wowsql_service_..."
   #   )
   #   schema.create_table("users", [
-  #     { "name" => "id", "type" => "SERIAL", "auto_increment" => true },
+  #     { "name" => "id", "type" => "UUID", "auto_increment" => true },
   #     { "name" => "email", "type" => "VARCHAR(255)", "unique" => true, "nullable" => false },
   #     { "name" => "name", "type" => "VARCHAR(255)" },
   #     { "name" => "metadata", "type" => "JSONB", "default" => "'{}'" },
@@ -24,11 +24,11 @@ module WOWSQL
 
     # @param project_url [String] Project subdomain or full URL
     # @param service_key [String] Service role key (wowsql_service_...)
-    # @param base_domain [String] Base domain (default: "wowsql.com")
+    # @param base_domain [String] Base domain (default: "wowsqlconnect.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, service_key, base_domain: 'wowsql.com', secure: true,
+    def initialize(project_url, service_key, base_domain: 'wowsqlconnect.com', secure: true,
                    timeout: 30, verify_ssl: true)
       if project_url.start_with?('http://') || project_url.start_with?('https://')
         base = project_url.chomp('/')
@@ -64,10 +64,14 @@ module WOWSQL
     #
     # @param table_name [String] Name of the table
     # @param columns [Array<Hash>] Column definitions (name, type, auto_increment, unique, nullable, default)
-    # @param primary_key [String, nil] Primary key column name
+    # @param primary_key [String] Primary key column name (must be the UUID column)
     # @param indexes [Array<String>, nil] Columns to create indexes on
     # @return [Hash]
-    def create_table(table_name, columns, primary_key: nil, indexes: nil)
+    def create_table(table_name, columns, primary_key:, indexes: nil)
+      raise ArgumentError, 'primary_key is required; primary key must be UUID type.' if primary_key.nil? || primary_key.to_s.strip.empty?
+
+      assert_uuid_primary_key!(primary_key, columns)
+
       request('POST', '/api/v2/schema/tables', nil, {
         table_name: table_name,
         columns: columns,
@@ -76,6 +80,19 @@ module WOWSQL
       })
     end
 
+    private
+
+    def assert_uuid_primary_key!(primary_key, columns)
+      col = columns.find { |c| c['name'] == primary_key || c[:name] == primary_key }
+      raise ArgumentError, 'Primary key column not found in columns.' unless col
+
+      type_str = (col['type'] || col[:type]).to_s
+      first = type_str.strip.split(/\s+/, 2).first.to_s.upcase
+      raise ArgumentError, 'Primary key column must use PostgreSQL type UUID.' unless first == 'UUID'
+    end
+
+    public
+
     # Alter an existing table.
     #
     # Operations: add_column, drop_column, modify_column, rename_column

data/lib/wowsql/storage.rb

@@ -98,12 +98,12 @@ module WOWSQL
     # @param api_key [String] API key for authentication
     # @param project_slug [String] Explicit slug (used with base_url)
     # @param base_url [String] Explicit base URL (used with project_slug)
-    # @param base_domain [String] Base domain (default: "wowsql.com")
+    # @param base_domain [String] Base domain (default: "wowsqlconnect.com")
     # @param secure [Boolean] Use HTTPS (default: true)
     # @param timeout [Integer] Request timeout in seconds (default: 60)
     # @param verify_ssl [Boolean] Verify SSL certificates (default: true)
     def initialize(project_url = '', api_key = '', project_slug: '', base_url: '',
-                   base_domain: 'wowsql.com', secure: true, timeout: 60, verify_ssl: true)
+                   base_domain: 'wowsqlconnect.com', secure: true, timeout: 60, verify_ssl: true)
       if !project_slug.empty? && !base_url.empty?
         @base_url = base_url.chomp('/')
         @project_slug = project_slug