wowsql-sdk 3.0.2 → 3.9.0

data/README.md

@@ -1,496 +1,761 @@
 # WowSQL Ruby SDK
 
-Official Ruby client for [WowSQL](https://wowsql.com) — PostgreSQL backend-as-a-service with project auth and object storage.
+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.
 
-**Gem:** `wowsql-sdk` · **Module:** `WOWSQL` · **Ruby:** 2.6+
+---
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+## Table of Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Client Configuration](#client-configuration)
+- [Database Operations](#database-operations)
+  - [get — Query Records](#get--query-records)
+  - [get_by_id — Fetch by Primary Key](#get_by_id--fetch-by-primary-key)
+  - [create / insert — Insert a Record](#create--insert--insert-a-record)
+  - [bulk_insert — Insert Multiple Records](#bulk_insert--insert-multiple-records)
+  - [upsert — Insert or Update](#upsert--insert-or-update)
+  - [update — Update by ID](#update--update-by-id)
+  - [delete — Delete by ID](#delete--delete-by-id)
+- [Query Builder](#query-builder)
+  - [select — Choose Columns](#select--choose-columns)
+  - [Filtering](#filtering)
+  - [order_by — Sort Results](#order_by--sort-results)
+  - [group_by — Aggregate Groups](#group_by--aggregate-groups)
+  - [limit / offset — Pagination](#limit--offset--pagination)
+  - [paginate — Page-Based Pagination](#paginate--page-based-pagination)
+  - [first — Single Record](#first--single-record)
+  - [single — Exactly One Record](#single--exactly-one-record)
+  - [count — Total Count](#count--total-count)
+  - [sum / avg — Aggregates](#sum--avg--aggregates)
+- [Authentication](#authentication)
+  - [sign_up](#sign_up)
+  - [sign_in](#sign_in)
+  - [get_user](#get_user)
+  - [OAuth — Google, GitHub, etc.](#oauth--google-github-etc)
+  - [forgot_password / reset_password](#forgot_password--reset_password)
+  - [send_otp / verify_otp](#send_otp--verify_otp)
+  - [send_magic_link](#send_magic_link)
+  - [verify_email / resend_verification](#verify_email--resend_verification)
+  - [refresh_token](#refresh_token)
+  - [change_password / update_user](#change_password--update_user)
+  - [logout](#logout)
+- [File Storage](#file-storage)
+  - [create_bucket](#create_bucket)
+  - [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)
+  - [drop_table / execute_sql](#drop_table--execute_sql)
+- [Error Handling](#error-handling)
+- [Response Format](#response-format)
 
 ---
 
-## Table of contents
-
-1. [Installation](#installation)
-2. [Quick start](#quick-start)
-3. [Concepts & API keys](#concepts--api-keys)
-4. [Database: `WOWSQLClient`](#database-wowsqlclient)
-5. [Table & `QueryBuilder`](#table--querybuilder)
-6. [Authentication: `ProjectAuthClient`](#authentication-projectauthclient)
-7. [Storage: `WOWSQLStorage`](#storage-wowsqlstorage)
-8. [Schema: `WOWSQLSchema`](#schema-wowsqlschema)
-9. [Models & types](#models--types)
-10. [Exceptions](#exceptions)
-11. [Configuration](#configuration)
-12. [Rails integration](#rails-integration)
-13. [Examples](#examples)
-14. [Troubleshooting](#troubleshooting)
-15. [Links](#links)
+## Requirements
+
+- Ruby 2.7 or higher
+- `faraday` >= 1.0
+- `faraday-multipart` >= 1.0
+- `websocket-client-simple` (realtime; declared in the gemspec)
 
 ---
 
 ## Installation
 
-### Gemfile
+Add to your `Gemfile`:
 
 ```ruby
-gem 'wowsql-sdk', '~> 1.3'
+gem 'wowsql-sdk'
 ```
 
-```bash
-bundle install
-```
-
-### Manual
+Or install directly:
 
 ```bash
 gem install wowsql-sdk
 ```
 
-### Require
+---
+
+## Quick Start
 
 ```ruby
 require 'wowsql'
-# or
-require 'wowmysql' # legacy alias entry (same library)
+
+# Initialize client with your project slug and API key
+client = WOWSQL::WOWSQLClient.new("myproject", "wowsql_anon_...")
+
+# Insert a record
+user = client.table("users").create({ email: "alice@example.com", name: "Alice" })
+
+# Query with filters
+result = client.table("users")
+               .select("id", "email", "name")
+               .eq("is_active", true)
+               .order_by("created_at", "desc")
+               .limit(10)
+               .get
+
+result["data"].each { |u| puts u["email"] }
+
+# Close when done
+client.close
 ```
 
 ---
 
-## Quick start
-
-### Database (CRUD + query builder)
+## Client Configuration
 
 ```ruby
-require 'wowsql'
-
 client = WOWSQL::WOWSQLClient.new(
-  'https://your-project.wowsql.com',
-  ENV.fetch('WOWSQL_SERVICE_KEY'),
-  base_domain: 'wowsql.com',
-  secure: true,
-  timeout: 30,
-  verify_ssl: true
+  "myproject",           # Project slug, full hostname, or full URL
+  "wowsql_anon_...",     # Anonymous key (or service role key for privileged ops)
+  base_domain: "wowsqlconnect.com",  # Default; only needed if self-hosting
+  secure: true,          # Use HTTPS (default: true)
+  timeout: 30,           # Request timeout in seconds (default: 30)
+  verify_ssl: true       # Verify SSL certificates (default: true)
 )
+```
 
-rows = client.table('posts')
-  .select('id', 'title', 'created_at')
-  .eq('published', true)
-  .order_by('created_at', 'desc')
-  .limit(10)
-  .get
+**project_url formats accepted:**
 
-puts rows['data'].inspect
+| Format | Description |
+|--------|-------------|
+| `"myproject"` | Appends `.wowsqlconnect.com` automatically |
+| `"myproject.wowsqlconnect.com"` | Full hostname |
+| `"https://myproject.wowsqlconnect.com"` | Full URL |
+| `"https://your-self-hosted-domain.com"` | Self-hosted instance |
 
-created = client.table('posts').create(
-  'title' => 'Hello',
-  'body' => 'World',
-  'published' => true
-)
-puts created['id']
+**API Key types:**
 
-client.close
+| Key Prefix | Purpose |
+|------------|---------|
+| `wowsql_anon_...` | Public / client-side operations |
+| `wowsql_service_...` | Server-side, privileged operations (schema management, admin) |
+
+---
+
+## Database Operations
+
+### get — Query Records
+
+```ruby
+# All records
+result = client.table("products").get
+
+# Chained query
+result = client.table("products")
+               .select("id", "name", "price")
+               .eq("category", "electronics")
+               .order_by("price", "asc")
+               .limit(20)
+               .offset(0)
+               .get
+
+puts result["data"]    # Array of hashes
+puts result["count"]   # Records returned
+puts result["total"]   # Total matching records
+puts result["limit"]   # Applied limit
+puts result["offset"]  # Applied offset
 ```
 
-### Project authentication
+### get_by_id — Fetch by Primary Key
 
 ```ruby
-auth = WOWSQL::ProjectAuthClient.new(
-  ENV.fetch('WOWSQL_PROJECT_URL'),
-  ENV.fetch('WOWSQL_ANON_KEY'),
-  base_domain: 'wowsql.com'
-)
+user = client.table("users").get_by_id("550e8400-e29b-41d4-a716-446655440000")
+puts user["email"]
+```
+
+### create / insert — Insert a Record
+
+```ruby
+product = client.table("products").create({
+  name: "Widget Pro",
+  price: 29.99,
+  category: "tools",
+  in_stock: true
+})
+puts product["id"]
+```
+
+`insert` is an alias for `create`.
+
+### bulk_insert — Insert Multiple Records
 
-res = auth.sign_up(
-  email: 'user@example.com',
-  password: 'SecurePass123!',
-  full_name: 'Ada Lovelace'
+```ruby
+records = [
+  { name: "Item A", price: 10.00 },
+  { name: "Item B", price: 20.00 },
+  { name: "Item C", price: 30.00 }
+]
+results = client.table("products").bulk_insert(records)
+puts "Inserted #{results.length} records"
+```
+
+### upsert — Insert or Update
+
+```ruby
+# Inserts if not exists; updates if the id already exists
+record = client.table("settings").upsert(
+  { id: "user-uuid", theme: "dark", language: "en" },
+  on_conflict: "id"
 )
+```
 
-auth.set_session(
-  access_token: res.session.access_token,
-  refresh_token: res.session.refresh_token
+### update — Update by ID
+
+```ruby
+updated = client.table("users").update(
+  "550e8400-e29b-41d4-a716-446655440000",
+  { name: "Alice Smith", updated_at: Time.now.iso8601 }
 )
+puts updated["name"]
+```
 
-user = auth.get_user
-puts user.email
+### delete — Delete by ID
+
+```ruby
+deleted = client.table("users").delete("550e8400-e29b-41d4-a716-446655440000")
+```
+
+---
+
+## Query Builder
+
+All query builder methods return `self` and are fully chainable. Call `get` at the end to execute.
+
+### select — Choose Columns
 
-auth.close
+```ruby
+# Specific columns
+client.table("users").select("id", "email", "name").get
+
+# All columns (default)
+client.table("users").get
 ```
 
-### Storage (buckets & files)
+### Filtering
+
+#### Available operators
+
+| Method | PostgREST operator | Description |
+|--------|--------------------|-------------|
+| `eq(col, val)` | `eq` | Equals |
+| `neq(col, val)` | `neq` | Not equals |
+| `gt(col, val)` | `gt` | Greater than |
+| `gte(col, val)` | `gte` | Greater than or equal |
+| `lt(col, val)` | `lt` | Less than |
+| `lte(col, val)` | `lte` | Less than or equal |
+| `like(col, pat)` | `like` | SQL LIKE pattern |
+| `ilike(col, pat)` | `ilike` | Case-insensitive LIKE |
+| `is_null(col)` | `is.null` | Column is NULL |
+| `is_not_null(col)` | `not.is.null` | Column is not NULL |
+| `in_list(col, arr)` | `in.(...)` | Column in list |
+| `not_in(col, arr)` | `not.in.(...)` | Column not in list |
+| `between(col, min, max)` | `gte+lte` | Inclusive range |
+| `not_between(col, min, max)` | `lt+gt` | Outside range |
+| `filter(col, op, val)` | any above | Generic filter |
+| `or_filter(col, op, val)` | OR | OR condition |
 
 ```ruby
-storage = WOWSQL::WOWSQLStorage.new(
-  ENV.fetch('WOWSQL_PROJECT_URL'),
-  ENV.fetch('WOWSQL_SERVICE_KEY'),
-  base_domain: 'wowsql.com',
-  timeout: 60
-)
+# Chained filters (all AND by default)
+result = client.table("orders")
+               .gte("total", 100)
+               .lte("total", 500)
+               .eq("status", "shipped")
+               .get
+
+# LIKE / ILIKE
+result = client.table("products")
+               .ilike("name", "%widget%")
+               .get
+
+# IN list
+result = client.table("users")
+               .in_list("role", ["admin", "manager"])
+               .get
+
+# NULL check
+result = client.table("users").is_null("deleted_at").get
+
+# Date range
+result = client.table("orders")
+               .between("created_at", "2025-01-01", "2025-12-31")
+               .get
+```
 
-bucket = storage.create_bucket('avatars', public: true)
-storage.upload(bucket.name, File.binread('face.png'), path: 'u/1.png', file_name: '1.png')
-puts storage.get_public_url('avatars', 'u/1.png')
+### order_by — Sort Results
 
-storage.close
+```ruby
+# Single column
+client.table("products").order_by("price", "asc").get
+client.table("products").order_by("created_at", "desc").get
+
+# Multiple columns
+client.table("products")
+      .order_by("category", "asc")
+      .order_by("price", "desc")
+      .get
 ```
 
-### Schema (service role only)
+### group_by — Aggregate Groups
 
 ```ruby
-schema = WOWSQL::WOWSQLSchema.new(
-  ENV.fetch('WOWSQL_PROJECT_URL'),
-  ENV.fetch('WOWSQL_SERVICE_KEY')
-)
+result = client.table("orders")
+               .select("status", "sum(total)", "count(*)")
+               .group_by("status")
+               .get
+```
 
-schema.create_table(
-  'notes',
-  [
-    { 'name' => 'id', 'type' => 'SERIAL', 'auto_increment' => true },
-    { 'name' => 'body', 'type' => 'TEXT', 'nullable' => false }
-  ],
-  primary_key: 'id'
-)
+### limit / offset — Pagination
 
-schema.close
+```ruby
+result = client.table("products").limit(20).offset(40).get
 ```
 
----
+### paginate — Page-Based Pagination
 
-## Concepts & API keys
+```ruby
+result = client.table("products").paginate(page: 3, per_page: 20)
 
-| Key | Prefix | Typical use |
-|-----|--------|-------------|
-| **Anonymous** | `wowsql_anon_…` | Browser/mobile auth flows, limited DB access |
-| **Service role** | `wowsql_service_…` | **Server only** — full DB, storage, schema DDL |
+puts result["data"]        # Array of records
+puts result["page"]        # 3
+puts result["per_page"]    # 20
+puts result["total"]       # Total records matching filters
+puts result["total_pages"] # Total pages
+```
 
-- **`WOWSQLClient`** / **`WOWSQLStorage`**: use anon or service key depending on RLS and server vs client.
-- **`WOWSQLSchema`**: **requires service role** (403 otherwise).
-- **`ProjectAuthClient`**: usually **anon** on clients; service key only on trusted servers.
+### first — Single Record
 
-Store keys in `ENV`, never commit them.
+```ruby
+user = client.table("users").eq("email", "alice@example.com").first
+puts user["name"]   # nil if not found
+```
+
+### single — Exactly One Record
+
+```ruby
+begin
+  user = client.table("users").eq("email", "alice@example.com").single
+rescue WOWSQL::WOWSQLError => e
+  puts "Not found or multiple records: #{e.message}"
+end
+```
+
+### count — Total Count
+
+```ruby
+total = client.table("users").eq("is_active", true).count
+puts "Active users: #{total}"
+```
 
-**Project URL:** full `https://{slug}.wowsql.com` or just the slug; the client normalizes against `base_domain` and `secure`.
+### sum / avg — Aggregates
+
+```ruby
+total_revenue = client.table("orders").eq("status", "completed").sum("total")
+avg_price     = client.table("products").eq("category", "electronics").avg("price")
+
+puts "Revenue: #{total_revenue}"
+puts "Average price: #{avg_price}"
+```
 
 ---
 
-## Database: `WOWSQLClient`
+## Authentication
 
 ```ruby
-WOWSQL::WOWSQLClient.new(
-  project_url,
-  api_key,
-  base_domain: 'wowsql.com',
+auth = WOWSQL::ProjectAuthClient.new(
+  "myproject",
+  "wowsql_anon_...",
+  base_domain: "wowsqlconnect.com",
   secure: true,
   timeout: 30,
-  verify_ssl: true
+  verify_ssl: true,
+  token_storage: nil   # Optional custom token storage (implements TokenStorage)
 )
 ```
 
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `table(table_name)` | `Table` | Fluent access to one table (`public` schema via API). |
-| `list_tables` | `Array<String>` | Table names in the project DB. |
-| `get_table_schema(table_name)` | `Hash` | Column metadata from the API. |
-| `request(method, path, params, json)` | `Hash` | Low-level JSON request (advanced). |
-| `close` | — | Release resources. |
+### sign_up
 
-**Reader:** `api_url`, `api_key`, `timeout`, `verify_ssl`.
+```ruby
+response = auth.sign_up(
+  email: "alice@example.com",
+  password: "SecurePass123!",
+  full_name: "Alice Smith",
+  user_metadata: { plan: "pro" }
+)
 
----
+puts response.session.access_token
+puts response.user.id
+puts response.user.email
+```
 
-## Table & `QueryBuilder`
+### sign_in
 
-### `Table`
+```ruby
+response = auth.sign_in(
+  email: "alice@example.com",
+  password: "SecurePass123!"
+)
 
-Obtained via `client.table('name')`.
+puts response.session.access_token
+puts response.session.refresh_token
+```
 
-| Method | Returns | Notes |
-|--------|---------|------|
-| `select(*columns)` | `QueryBuilder` | Column list or `'*'`-style strings per your API. |
-| `filter(column, operator, value, logical_op: 'AND')` | `QueryBuilder` | See operators below. |
-| `get(options = nil)` | `Hash` | Executes SELECT pipeline. |
-| `get_by_id(record_id)` | `Hash` | Single row by PK. |
-| `create(data)` / `insert(data)` | `Hash` | Insert one row. |
-| `bulk_insert(records)` | `Array` | Multiple inserts. |
-| `upsert(data, on_conflict: 'id')` | `Hash` | Upsert semantics per backend. |
-| `update(record_id, data)` | `Hash` | Update by id. |
-| `delete(record_id)` | `Hash` | Delete by id. |
-| `eq` / `neq` / `gt` / `gte` / `lt` / `lte` | `QueryBuilder` | Shorthand filters. |
-| `order_by(column, direction = 'asc')` | `QueryBuilder` | |
-| `count` | `Integer` | |
-| `paginate(page: 1, per_page: 20)` | `Hash` | Paginated result envelope. |
+### get_user
 
-### `QueryBuilder`
+```ruby
+user = auth.get_user
+puts user.id
+puts user.email
+puts user.full_name
+puts user.email_verified
+puts user.user_metadata.inspect
+```
 
-Chainable; ends with `get`, `execute`, `first`, `single`, `count`, or `paginate`.
+### OAuth — Google, GitHub, etc.
 
-**Filters:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `is_null`, `is_not_null`, `in_list`, `not_in`, `between`, `not_between`, `or_filter`.
+**Step 1: Get the authorization URL**
 
-**Grouping / aggregates:** `group_by(*columns)`, `having(column, operator, value)`.
+```ruby
+oauth = auth.get_oauth_authorization_url(
+  provider: "google",
+  redirect_uri: "https://myapp.com/auth/callback"
+)
 
-**Sort / page:** `order_by`, `order`, `limit`, `offset`.
+# Redirect the browser to:
+puts oauth["authorization_url"]
+```
 
-**Terminal:**
+**Step 2: Exchange the callback code**
 
-| Method | Behavior |
-|--------|----------|
-| `get` / `execute` | Full result hash (`data`, counts, etc.). |
-| `first` | First row or `nil`. |
-| `single` | Exactly one row; raises `WOWSQLError` if not one row. |
-| `count` | Integer count. |
-| `paginate(page:, per_page:)` | Paginated structure. |
+```ruby
+result = auth.exchange_oauth_callback(
+  provider: "google",
+  code: params[:code],
+  redirect_uri: "https://myapp.com/auth/callback"
+)
 
-### Filter operators (string)
+puts result.session.access_token
+puts result.user.email
+```
 
-Use with `filter` or the shorthand methods:
+### forgot_password / reset_password
 
-`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `is`, `in`, `not_in`, `between`, `not_between`, `is_not` — as supported by the WowSQL REST API for your project.
+```ruby
+# Send reset email
+auth.forgot_password(email: "alice@example.com")
 
----
+# Reset with token from email
+auth.reset_password(
+  token: "reset_token_from_email",
+  new_password: "NewSecurePass456!"
+)
+```
 
-## Authentication: `ProjectAuthClient`
+### send_otp / verify_otp
 
 ```ruby
-WOWSQL::ProjectAuthClient.new(
-  project_url,
-  api_key,
-  base_domain: 'wowsql.com',
-  secure: true,
-  timeout: 30,
-  verify_ssl: true,
-  token_storage: nil # optional WOWSQL::MemoryTokenStorage or custom
+# Send OTP
+auth.send_otp(email: "alice@example.com", purpose: "login")
+
+# Verify OTP
+response = auth.verify_otp(
+  email: "alice@example.com",
+  otp: "123456",
+  purpose: "login"
 )
+puts response.session.access_token
 ```
 
-### `TokenStorage` (module)
+Purposes: `"login"`, `"signup"`, `"password_reset"`.
 
-Implement in your app for Redis/DB/session persistence:
+### send_magic_link
 
-- `get_access_token` / `set_access_token(token)`
-- `get_refresh_token` / `set_refresh_token(token)`
+```ruby
+auth.send_magic_link(email: "alice@example.com", purpose: "login")
+```
 
-`WOWSQL::MemoryTokenStorage` is in-memory only.
+Purposes: `"login"`, `"signup"`, `"email_verification"`.
 
-### Methods
+### verify_email / resend_verification
 
-| Method | Returns |
-|--------|---------|
-| `sign_up(email:, password:, full_name:, user_metadata:)` | `AuthResponse` |
-| `sign_in(email:, password:)` | `AuthResponse` |
-| `get_user(access_token: nil)` | `AuthUser` |
-| `get_oauth_authorization_url(provider:, redirect_uri:)` | `Hash` |
-| `exchange_oauth_callback(provider:, code:, redirect_uri:)` | `AuthResponse` |
-| `forgot_password(email:)` | `Hash` |
-| `reset_password(token:, new_password:)` | `Hash` |
-| `send_otp(email:, purpose: 'login')` | `Hash` |
-| `verify_otp(email:, otp:, purpose: 'login', new_password: nil)` | `AuthResponse` or `Hash` |
-| `send_magic_link(email:, purpose: 'login')` | `Hash` |
-| `verify_email(token:)` | `Hash` |
-| `resend_verification(email:)` | `Hash` |
-| `logout(access_token: nil)` | `Hash` |
-| `refresh_token(refresh_token: nil)` | `AuthResponse` |
-| `change_password(current_password:, new_password:, access_token: nil)` | `Hash` |
-| `update_user(full_name:, avatar_url:, username:, user_metadata:, access_token:)` | `AuthUser` |
-| `get_session` | `Hash` with token keys |
-| `set_session(access_token:, refresh_token: nil)` | |
-| `clear_session` | |
-| `close` | |
+```ruby
+# Verify email from link token
+result = auth.verify_email(token: "verification_token_from_email")
+puts result["success"]
 
-**Structs:** `AuthUser`, `AuthSession`, `AuthResponse` (see [Models](#models--types)).
+# Resend if needed
+auth.resend_verification(email: "alice@example.com")
+```
 
----
+### refresh_token
 
-## Storage: `WOWSQLStorage`
+```ruby
+response = auth.refresh_token
+puts response.session.access_token
+```
+
+### change_password / update_user
 
 ```ruby
-WOWSQL::WOWSQLStorage.new(
-  project_url = '',
-  api_key = '',
-  project_slug: '',
-  base_url: '',
-  base_domain: 'wowsql.com',
-  secure: true,
-  timeout: 60,
-  verify_ssl: true
+# Change password
+auth.change_password(
+  current_password: "OldPass123!",
+  new_password: "NewPass456!"
+)
+
+# Update profile
+user = auth.update_user(
+  full_name: "Alice Smith",
+  avatar_url: "https://cdn.example.com/avatar.jpg",
+  user_metadata: { bio: "Developer" }
 )
 ```
 
-| Method | Returns |
-|--------|---------|
-| `create_bucket(name, public: false, file_size_limit: nil, allowed_mime_types: nil)` | `StorageBucket` |
-| `list_buckets` | `Array<StorageBucket>` |
-| `get_bucket(name)` | `StorageBucket` |
-| `update_bucket(name, **options)` | `StorageBucket` |
-| `delete_bucket(name)` | `Hash` |
-| `upload(bucket_name, file_data, path: nil, file_name: nil)` | `StorageFile` |
-| `upload_from_path(file_path, bucket_name: 'default', path: nil)` | `StorageFile` |
-| `list_files(bucket_name, prefix: nil, limit: 100, offset: 0)` | `Array<StorageFile>` |
-| `download(bucket_name, file_path)` | `String` (binary string) |
-| `download_to_file(bucket_name, file_path, local_path)` | `String` (path) |
-| `delete_file(bucket_name, file_path)` | `Hash` |
-| `get_public_url(bucket_name, file_path)` | `String` |
-| `get_stats` | `StorageQuota` |
-| `get_quota(force_refresh: false)` | `StorageQuota` |
-| `close` | |
-
-**Value objects:** `StorageBucket`, `StorageFile` (`size_mb`, `size_gb`), `StorageQuota`.
+### logout
 
----
+```ruby
+auth.logout
+```
 
-## Schema: `WOWSQLSchema`
+---
 
-**Requires service role key.**
+## File Storage
 
 ```ruby
-WOWSQL::WOWSQLSchema.new(
-  project_url,
-  service_key,
-  base_domain: 'wowsql.com',
+storage = WOWSQL::WOWSQLStorage.new(
+  "myproject",
+  "wowsql_anon_...",
+  base_domain: "wowsqlconnect.com",
   secure: true,
-  timeout: 30,
+  timeout: 60,
   verify_ssl: true
 )
 ```
 
-| Method | Returns |
-|--------|---------|
-| `create_table(table_name, columns, primary_key: nil, indexes: nil)` | `Hash` |
-| `alter_table(table_name, operation, column_name: nil, column_type: nil, new_column_name: nil, nullable: true, default: nil)` | `Hash` |
-| `drop_table(table_name, cascade: false)` | `Hash` |
-| `execute_sql(sql)` | `Hash` |
-| `add_column(table_name, column_name, column_type, nullable: true, default: nil)` | `Hash` |
-| `drop_column(table_name, column_name)` | `Hash` |
-| `rename_column(table_name, old_name, new_name)` | `Hash` |
-| `modify_column(table_name, column_name, column_type: nil, nullable: nil, default: nil)` | `Hash` |
-| `create_index(table_name, columns, unique: false, name: nil, using: nil)` | `Hash` |
-| `list_tables` | `Array<String>` |
-| `get_table_schema(table_name)` | `Hash` |
-| `close` | |
+### create_bucket
 
-`operation` examples: `add_column`, `drop_column`, `modify_column`, `rename_column` (per API).
+```ruby
+bucket = storage.create_bucket(
+  "avatars",
+  public: true,
+  file_size_limit: 5 * 1024 * 1024,       # 5 MB
+  allowed_mime_types: ["image/jpeg", "image/png"]
+)
+puts bucket.name
+puts bucket.public
+```
 
----
+### upload / upload_from_path
+
+```ruby
+# Upload from IO
+File.open("photo.jpg", "rb") do |f|
+  file = storage.upload("avatars", f, path: "users/alice.jpg")
+  puts file.path
+  puts file.size
+end
+
+# Upload from filesystem path
+file = storage.upload_from_path(
+  "/local/path/photo.jpg",
+  bucket_name: "avatars",
+  path: "users/alice.jpg"
+)
+```
 
-## Models & types
+### list_files / download / delete_file
 
-### Auth (structs)
+```ruby
+# List files
+files = storage.list_files("avatars", prefix: "users/", limit: 50)
+files.each { |f| puts "#{f.path} (#{f.size_mb.round(2)} MB)" }
+
+# Download to memory
+content = storage.download("avatars", "users/alice.jpg")
 
-- **`AuthUser`**: `id`, `email`, `full_name`, `avatar_url`, `email_verified`, `user_metadata`, `app_metadata`, `created_at`
-- **`AuthSession`**: `access_token`, `refresh_token`, `token_type`, `expires_in`
-- **`AuthResponse`**: `session`, `user`
+# Download to disk
+storage.download_to_file("avatars", "users/alice.jpg", "/local/alice.jpg")
 
-### Storage
+# Delete
+storage.delete_file("avatars", "users/alice.jpg")
+```
 
-- **`StorageBucket`**: `id`, `name`, `public`, `file_size_limit`, `allowed_mime_types`, `created_at`, `object_count`, `total_size`
-- **`StorageFile`**: `id`, `bucket_id`, `name`, `path`, `mime_type`, `size`, `metadata`, `created_at`, `public_url` — `size_mb`, `size_gb`
-- **`StorageQuota`**: `total_files`, `total_size_bytes`, `total_size_gb`, `file_types`
+### get_public_url
+
+```ruby
+url = storage.get_public_url("avatars", "users/alice.jpg")
+puts url   # https://myproject.wowsqlconnect.com/api/v1/storage/...
+```
 
 ---
 
-## Exceptions
+## Realtime
 
-| Class | Typical HTTP | When |
-|-------|----------------|------|
-| `WOWSQLError` | any | Base error; `message`, `status_code`, `response`. |
-| `StorageError` | 4xx/5xx | Storage API failures. |
-| `StorageLimitExceededError` | 413 | Quota / size limit. |
-| `SchemaPermissionError` | 403 | Schema call without service key. |
+Subscribe to INSERT / UPDATE / DELETE, broadcast ephemeral events, and track presence. Uses the **same anon or service_role key** as REST.
 
-Aliases: `WOWSQLException`, `StorageException`, `StorageLimitExceededException`, `PermissionException` → map to the classes above.
+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
-begin
-  client.table('x').get
-rescue WOWSQL::WOWSQLError => e
-  warn "#{e.status_code}: #{e.message}"
+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
 ```
 
 ---
 
-## Configuration
+## Schema Management
 
-| Option | Default | Notes |
-|--------|---------|------|
-| `base_domain` | `wowsql.com` | Custom cloud domain if applicable. |
-| `secure` | `true` | Use HTTPS. |
-| `timeout` | 30 (DB/auth/schema), 60 (storage) | Seconds. |
-| `verify_ssl` | `true` | Set `false` only for local dev with self-signed certs. |
+Schema operations require a **service role key** (`wowsql_service_...`).
 
----
+```ruby
+schema = WOWSQL::WOWSQLSchema.new(
+  "myproject",
+  "wowsql_service_...",
+  base_domain: "wowsqlconnect.com",
+  secure: true
+)
+```
 
-## Rails integration
+### create_table
 
-**config/initializers/wowsql.rb**
+```ruby
+schema.create_table(
+  "products",
+  [
+    { "name" => "id",         "type" => "UUID",         "auto_increment" => true },
+    { "name" => "name",       "type" => "VARCHAR(255)",  "nullable" => false },
+    { "name" => "price",      "type" => "DECIMAL(10,2)", "nullable" => false },
+    { "name" => "category",   "type" => "VARCHAR(100)" },
+    { "name" => "metadata",   "type" => "JSONB",         "default" => "'{}'" },
+    { "name" => "created_at", "type" => "TIMESTAMPTZ",   "default" => "CURRENT_TIMESTAMP" }
+  ],
+  primary_key: "id",
+  indexes: ["category", "name"]
+)
+```
+
+### add_column / drop_column / rename_column
 
 ```ruby
-# frozen_string_literal: true
+# Add
+schema.add_column("products", "sku", "VARCHAR(50)", nullable: true)
 
-WOWSQL_CLIENT = WOWSQL::WOWSQLClient.new(
-  ENV.fetch('WOWSQL_PROJECT_URL'),
-  ENV.fetch('WOWSQL_SERVICE_KEY')
-)
+# Drop
+schema.drop_column("products", "old_field")
 
-WOWSQL_AUTH = WOWSQL::ProjectAuthClient.new(
-  ENV.fetch('WOWSQL_PROJECT_URL'),
-  ENV.fetch('WOWSQL_ANON_KEY')
-)
+# Rename
+schema.rename_column("products", "sku", "product_sku")
+
+# Modify type / nullability / default
+schema.modify_column("products", "price", column_type: "NUMERIC(12,2)", nullable: false)
 ```
 
-Use **service key** only in server-side code (jobs, controllers that must bypass restrictions). Prefer **anon** for end-user auth flows.
+### drop_table / execute_sql
+
+```ruby
+# Drop table (irreversible)
+schema.drop_table("products", cascade: false)
+
+# Execute raw DDL SQL
+schema.execute_sql("CREATE INDEX idx_products_category ON products (category)")
+schema.execute_sql("ALTER TABLE users ADD COLUMN last_login TIMESTAMPTZ")
+```
 
 ---
 
-## Examples
+## Error Handling
 
-### Blog: posts and comments
+All SDK errors are subclasses of `WOWSQL::WOWSQLError`.
 
 ```ruby
-posts = WOWSQL_CLIENT.table('posts')
-  .select('id', 'title')
-  .eq('published', true)
-  .order_by('created_at', 'desc')
-  .limit(20)
-  .get
+begin
+  result = client.table("orders").get_by_id("some-id")
+rescue WOWSQL::WOWSQLError => e
+  puts e.message      # Human-readable error message
+  puts e.status_code  # HTTP status code (e.g., 400, 401, 403, 404, 500)
+  puts e.response     # Raw response body hash
+end
+```
 
-posts['data'].each do |p|
-  puts p['title']
+**Storage-specific errors:**
+
+```ruby
+begin
+  storage.upload("avatars", large_file, path: "big.mov")
+rescue WOWSQL::StorageLimitExceededError => e
+  puts "File too large: #{e.message}"
+rescue WOWSQL::StorageError => e
+  puts "Storage error: #{e.message}"
 end
 ```
 
-### Upload avatar then save URL in `public` table
+**Schema-specific errors:**
 
 ```ruby
-storage = WOWSQL::WOWSQLStorage.new(ENV['WOWSQL_PROJECT_URL'], ENV['WOWSQL_SERVICE_KEY'])
-path = "avatars/#{user_id}.jpg"
-storage.upload('default', File.binread(local_path), path: path, file_name: 'avatar.jpg')
-url = storage.get_public_url('default', path)
-WOWSQL_CLIENT.table('profiles').update(user_id, 'avatar_url' => url)
-storage.close
+begin
+  schema.drop_table("important_table")
+rescue WOWSQL::SchemaPermissionError => e
+  puts "Permission denied — use a service role key"
+rescue WOWSQL::WOWSQLError => e
+  puts "Schema error: #{e.message}"
+end
 ```
 
 ---
 
-## Troubleshooting
+## Response Format
 
-| Issue | Check |
-|-------|------|
-| `cannot load such file -- faraday/multipart` | Install **`faraday-multipart`** (`gem install faraday-multipart`) or upgrade to **wowsql-sdk ≥ 3.0.1**, which declares this dependency. Faraday 2 moved multipart into that gem. |
-| 401 Invalid API key | Key matches project; no extra spaces; key active in dashboard. |
-| 403 Schema | Using **service role** for `WOWSQLSchema`. |
-| 413 Storage | `StorageLimitExceededError` — plan / quota / object size. |
-| SSL errors | `verify_ssl: false` temporarily on dev only. |
+All `get` and query builder calls return a consistent hash:
 
----
+```ruby
+{
+  "data"   => [...],    # Array of record hashes
+  "count"  => 10,       # Number of records in this response
+  "total"  => 120,      # Total matching records (from Content-Range)
+  "limit"  => 20,       # Applied limit
+  "offset" => 0         # Applied offset
+}
+```
 
-## Links
+Single-record operations (`create`, `update`, `delete`, `get_by_id`, `upsert`) return a plain `Hash` representing the record.
 
-- [WowSQL Docs](https://wowsql.com/docs)
-- [Dashboard](https://wowsql.com)
-- [Support](mailto:support@wowsql.com)
+Pagination (`paginate`) returns:
+
+```ruby
+{
+  "data"        => [...],
+  "page"        => 2,
+  "per_page"    => 20,
+  "total"       => 120,
+  "total_pages" => 6
+}
+```
 
 ---
 
-**License:** MIT — see included `LICENSE`.
+## License
 
-*WowSQL Team*
+MIT License — see [LICENSE](LICENSE) for details.