wowsql-sdk 3.1.0 → 3.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6af7e027585348a21d26fd70a40e2bfa2ccc7502ae68ee311564a4c8091fbc48
-  data.tar.gz: 3367f7b010bb6fcea604af499cf9f60b16f0725cc0060fa37a44821e3f5e2fca
+  metadata.gz: dda55e2b1cbe73aabfaffa2aaadb6690c8a8978e89f712284cf9507a640004cf
+  data.tar.gz: c88299d7c4be38e8a121865f292d0cac3d489b5de358ea002d24afc6a6715fe6
 SHA512:
-  metadata.gz: eb28912ac3e115c0afe97492493d5832b26cee3dd4f9f7d2e2934c733847f0766d74b32bdbe776525b0192a2a4661553df7e63591c6da05f609c6e3b2972d841
-  data.tar.gz: c351aeaeb6113c5639fb3dff407150bdece3b12b0bd13d079123bee1d30e4d58a933cc38508485bbe190c387d2f40e8916261ac6642a3c9d3cf9cee5ba51e74a
+  metadata.gz: f8d0524196573928f5c92b8cac0df6a0bd6789a9fa18d1cf4c16d87ffb76fb547d51365ca2dc8bca996469584497a249ae3be7fb3fdc1b06c50a2d4c083c8ee4
+  data.tar.gz: 1ee24eb2e9e535fdaa3ca6478ac77407e693a68914f26466b66eeb04ca92f2c561bb9a2154f9705d1eaa7ed793da1ea89e30b267a51f20a4bab91516b1e8c8a2

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to the WowSQL Ruby SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.9.0] - 2026-08-20
+
+### Added - Realtime
+
+- `client.realtime.subscribe` for Postgres `INSERT` / `UPDATE` / `DELETE` (and `*`)
+- WebSocket auth: `wss://<project>/realtime/v1/websocket?apikey=<anon or service_role key>`
+- Auto-reconnect after disconnect; unsubscribe / disconnect clean local and server state
+- `client.realtime.channel(name)` — ephemeral broadcast (`send`) and presence (`track` / `presence_state`)
+- `websocket-client-simple` dependency
+
+### Documentation
+
+- README realtime section

data/LICENSE

@@ -1,22 +1,86 @@
-MIT License
+Elastic License 2.0
 
-Copyright (c) 2024 WowSQL
+Copyright 2026 WowSQL Team
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+## Acceptance
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+By using the software, you agree to all of the terms and conditions below.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+## Copyright License
 
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, practice,
+import, compile, run, and execute the software. If you institute, or help
+institute, patent litigation against any person over claims that your use of
+the software infringes or contributes to the infringement of a patent, then
+your patent license for the software ends immediately.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+## Definitions
+
+The "licensor" is the entity offering these terms, and the "software" is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+"you" refers to the individual or entity agreeing to these terms.
+
+"your company" is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are controlled by, or are under common control with that organization.
+
+"your licenses" are all the licenses granted to you for the software under
+these terms.
+
+"use" means anything you do with the software requiring one of your licenses.
+
+"trademark" means trademarks, service marks, and similar rights.

data/README.md

@@ -1,6 +1,6 @@
 # WowSQL Ruby SDK
 
-The official Ruby SDK for [WowSQL](https://wowsqlconnect.com). Provides a clean, chainable interface for all PostgREST database operations, authentication, file storage, and schema management.
+The official Ruby SDK for [WowSQL](https://wowsqlconnect.com). Provides a clean, chainable interface for all PostgREST database operations, authentication, file storage, realtime, and schema management.
 
 ---
 
@@ -46,6 +46,7 @@ The official Ruby SDK for [WowSQL](https://wowsqlconnect.com). Provides a clean,
   - [upload / upload_from_path](#upload--upload_from_path)
   - [list_files / download / delete_file](#list_files--download--delete_file)
   - [get_public_url](#get_public_url)
+- [Realtime](#realtime)
 - [Schema Management](#schema-management)
   - [create_table](#create_table)
   - [add_column / drop_column / rename_column](#add_column--drop_column--rename_column)
@@ -60,6 +61,7 @@ The official Ruby SDK for [WowSQL](https://wowsqlconnect.com). Provides a clean,
 - Ruby 2.7 or higher
 - `faraday` >= 1.0
 - `faraday-multipart` >= 1.0
+- `websocket-client-simple` (realtime; declared in the gemspec)
 
 ---
 
@@ -593,6 +595,37 @@ puts url   # https://myproject.wowsqlconnect.com/api/v1/storage/...
 
 ---
 
+## Realtime
+
+Subscribe to INSERT / UPDATE / DELETE, broadcast ephemeral events, and track presence. Uses the **same anon or service_role key** as REST.
+
+The SDK connects to:
+
+```
+wss://<project>.wowsqlconnect.com/realtime/v1/websocket?apikey=<wowsql_anon_... or wowsql_service_...>
+```
+
+Enable a table first (`POST /realtime/v1/enable` with `schema_name` and `table_name`) before postgres changes. Channel `send` / presence do **not** need a Postgres trigger. Payloads are capped at 64 KiB. Missing key closes **4001**; invalid key closes **4003** (do not reconnect). Multi-replica deployments need `REDIS_URL`.
+
+```ruby
+unsub = client.realtime.subscribe("messages") do |change|
+  puts "#{change['event']} #{change['new'] || change['old']}"
+end
+
+channel = client.realtime.channel("chat")
+channel.on("broadcast", event: "typing") { |msg| puts msg["payload"] }
+channel.on("presence") { |msg| puts channel.presence_state }
+channel.subscribe
+channel.track("user" => "alice")
+channel.send(event: "typing", payload: { "user" => "alice" })
+
+unsub.call
+channel.unsubscribe
+client.realtime.disconnect
+```
+
+---
+
 ## Schema Management
 
 Schema operations require a **service role key** (`wowsql_service_...`).

data/lib/wowsql/client.rb

@@ -66,6 +66,10 @@ module WOWSQL
       Table.new(self, table_name)
     end
 
+    def realtime
+      @realtime ||= WowSQLRealtime.new(@base_url, @api_key)
+    end
+
     # Close the HTTP connection (no-op, provided for API parity).
     def close
       @conn.close if @conn.respond_to?(:close)

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/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.1.0
+  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