wowsql-sdk 3.0.2 → 3.9.0

data/lib/wowsql/realtime.rb

@@ -0,0 +1,201 @@
+require 'json'
+require 'thread'
+require 'uri'
+
+module WOWSQL
+  def self.build_realtime_websocket_url(project_url, api_key)
+    origin = project_url.to_s.sub(%r{/$}, '')
+    ws = origin.sub(/\Ahttp/, 'ws')
+    "#{ws}/realtime/v1/websocket?apikey=#{URI.encode_www_form_component(api_key)}"
+  end
+
+  class RealtimeChannel
+    attr_reader :name
+
+    def initialize(rt, name)
+      @rt = rt
+      @name = name
+      @joined = false
+      @state = {}
+      @broadcast = []
+      @presence = []
+      @tracked = nil
+    end
+
+    def on(kind, filter = {}, &cb)
+      if kind.to_s == 'broadcast'
+        ev = (filter[:event] || filter['event'] || '*').to_s
+        @broadcast << ->(msg) { cb.call(msg) if ev == '*' || ev == msg['event'].to_s }
+      else
+        @presence << cb
+      end
+      self
+    end
+
+    def subscribe(&on_status)
+      @rt.ensure_connected
+      @rt.send_json(type: 'join', channel: @name)
+      @joined = true
+      on_status&.call('SUBSCRIBED')
+      self
+    end
+
+    def send(event:, payload: {})
+      @rt.ensure_connected
+      unless @joined
+        @rt.send_json(type: 'join', channel: @name)
+        @joined = true
+      end
+      @rt.send_json(type: 'broadcast', channel: @name, event: event, payload: payload || {})
+    end
+
+    def track(payload)
+      @tracked = payload
+      @rt.ensure_connected
+      unless @joined
+        @rt.send_json(type: 'join', channel: @name)
+        @joined = true
+      end
+      @rt.send_json(type: 'presence', event: 'track', channel: @name, payload: payload)
+    end
+
+    def presence_state
+      @state.dup
+    end
+
+    def unsubscribe
+      @rt.send_json(type: 'leave', channel: @name)
+      @joined = false
+      @rt.drop_channel(@name)
+    end
+
+    def rejoin
+      @rt.send_json(type: 'join', channel: @name)
+      @rt.send_json(type: 'presence', event: 'track', channel: @name, payload: @tracked) if @tracked
+    end
+
+    def handle_server(message)
+      case message['type']
+      when 'joined' then @joined = true
+      when 'presence'
+        ev = message['event']
+        if ev == 'sync' && message['state'].is_a?(Hash)
+          @state = message['state']
+        elsif ev == 'join' && message['key']
+          @state[message['key']] = message['payload']
+        elsif ev == 'leave' && message['key']
+          @state.delete(message['key'])
+        end
+        @presence.each { |cb| cb.call(message) }
+      when 'broadcast'
+        wrapped = { 'event' => message['event'], 'payload' => message['payload'] || {}, 'channel' => @name }
+        @broadcast.each { |cb| cb.call(wrapped) }
+      end
+    end
+  end
+
+  class WowSQLRealtime
+    def initialize(project_url, api_key)
+      @project_url = project_url.to_s.sub(%r{/$}, '')
+      @api_key = api_key
+      @ws = nil
+      @manual = false
+      @subs = []
+      @channels = {}
+      @mutex = Mutex.new
+    end
+
+    def url
+      WOWSQL.build_realtime_websocket_url(@project_url, @api_key)
+    end
+
+    def channel(name)
+      @channels[name] ||= RealtimeChannel.new(self, name)
+    end
+
+    def subscribe(table, schema: 'public', event: '*', &callback)
+      sub = { schema: schema, table: table, event: event, callback: callback }
+      @subs << sub
+      Thread.new do
+        ensure_connected
+        send_json(type: 'subscribe', schema: schema, table: table, event: event)
+      end
+      -> { unsubscribe(sub) }
+    end
+
+    def disconnect
+      @manual = true
+      @ws&.close
+      @ws = nil
+    end
+
+    def drop_channel(name)
+      @channels.delete(name)
+    end
+
+    def send_json(obj)
+      @ws&.send(JSON.dump(obj))
+    end
+
+    def ensure_connected
+      return if @ws
+      begin
+        require 'websocket-client-simple'
+      rescue LoadError
+        raise LoadError, 'Realtime requires the websocket-client-simple gem'
+      end
+      @manual = false
+      rt = self
+      @ws = WebSocket::Client::Simple.connect(url) do |ws|
+        ws.on :message do |msg|
+          rt.send(:handle, msg.data)
+        end
+        ws.on :open do
+          rt.send(:on_open)
+        end
+        ws.on :close do |_e|
+          rt.send(:on_close)
+        end
+      end
+      sleep 0.2
+    end
+
+    private
+
+    def on_open
+      @subs.each { |s| send_json(type: 'subscribe', schema: s[:schema], table: s[:table], event: s[:event]) }
+      @channels.each_value(&:rejoin)
+    end
+
+    def on_close
+      @ws = nil
+      ensure_connected if !@manual && (!@subs.empty? || !@channels.empty?)
+    end
+
+    def unsubscribe(sub)
+      @subs.delete(sub)
+      send_json(type: 'unsubscribe', schema: sub[:schema], table: sub[:table])
+    end
+
+    def handle(raw)
+      message = JSON.parse(raw)
+      name = message['channel']
+      @channels[name]&.handle_server(message) if name
+      return unless message['type'] == 'broadcast'
+      return if message['channel'] && !message['table']
+      nested = message['payload'].is_a?(Hash) ? message['payload'] : {}
+      event = (message['event'] || nested['type'] || '').to_s.upcase
+      schema = (message['schema'] || nested['schema'] || 'public').to_s
+      table = (message['table'] || nested['table'] || '').to_s
+      return if table.empty? || !%w[INSERT UPDATE DELETE].include?(event)
+      change = { 'event' => event, 'schema' => schema, 'table' => table, 'payload' => nested }
+      change['new'] = nested['new'] if nested.key?('new')
+      change['old'] = nested['old'] if nested.key?('old')
+      @subs.each do |s|
+        next unless s[:schema] == schema && s[:table] == table
+        next unless s[:event] == '*' || s[:event].to_s.upcase == event
+        s[:callback].call(change)
+      end
+    end
+  end
+end

