wowsql-sdk 1.3.0 → 3.0.1

data/README.md

@@ -1,554 +1,496 @@
-# 🚀 WOWSQL Ruby SDK
+# WowSQL Ruby SDK
 
-Official Ruby client for [WOWSQL](https://wowsql.com) - MySQL Backend-as-a-Service with S3 Storage.
+Official Ruby client for [WowSQL](https://wowsql.com) — PostgreSQL backend-as-a-service with project auth and object storage.
+
+**Gem:** `wowsql-sdk` · **Module:** `WOWSQL` · **Ruby:** 2.6+
 
-[![Gem Version](https://img.shields.io/gem/v/wowsql-sdk.svg)](https://rubygems.org/gems/wowsql-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## ✨ Features
-
-### Database Features
-- 🗄️ Full CRUD operations (Create, Read, Update, Delete)
-- 🔍 Advanced filtering (eq, neq, gt, gte, lt, lte, like, is_null)
-- 📄 Pagination (limit, offset)
-- 📊 Sorting (order_by)
-- 🎯 Fluent query builder API
-- 📝 Raw SQL queries (read-only)
-- 📋 Table schema introspection
-- 🔒 Built-in error handling
-
-### Storage Features
-- 📦 S3-compatible storage client
-- ⬆️ File upload with automatic quota validation
-- ⬇️ File download (presigned URLs)
-- 📂 File listing with metadata
-- 🗑️ File deletion
-- 📊 Storage quota management
-- 🌍 Multi-region support
-
-## 📦 Installation
+---
+
+## 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)
+
+---
+
+## Installation
 
 ### Gemfile
 
 ```ruby
-gem 'wowsql-sdk', '~> 1.0'
+gem 'wowsql-sdk', '~> 1.3'
 ```
 
-Then run:
-
 ```bash
 bundle install
 ```
 
-### Manual Installation
+### Manual
 
 ```bash
 gem install wowsql-sdk
 ```
 
-## 🚀 Quick Start
+### Require
 
-### Database Operations
+```ruby
+require 'wowsql'
+# or
+require 'wowmysql' # legacy alias entry (same library)
+```
+
+---
+
+## Quick start
+
+### Database (CRUD + query builder)
 
 ```ruby
 require 'wowsql'
 
-# Initialize client
 client = WOWSQL::WOWSQLClient.new(
   'https://your-project.wowsql.com',
-  'your-api-key'  # Get from dashboard
+  ENV.fetch('WOWSQL_SERVICE_KEY'),
+  base_domain: 'wowsql.com',
+  secure: true,
+  timeout: 30,
+  verify_ssl: true
 )
 
-# Select data
-response = client.table('users')
-  .select('id', 'name', 'email')
-  .eq('status', 'active')
+rows = client.table('posts')
+  .select('id', 'title', 'created_at')
+  .eq('published', true)
+  .order_by('created_at', 'desc')
   .limit(10)
   .get
 
-response['data'].each do |user|
-  puts "#{user['name']} (#{user['email']})"
-end
-
-# Insert data
-new_user = {
-  'name' => 'Jane Doe',
-  'email' => 'jane@example.com',
-  'age' => 25
-}
-
-result = client.table('users').create(new_user)
-puts "Created user with ID: #{result['id']}"
+puts rows['data'].inspect
 
-# Update data
-updates = { 'name' => 'Jane Smith' }
-client.table('users').update(result['id'], updates)
+created = client.table('posts').create(
+  'title' => 'Hello',
+  'body' => 'World',
+  'published' => true
+)
+puts created['id']
 
-# Delete data
-client.table('users').delete(result['id'])
+client.close
 ```
 
-### Storage Operations
+### Project authentication
 
 ```ruby
-require 'wowsql'
-
-# Initialize storage client
-storage = WOWSQL::WOWSQLStorage.new(
-  'your-project-slug',
-  'your-api-key'
+auth = WOWSQL::ProjectAuthClient.new(
+  ENV.fetch('WOWSQL_PROJECT_URL'),
+  ENV.fetch('WOWSQL_ANON_KEY'),
+  base_domain: 'wowsql.com'
 )
 
-# Upload file
-storage.upload_from_path('local-file.pdf', 'uploads/document.pdf', 'documents')
-
-# Get presigned URL
-url_data = storage.get_file_url('uploads/document.pdf', 3600)
-puts "File URL: #{url_data['file_url']}"
+res = auth.sign_up(
+  email: 'user@example.com',
+  password: 'SecurePass123!',
+  full_name: 'Ada Lovelace'
+)
 
-# List files
-files = storage.list_files('uploads/')
-files.each do |file|
-  puts "#{file['key']}: #{(file['size'] / 1024.0 / 1024.0).round(2)} MB"
-end
+auth.set_session(
+  access_token: res.session.access_token,
+  refresh_token: res.session.refresh_token
+)
 
-# Delete file
-storage.delete_file('uploads/document.pdf')
+user = auth.get_user
+puts user.email
 
-# Check storage quota
-quota = storage.get_quota
-puts "Used: #{quota['used_gb']} GB"
-puts "Available: #{quota['available_gb']} GB"
+auth.close
 ```
 
-## 📚 Usage Examples
-
-### Select Queries
+### Storage (buckets & files)
 
 ```ruby
-# Select all columns
-users = client.table('users').select('*').get
-
-# Select specific columns
-users = client.table('users')
-  .select('id', 'name', 'email')
-  .get
+storage = WOWSQL::WOWSQLStorage.new(
+  ENV.fetch('WOWSQL_PROJECT_URL'),
+  ENV.fetch('WOWSQL_SERVICE_KEY'),
+  base_domain: 'wowsql.com',
+  timeout: 60
+)
 
-# With filters
-active_users = client.table('users')
-  .select('id', 'name', 'email')
-  .eq('status', 'active')
-  .gt('age', 18)
-  .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')
 
-# With ordering
-recent_users = client.table('users')
-  .select('*')
-  .order_by('created_at', desc: true)
-  .limit(10)
-  .get
+storage.close
+```
 
-# With pagination
-page1 = client.table('users')
-  .select('*')
-  .limit(20)
-  .offset(0)
-  .get
+### Schema (service role only)
 
-page2 = client.table('users')
-  .select('*')
-  .limit(20)
-  .offset(20)
-  .get
+```ruby
+schema = WOWSQL::WOWSQLSchema.new(
+  ENV.fetch('WOWSQL_PROJECT_URL'),
+  ENV.fetch('WOWSQL_SERVICE_KEY')
+)
 
-# Pattern matching
-gmail_users = client.table('users')
-  .select('*')
-  .like('email', '%@gmail.com')
-  .get
+schema.create_table(
+  'notes',
+  [
+    { 'name' => 'id', 'type' => 'SERIAL', 'auto_increment' => true },
+    { 'name' => 'body', 'type' => 'TEXT', 'nullable' => false }
+  ],
+  primary_key: 'id'
+)
 
-# Get single record by ID
-user = client.table('users').get_by_id(123)
+schema.close
 ```
 
-### Insert Data
+---
 
-```ruby
-# Insert single record
-new_user = {
-  'name' => 'John Doe',
-  'email' => 'john@example.com',
-  'age' => 30,
-  'status' => 'active'
-}
-
-result = client.table('users').create(new_user)
-puts "New user ID: #{result['id']}"
-```
+## Concepts & API keys
 
-### Update Data
+| 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 |
 
-```ruby
-# Update by ID
-updates = {
-  'name' => 'Jane Smith',
-  'age' => 26
-}
-
-result = client.table('users').update(1, updates)
-puts "Updated #{result['affected_rows']} row(s)"
-```
+- **`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.
 
-### Delete Data
+Store keys in `ENV`, never commit them.
 
-```ruby
-# Delete by ID
-result = client.table('users').delete(1)
-puts "Deleted #{result['affected_rows']} row(s)"
-
-# Delete with conditions
-deleted = client.table('users')
-  .eq('status', 'deleted')
-  .delete
-```
+**Project URL:** full `https://{slug}.wowsql.com` or just the slug; the client normalizes against `base_domain` and `secure`.
 
-### Filter Operators
+---
+
+## Database: `WOWSQLClient`
 
 ```ruby
-# Equal
-.eq('status', 'active')
+WOWSQL::WOWSQLClient.new(
+  project_url,
+  api_key,
+  base_domain: 'wowsql.com',
+  secure: true,
+  timeout: 30,
+  verify_ssl: true
+)
+```
 
-# Not equal
-.neq('status', 'deleted')
+| 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. |
 
-# Greater than
-.gt('age', 18)
+**Reader:** `api_url`, `api_key`, `timeout`, `verify_ssl`.
 
-# Greater than or equal
-.gte('age', 18)
+---
 
-# Less than
-.lt('age', 65)
+## Table & `QueryBuilder`
 
-# Less than or equal
-.lte('age', 65)
+### `Table`
 
-# Pattern matching (SQL LIKE)
-.like('email', '%@gmail.com')
+Obtained via `client.table('name')`.
 
-# Is null
-.is_null('deleted_at')
+| 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. |
 
-# Is not null
-.is_not_null('email')
-```
+### `QueryBuilder`
 
-### Advanced Queries
+Chainable; ends with `get`, `execute`, `first`, `single`, `count`, or `paginate`.
 
-```ruby
-# Multiple filters with sorting
-active_users = client.table('users')
-  .select('id', 'name', 'email')
-  .eq('status', 'active')
-  .gt('age', 18)
-  .order_by('created_at', desc: true)
-  .limit(20)
-  .get
+**Filters:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `is_null`, `is_not_null`, `in_list`, `not_in`, `between`, `not_between`, `or_filter`.
 
-# Complex filtering
-results = client.table('products')
-  .select('*')
-  .gt('price', 100)
-  .lt('price', 1000)
-  .like('name', '%widget%')
-  .is_not_null('category')
-  .order_by('price', desc: false)  # asc
-  .limit(50)
-  .offset(0)
-  .get
-```
+**Grouping / aggregates:** `group_by(*columns)`, `having(column, operator, value)`.
 
-### Storage Operations
+**Sort / page:** `order_by`, `order`, `limit`, `offset`.
 
-```ruby
-storage = WOWSQL::WOWSQLStorage.new(
-  'your-project-slug',
-  'your-api-key'
-)
+**Terminal:**
 
-# Upload file from local path
-storage.upload_from_path(
-  'local-file.pdf',
-  'uploads/document.pdf',
-  'documents'  # bucket/folder
-)
+| 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. |
 
-# Check if file exists
-if storage.file_exists?('uploads/document.pdf')
-  puts "File exists!"
-end
+### Filter operators (string)
 
-# Get file information
-info = storage.get_file_info('uploads/document.pdf')
-puts "Size: #{info['size']} bytes"
-puts "Modified: #{info['last_modified']}"
+Use with `filter` or the shorthand methods:
 
-# List files with prefix
-files = storage.list_files('uploads/2024/')
-files.each do |file|
-  puts "#{file['key']}: #{file['size']} bytes"
-end
+`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.
 
-# Download file (get presigned URL)
-url_data = storage.get_file_url('uploads/document.pdf', 3600)
-puts "Download URL: #{url_data['file_url']}"
-# URL is valid for 1 hour (3600 seconds)
-
-# Delete single file
-storage.delete_file('uploads/old-file.pdf')
-
-# Delete multiple files
-storage.delete_files([
-  'uploads/file1.pdf',
-  'uploads/file2.pdf',
-  'uploads/file3.pdf'
-])
-
-# Check quota
-quota = storage.get_quota
-puts "Used: #{quota['used_gb'].round(2)} GB"
-puts "Available: #{quota['available_gb'].round(2)} GB"
-puts "Usage: #{quota['usage_percentage'].round(1)}%"
-
-# Check if enough storage before upload
-file_size = File.size('large-file.zip')
-if quota['available_bytes'] < file_size
-  puts "Not enough storage!"
-else
-  storage.upload_from_path('large-file.zip', 'uploads/large-file.zip')
-end
-```
+---
 
-### Error Handling
+## Authentication: `ProjectAuthClient`
 
 ```ruby
-begin
-  users = client.table('users').select('*').get
-  puts "Success: #{users['data'].count} users"
-rescue WOWSQL::AuthenticationException => e
-  puts "Authentication error: #{e.message}"
-rescue WOWSQL::NotFoundException => e
-  puts "Not found: #{e.message}"
-rescue WOWSQL::RateLimitException => e
-  puts "Rate limit exceeded: #{e.message}"
-rescue WOWSQL::WOWSQLException => e
-  puts "Database error (#{e.status_code}): #{e.message}"
-end
-
-begin
-  storage.upload_from_path('file.pdf', 'uploads/file.pdf')
-rescue WOWSQL::StorageLimitExceededException => e
-  puts "Storage full: #{e.message}"
-  puts "Please upgrade your plan or delete old files"
-rescue WOWSQL::StorageException => e
-  puts "Storage error: #{e.message}"
-end
+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
+)
 ```
 
-### Utility Methods
-
-```ruby
-# List all tables
-tables = client.list_tables
-puts "Tables: #{tables.inspect}"
-
-# Get table schema
-schema = client.get_table_schema('users')
-puts "Columns: #{schema['columns'].count}"
-schema['columns'].each do |column|
-  puts "  - #{column['name']} (#{column['type']})"
-end
-
-# Check API health
-health = client.health
-puts "Status: #{health['status']}"
-```
+### `TokenStorage` (module)
+
+Implement in your app for Redis/DB/session persistence:
+
+- `get_access_token` / `set_access_token(token)`
+- `get_refresh_token` / `set_refresh_token(token)`
+
+`WOWSQL::MemoryTokenStorage` is in-memory only.
+
+### Methods
+
+| 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` | |
+
+**Structs:** `AuthUser`, `AuthSession`, `AuthResponse` (see [Models](#models--types)).
 
-## 🔧 Configuration
+---
 
-### Custom Timeout
+## Storage: `WOWSQLStorage`
 
 ```ruby
-# Database client
-client = WOWSQL::WOWSQLClient.new(
-  'https://your-project.wowsql.com',
-  'your-api-key',
-  60  # 60 seconds timeout
-)
-
-# Storage client
-storage = WOWSQL::WOWSQLStorage.new(
-  'your-project-slug',
-  'your-api-key',
-  120  # 2 minutes for large files
+WOWSQL::WOWSQLStorage.new(
+  project_url = '',
+  api_key = '',
+  project_slug: '',
+  base_url: '',
+  base_domain: 'wowsql.com',
+  secure: true,
+  timeout: 60,
+  verify_ssl: true
 )
 ```
 
-### Using Environment Variables
+| 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`.
 
-```ruby
-# Best practice: Use environment variables for API keys
-client = WOWSQL::WOWSQLClient.new(
-  ENV['WOWSQL_PROJECT_URL'],
-  ENV['WOWSQL_API_KEY']
-)
+---
 
-storage = WOWSQL::WOWSQLStorage.new(
-  ENV['WOWSQL_PROJECT_URL'],
-  ENV['WOWSQL_API_KEY']
+## Schema: `WOWSQLSchema`
+
+**Requires service role key.**
+
+```ruby
+WOWSQL::WOWSQLSchema.new(
+  project_url,
+  service_key,
+  base_domain: 'wowsql.com',
+  secure: true,
+  timeout: 30,
+  verify_ssl: true
 )
 ```
 
-## 🔑 API Keys
+| 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` | |
+
+`operation` examples: `add_column`, `drop_column`, `modify_column`, `rename_column` (per API).
 
-WOWSQL uses **different API keys for different operations**. Understanding which key to use is crucial for proper authentication.
+---
+
+## Models & types
 
-### Key Types Overview
+### Auth (structs)
 
-| Operation Type | Recommended Key | Alternative Key | Used By |
-|---------------|----------------|-----------------|---------|
-| **Database Operations** (CRUD) | Service Role Key (`wowbase_service_...`) | Anonymous Key (`wowbase_anon_...`) | `WOWSQLClient` |
-| **Storage Operations** | Service Role Key (`wowbase_service_...`) | Anonymous Key (`wowbase_anon_...`) | `WOWSQLStorage` |
+- **`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`
 
-### Where to Find Your Keys
+### Storage
 
-All keys are found in: **WOWSQL Dashboard → Authentication → PROJECT KEYS**
+- **`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`
 
-1. **Service Role Key** (`wowbase_service_...`)
-   - Location: "Service Role Key (keep secret)"
-   - Used for: Database CRUD operations and storage (recommended for server-side)
-   - **Important**: Click the eye icon to reveal this key
+---
 
-2. **Anonymous Key** (`wowbase_anon_...`)
-   - Location: "Anonymous Key"
-   - Used for: Public/client-side database operations with limited permissions
-   - Optional: Use when exposing database access to frontend/client
+## Exceptions
 
-### Database Operations
+| 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. |
 
-Use **Service Role Key** or **Anonymous Key** for database operations:
+Aliases: `WOWSQLException`, `StorageException`, `StorageLimitExceededException`, `PermissionException` → map to the classes above.
 
 ```ruby
-# Using Service Role Key (recommended for server-side, full access)
-client = WOWSQL::WOWSQLClient.new(
-  'https://your-project.wowsql.com',
-  'wowbase_service_your-service-key-here'  # Service Role Key
-)
+begin
+  client.table('x').get
+rescue WOWSQL::WOWSQLError => e
+  warn "#{e.status_code}: #{e.message}"
+end
+```
 
-# Using Anonymous Key (for public/client-side access with limited permissions)
-client = WOWSQL::WOWSQLClient.new(
-  'https://your-project.wowsql.com',
-  'wowbase_anon_your-anon-key-here'  # Anonymous Key
-)
+---
 
-# Query data
-users = client.table('users').get
-```
+## Configuration
 
-### Security Best Practices
+| 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. |
 
-1. **Never expose Service Role Key** in client-side code or public repositories
-2. **Use Anonymous Key** for public database access with limited permissions
-3. **Store keys in environment variables**, never hardcode them
-4. **Rotate keys regularly** if compromised
+---
 
-## 🎨 Framework Integration
+## Rails integration
 
-### Rails
+**config/initializers/wowsql.rb**
 
 ```ruby
-# config/initializers/wowsql.rb
+# frozen_string_literal: true
+
 WOWSQL_CLIENT = WOWSQL::WOWSQLClient.new(
-  Rails.application.credentials.wowsql[:project_url],
-  Rails.application.credentials.wowsql[:api_key]
+  ENV.fetch('WOWSQL_PROJECT_URL'),
+  ENV.fetch('WOWSQL_SERVICE_KEY')
 )
 
-# app/models/user.rb
-class User < ApplicationRecord
-  def self.sync_from_wowsql
-    response = WOWSQL_CLIENT.table('users')
-      .select('*')
-      .get
-    
-    response['data'].each do |user_data|
-      User.find_or_create_by(external_id: user_data['id']) do |user|
-        user.name = user_data['name']
-        user.email = user_data['email']
-      end
-    end
-  end
-end
-
-# Usage in Controller
-class UsersController < ApplicationController
-  def index
-    @users = WOWSQL_CLIENT.table('users')
-      .select('id', 'name', 'email')
-      .get['data']
-  end
-end
+WOWSQL_AUTH = WOWSQL::ProjectAuthClient.new(
+  ENV.fetch('WOWSQL_PROJECT_URL'),
+  ENV.fetch('WOWSQL_ANON_KEY')
+)
 ```
 
-### Sinatra
+Use **service key** only in server-side code (jobs, controllers that must bypass restrictions). Prefer **anon** for end-user auth flows.
 
-```ruby
-require 'sinatra'
-require 'wowsql'
+---
 
-configure do
-  set :wowsql_client, WOWSQL::WOWSQLClient.new(
-    ENV['WOWSQL_PROJECT_URL'],
-    ENV['WOWSQL_API_KEY']
-  )
-end
+## Examples
 
-get '/users' do
-  users = settings.wowsql_client.table('users')
-    .select('id', 'name', 'email')
-    .get['data']
-  
-  content_type :json
-  users.to_json
-end
-```
+### Blog: posts and comments
 
-## 📋 Requirements
+```ruby
+posts = WOWSQL_CLIENT.table('posts')
+  .select('id', 'title')
+  .eq('published', true)
+  .order_by('created_at', 'desc')
+  .limit(20)
+  .get
 
-- Ruby 2.6.0 or higher
-- Faraday 2.0+
-- JSON 2.0+
+posts['data'].each do |p|
+  puts p['title']
+end
+```
 
-## 🔗 Links
+### Upload avatar then save URL in `public` table
 
-- 📚 [Documentation](https://wowsql.com/docs)
-- 🌐 [Website](https://wowsql.com)
-- 💬 [Discord](https://discord.gg/WOWSQL)
-- 🐛 [Issues](https://github.com/wowsql/wowsql/issues)
+```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
+```
 
-## 📄 License
+---
 
-MIT License - see [LICENSE](LICENSE) file for details.
+## Troubleshooting
 
-## 🤝 Contributing
+| 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. |
 
-Contributions are welcome! Please open an issue or submit a pull request.
+---
 
-## 📞 Support
+## Links
 
-- Email: support@wowsql.com
-- Discord: https://discord.gg/WOWSQL
-- Documentation: https://wowsql.com/docs
+- [WowSQL Docs](https://wowsql.com/docs)
+- [Dashboard](https://wowsql.com)
+- [Support](mailto:support@wowsql.com)
 
 ---
 
-Made with ❤️ by the WOWSQL Team
+**License:** MIT — see included `LICENSE`.
+
+*WowSQL Team*