pixeluvw_supabase 0.1.0

# pixeluvw_supabase


[![Crates.io](https://img.shields.io/crates/v/pixeluvw_supabase.svg)](https://crates.io/crates/pixeluvw_supabase)
[![Docs.rs](https://docs.rs/pixeluvw_supabase/badge.svg)](https://docs.rs/pixeluvw_supabase)
[![License](https://img.shields.io/crates/l/pixeluvw_supabase.svg)](https://opensource.org/licenses/MIT)

**A high-performance Rust SDK for [Supabase](https://supabase.com).**

Designed for reliability and improved developer experience, this crate provides a strongly-typed, fluent interface for interacting with the entire Supabase stack (Database, Auth, Realtime, Storage, and Edge Functions).

> **Note:** This SDK is currently in Beta. APIs are stable but may evolve.

## ✨ Features


- **🚀 Database**: Full PostgREST support with a fluent query builder, 25+ filters, and strong typing.
- **🔮 Schema Introspection**: Unique capability to fetch remote schema metadata at runtime and generate Rust structs.
- **🔐 Auth**: Complete authentication suite including Email/Password, OAuth, OTP, MFA, and Admin API.
- **⚡ Realtime**: Robust WebSocket client for listening to database changes (INSERT, UPDATE, DELETE), presence, and broadcast.
- **📦 Storage**: Simple API for file uploads, downloads, and signed URL generation.
- **serverless Functions**: Invoke Edge Functions seamlessly.
- **🛡️ Enterprise Ready**: Built-in middleware support, automatic retries with exponential backoff, and robust error handling.

## 📦 Installation


Add this to your `Cargo.toml`:

```toml
[dependencies]
pixeluvw_supabase = "0.1"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
dotenv = "0.15"
```

## 🚀 Quick Start


### 1. Setup Environment


Create a `.env` file in your project root (ensure it's in your `.gitignore`):

```env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-key
```

### 2. Basic Usage


```rust
use pixeluvw_supabase::{supabase, SupabaseClient};
use serde_json::json;

#[tokio::main]

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv::dotenv().ok();

    // Initialize the client (automatically loads from env)
    let client = supabase!()?;

    // Perform a query
    let users: Vec<serde_json::Value> = client
        .from("users")
        .select("*")
        .eq("status", "active")
        .limit(5)
        .execute()
        .await?;

    println!("Users: {:?}", users);

    Ok(())
}
```

## 📚 Guides


### Database


The query builder allows you to construct complex queries with ease.

```rust
// Select with multiple filters and ordering
let items = client
    .from("todos")
    .select("id, title, is_complete")
    .eq("user_id", "123")
    .is_("deleted_at", "null")
    .order("created_at", false) // descending
    .execute()
    .await?;

// Insert new data
client
    .from("todos")
    .insert(json!({ "title": "Buy milk", "user_id": "123" }))
    .execute()
    .await?;

// Update existing data
client
    .from("todos")
    .update(json!({ "is_complete": true }))
    .eq("id", 1)
    .execute()
    .await?;
```

#### Supported Filters

`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `is_`, `in_`, `contains`, `contained_by`, `range_gt`, `range_gte`, `range_lt`, `range_lte`, `range_adjacent`, `overlaps`, `text_search`, `match_`, `filter`, `not`, `or`, `and`.

### Authentication


Handle user sessions securely.

```rust
// Sign in with email and password
let session = client.auth().sign_in_with_password("user@example.com", "pass123").await?;

// The client automatically attaches the access token to subsequent requests!
// You can also access the user object:
println!("Logged in as: {}", session.user.id);

// Sign out
client.auth().sign_out().await?;
```

**OAuth Login:**
```rust
let url = client.auth().sign_in_with_oauth(
    pixeluvw_supabase::Provider::Github,
    Some("https://myapp.com/callback"), // redirect URL
    None, // scopes
)?;
// Redirect your user to `url`
```

### Realtime


Subscribe to database changes instantly.

```rust
use pixeluvw_supabase::PostgresEvent;
use tokio_stream::StreamExt;

let mut channel = client
    .realtime()
    .channel("room-1")
    .on_postgres_changes(
        PostgresEvent::Insert, 
        "public", 
        Some("messages"), 
        None // No filter
    )
    .subscribe()
    .await?;

// Listen for messages
while let Some(msg) = channel.next().await {
    println!("New event: {:?}", msg);
}
```

### Storage


Manage user files.

```rust
let bucket = client.storage().from("avatars");

// Upload a file
bucket.upload("user_123.png", "./local_path.png", None).await?;

// Get a public URL
let url = bucket.get_public_url("user_123.png")?;
```

## ⚙️ Configuration


You can customize the client behavior using `ClientConfig`.

```rust
use pixeluvw_supabase::{ClientConfig, SupabaseClient};

let config = ClientConfig {
    timeout_secs: 60,
    max_retries: 3,
    retry_base_delay_ms: 500,
};

let client = SupabaseClient::with_config("url", "key", config)?;
```

## 🤝 Contributing


Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License


This project is licensed under the [MIT License](LICENSE).