data/lib/wowsql/schema.rb

@@ -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('/')

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

data/lib/wowsql/table.rb

@@ -1,169 +1,182 @@
 require_relative 'query_builder'
 
 module WOWSQL
-  # Table interface for database operations.
+  # Table interface for direct PostgREST operations.
+  #
+  # All mutations use PostgREST native query parameters (?id=eq.val) and
+  # Prefer headers (return=representation, resolution=merge-duplicates).
+  #
+  # @example
+  #   user = client.table("users").get_by_id("uuid-here")
+  #   result = client.table("users").create({ email: "a@b.com", name: "Alice" })
   class Table
     def initialize(client, table_name)
-      @client = client
+      @client     = client
       @table_name = table_name
     end
 
-    # Start a query with column selection.
-    #
-    # @param columns [Array<String>] Column(s) to select
-    # @return [QueryBuilder] QueryBuilder for chaining
+    # ── Query builder shortcuts ───────────────────────────────────
+
     def select(*columns)
       QueryBuilder.new(@client, @table_name).select(*columns)
     end
 
-    # Start a query with a filter.
-    #
-    # @param column [String, Hash] Column name or filter hash
-    # @param operator [String, nil] Operator
-    # @param value [Object] Filter value
-    # @param logical_op [String] "AND" or "OR"
-    # @return [QueryBuilder] QueryBuilder for chaining
     def filter(column, operator = nil, value = nil, logical_op: 'AND')
       QueryBuilder.new(@client, @table_name).filter(column, operator, value, logical_op: logical_op)
     end
 
-    # Get all records with optional filters.
+    def eq(column, value)
+      QueryBuilder.new(@client, @table_name).eq(column, value)
+    end
+
+    def neq(column, value)
+      QueryBuilder.new(@client, @table_name).neq(column, value)
+    end
+
+    def gt(column, value)
+      QueryBuilder.new(@client, @table_name).gt(column, value)
+    end
+
+    def gte(column, value)
+      QueryBuilder.new(@client, @table_name).gte(column, value)
+    end
+
+    def lt(column, value)
+      QueryBuilder.new(@client, @table_name).lt(column, value)
+    end
+
+    def lte(column, value)
+      QueryBuilder.new(@client, @table_name).lte(column, value)
+    end
+
+    def order_by(column, direction = 'asc')
+      QueryBuilder.new(@client, @table_name).order_by(column, direction)
+    end
+
+    def limit(n)
+      QueryBuilder.new(@client, @table_name).limit(n)
+    end
+
+    def offset(n)
+      QueryBuilder.new(@client, @table_name).offset(n)
+    end
+
+    # ── Read ─────────────────────────────────────────────────────
+
+    # Retrieve all rows (with optional filter options forwarded to QueryBuilder#get).
     #
-    # @param options [Hash, nil] Query options
-    # @return [Hash] Query response
+    # @param options [Hash, nil] Reserved for compatibility; use chained methods instead
+    # @return [Hash] { data: Array, count: Integer, total: Integer, limit: Integer, offset: Integer }
     def get(options = nil)
       QueryBuilder.new(@client, @table_name).get(options)
     end
 
-    # Get a single record by ID.
+    # Retrieve a single row by primary key.
     #
-    # @param record_id [Object] Record ID
-    # @return [Hash] Record data
+    # @param record_id [String] Row UUID
+    # @return [Hash] Row data
     def get_by_id(record_id)
-      @client.request('GET', "/#{@table_name}/#{record_id}", nil, nil)
+      result = @client.request(
+        'GET', "/#{@table_name}",
+        { 'id' => "eq.#{record_id}" },
+        nil,
+        'Prefer' => 'return=representation'
+      )
+      data = normalise_data(result)
+      data.first
     end
 
-    # Create a new record.
+    # ── Write ────────────────────────────────────────────────────
+
+    # Insert a single row and return the created record.
     #
-    # @param data [Hash] Record data
-    # @return [Hash] Create response with new record ID
+    # @param data [Hash] Column→value map
+    # @return [Hash] Created row
     def create(data)
-      @client.request('POST', "/#{@table_name}", nil, data)
+      result = @client.request(
+        'POST', "/#{@table_name}", nil, data,
+        'Prefer' => 'return=representation'
+      )
+      normalise_data(result).first || {}
     end
 
-    # Insert a new record (alias for create).
-    #
-    # @param data [Hash] Record data
-    # @return [Hash] Create response with new record ID
-    def insert(data)
-      create(data)
-    end
+    alias insert create
 
-    # Insert multiple records.
+    # Insert multiple rows.
     #
-    # Attempts a single batch POST first. Falls back to individual
-    # inserts if the server does not support batch creation.
-    #
-    # @param records [Array<Hash>] List of record hashes
-    # @return [Array<Hash>] List of create responses
+    # @param records [Array<Hash>] List of row hashes
+    # @return [Array<Hash>] Created rows
     def bulk_insert(records)
       return [] if records.nil? || records.empty?
 
-      begin
-        result = @client.request('POST', "/#{@table_name}", nil, records)
-        result.is_a?(Array) ? result : [result]
-      rescue StandardError
-        records.map { |record| create(record) }
-      end
+      result = @client.request(
+        'POST', "/#{@table_name}", nil, records,
+        'Prefer' => 'return=representation'
+      )
+      normalise_data(result)
     end
 
     # Insert or update based on conflict column.
     #
-    # Uses PostgreSQL ON CONFLICT (upsert). Falls back to
-    # get-then-insert/update when the backend doesn't expose
-    # a native upsert endpoint.
-    #
-    # @param data [Hash] Record data (must include the conflict column)
-    # @param on_conflict [String] Column to check for conflicts (default: "id")
-    # @return [Hash] Create or update response
+    # @param data [Hash] Row data (must include the conflict column value)
+    # @param on_conflict [String] Column to detect conflicts on (default: "id")
+    # @return [Hash] Upserted row
     def upsert(data, on_conflict: 'id')
-      conflict_value = data[on_conflict] || data[on_conflict.to_sym]
-      return create(data) if conflict_value.nil?
-
-      existing = QueryBuilder.new(@client, @table_name).eq(on_conflict, conflict_value).first
-      if existing
-        update_data = data.reject { |k, _| k.to_s == on_conflict }
-        if update_data.empty?
-          { 'message' => 'No changes', 'affected_rows' => 0 }
-        else
-          update(conflict_value, update_data)
-        end
-      else
-        create(data)
-      end
+      result = @client.request(
+        'POST', "/#{@table_name}", nil, data,
+        'Prefer'             => 'return=representation,resolution=merge-duplicates',
+        'on-conflict-column' => on_conflict
+      )
+      normalise_data(result).first || {}
     end
 
-    # Update a record by ID.
+    # Update a row by ID.
     #
-    # @param record_id [Object] Record ID
-    # @param data [Hash] Data to update
-    # @return [Hash] Update response
+    # @param record_id [String] Row UUID
+    # @param data [Hash] Columns to update
+    # @return [Hash] Updated row
     def update(record_id, data)
-      @client.request('PATCH', "/#{@table_name}/#{record_id}", nil, data)
+      result = @client.request(
+        'PATCH', "/#{@table_name}",
+        { 'id' => "eq.#{record_id}" },
+        data,
+        'Prefer' => 'return=representation'
+      )
+      normalise_data(result).first || {}
     end
 
-    # Delete a record by ID.
+    # Delete a row by ID.
     #
-    # @param record_id [Object] Record ID
-    # @return [Hash] Delete response
+    # @param record_id [String] Row UUID
+    # @return [Hash] Deleted row
     def delete(record_id)
-      @client.request('DELETE', "/#{@table_name}/#{record_id}", nil, nil)
-    end
-
-    # ── Convenience shortcuts ──────────────────────────────────
-
-    def eq(column, value)
-      QueryBuilder.new(@client, @table_name).eq(column, value)
-    end
-
-    def neq(column, value)
-      QueryBuilder.new(@client, @table_name).neq(column, value)
-    end
-
-    def gt(column, value)
-      QueryBuilder.new(@client, @table_name).gt(column, value)
-    end
-
-    def gte(column, value)
-      QueryBuilder.new(@client, @table_name).gte(column, value)
-    end
-
-    def lt(column, value)
-      QueryBuilder.new(@client, @table_name).lt(column, value)
+      result = @client.request(
+        'DELETE', "/#{@table_name}",
+        { 'id' => "eq.#{record_id}" },
+        nil,
+        'Prefer' => 'return=representation'
+      )
+      normalise_data(result).first || {}
     end
 
-    def lte(column, value)
-      QueryBuilder.new(@client, @table_name).lte(column, value)
-    end
+    # ── Aggregates / pagination ───────────────────────────────────
 
-    def order_by(column, direction = 'asc')
-      QueryBuilder.new(@client, @table_name).order_by(column, direction)
-    end
-
-    # Get total record count for this table.
-    #
-    # @return [Integer]
     def count
       QueryBuilder.new(@client, @table_name).count
     end
 
-    # Paginate all records in this table.
-    #
-    # @param page [Integer] Page number (1-indexed)
-    # @param per_page [Integer] Records per page
-    # @return [Hash]
     def paginate(page: 1, per_page: 20)
       QueryBuilder.new(@client, @table_name).paginate(page: page, per_page: per_page)
     end
+
+    private
+
+    def normalise_data(result)
+      case result
+      when Array then result
+      when Hash  then result['data'] || result['rows'] || (result.key?('id') ? [result] : [])
+      else            []
+      end
+    end
   end
 end

data/lib/wowsql/version.rb

@@ -1,4 +1,4 @@
 module WOWSQL
-  VERSION = "3.0.1"
+  VERSION = "3.9.0"
 end
 

data/lib/wowsql.rb

@@ -6,6 +6,7 @@ require_relative 'wowsql/query_builder'
 require_relative 'wowsql/auth'
 require_relative 'wowsql/storage'
 require_relative 'wowsql/schema'
+require_relative 'wowsql/realtime'
 
 module WOWSQL
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wowsql-sdk
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.9.0
 platform: ruby
 authors:
 - WOWSQL Team
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -87,6 +101,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/wowmysql.rb
@@ -95,6 +110,7 @@ files:
 - lib/wowsql/client.rb
 - lib/wowsql/exceptions.rb
 - lib/wowsql/query_builder.rb
+- lib/wowsql/realtime.rb
 - lib/wowsql/schema.rb
 - lib/wowsql/storage.rb
 - lib/wowsql/table.rb