@e-techsolutions/e-baas-sdk 1.0.7 → 1.0.8

package/README.md

@@ -1,23 +1,103 @@
 # E-BaaS SDK
 
-The official TypeScript SDK for E-BaaS (Enterprise Backend as a Service) - A comprehensive backend-as-a-service platform similar to Supabase.
+The official TypeScript SDK for E-BaaS (Enterprise Backend as a Service) - A comprehensive backend-as-a-service platform.
 
 ## Installation
 
 ```bash
-npm install @e-techsolutions/e-baas-sdk
+npm install @e-techsolutions/e-baas-sdk@latest
 # or
-yarn add @e-techsolutions/e-baas-sdk
+yarn add @e-techsolutions/e-baas-sdk@latest
 ```
 
 ## Quick Start
 
 ```typescript
-import { createClient } from '@e-techsolutions/e-baas-sdk';
+import { createClient } from "@e-techsolutions/e-baas-sdk";
 
-const ebaas = createClient('https://your-project.e-baas.apiservices.app.br', 'your-anon-key');
+// Basic configuration (required)
+const EBAAS_URL = process.env.EBAAS_API_URL; // required - https://your-api-e-baas-service
+const EBAAS_KEY = process.env.EBAAS_API_KEY; // required - your API key
+const WORKSPACE_ID = process.env.EBAAS_WORKSPACE_ID; // required - your workspace ID
+
+export const ebaas = createClient(EBAAS_URL, EBAAS_KEY, {
+  // Database configuration (required)
+  database: {
+    workspaceId: WORKSPACE_ID, // required
+    autoDetectCustomDatabase: true, // optional (default: false)
+  },
+  // Other configurations are optional
+});
 ```
 
+### Complete Authentication Flow
+
+```typescript
+// 1. User login
+const { user, session, error } = await ebaas.auth.signIn({
+  email: "user@example.com",
+  password: "secure-password",
+});
+
+if (error) {
+  console.error("Login failed:", error);
+  return;
+}
+
+// 2. Configure session in SDK (REQUIRED!)
+ebaas.auth.setSession(session);
+
+// 3. Persist session (optional)
+localStorage.setItem("ebaas_session", JSON.stringify(session));
+localStorage.setItem("ebaas_user", JSON.stringify(user));
+
+// 4. Now you can use database operations normally
+const { data: users, error } = await ebaas.from("users").select("*");
+
+if (error) {
+  console.error("Error fetching users:", error);
+} else {
+  console.log("Users found:", users.length);
+}
+```
+
+### Session Restoration
+
+```typescript
+// Restore session on app initialization
+const restoreSession = () => {
+  const savedSession = localStorage.getItem("ebaas_session");
+  const savedUser = localStorage.getItem("ebaas_user");
+
+  if (savedSession && savedUser) {
+    const sessionData = JSON.parse(savedSession);
+
+    // Check if not expired
+    if (sessionData.expires_at > Date.now()) {
+      // Restore session in SDK
+      ebaas.auth.setSession(sessionData);
+      console.log("✅ Session restored automatically");
+    } else {
+      // Clear expired session
+      localStorage.removeItem("ebaas_session");
+      localStorage.removeItem("ebaas_user");
+    }
+  }
+};
+```
+
+### Environment Variables
+
+Create a `.env` file in your project root:
+
+```env
+EBAAS_API_URL=https://your-api-e-baas-service
+EBAAS_API_KEY=your-api-key-here
+EBAAS_WORKSPACE_ID=your-workspace-id-here
+```
+
+**Note**: This works with any bundler (Webpack, Vite, Next.js, etc.) that supports `process.env`.
+
 ## Features
 
 - **Authentication** - Email/password and OAuth providers (Google, GitHub, Facebook)
@@ -35,15 +115,15 @@ const ebaas = createClient('https://your-project.e-baas.apiservices.app.br', 'yo
 ```typescript
 // Sign up with email/password
 const { user, session, error } = await ebaas.auth.signUp({
-  email: 'user@example.com',
-  password: 'secure-password',
-  name: 'John Doe'
+  email: "user@example.com",
+  password: "secure-password",
+  name: "John Doe",
 });
 
 // Sign in
 const { user, session, error } = await ebaas.auth.signIn({
-  email: 'user@example.com',
-  password: 'secure-password'
+  email: "user@example.com",
+  password: "secure-password",
 });
 
 // Get current user
@@ -53,51 +133,109 @@ const user = await ebaas.auth.getUser();
 await ebaas.auth.signOut();
 ```
 
+**⚠️ IMPORTANT - Session Configuration:**
+
+After login, you **MUST** configure the session in the SDK for all subsequent operations to work correctly:
+
+```typescript
+// Complete authentication flow
+const loginUser = async () => {
+  // 1. Perform login
+  const { user, session, error } = await ebaas.auth.signIn({
+    email: "user@example.com",
+    password: "secure-password",
+  });
+
+  if (error) {
+    console.error("Login failed:", error);
+    return;
+  }
+
+  // 2. Configure session in SDK (MANDATORY STEP!)
+  ebaas.auth.setSession(session);
+
+  // 3. Persist session in localStorage (optional)
+  localStorage.setItem("ebaas_session", JSON.stringify(session));
+  localStorage.setItem("ebaas_user", JSON.stringify(user));
+
+  console.log("✅ Login and session configuration completed");
+};
+
+// Restore session on application initialization
+const restoreSession = () => {
+  const savedSession = localStorage.getItem("ebaas_session");
+  const savedUser = localStorage.getItem("ebaas_user");
+
+  if (savedSession && savedUser) {
+    const sessionData = JSON.parse(savedSession);
+
+    // Check if not expired
+    if (sessionData.expires_at > Date.now()) {
+      // Restore session in SDK
+      ebaas.auth.setSession(sessionData);
+      console.log("✅ Session restored automatically");
+    } else {
+      // Clear expired session
+      localStorage.removeItem("ebaas_session");
+      localStorage.removeItem("ebaas_user");
+    }
+  }
+};
+```
+
 ### Database Operations
 
 ```typescript
-// Select data (GET /sdk/v1/users?operation=select&select=id,name,email&status=eq.active)
-// IMPORTANTE: Campos sensíveis (password, hash, token, secret, key) são automaticamente 
-// excluídos quando usando select='*' por motivos de segurança
-const { data, error } = await ebaas
-  .from('users')
-  .select('id, name, email') // Especificar campos explicitamente é mais seguro
-  .eq('status', 'active')
-  .order('created_at', { ascending: false })
-  .limit(10)
-  .execute();
-
-// Para incluir todos os campos (incluindo sensíveis), especifique explicitamente:
-const { data, error } = await ebaas
-  .from('users')
-  .select('id, name, email, password') // Explícito para incluir campo sensível
-  .execute();
+// Select data
+const { data: users, error } = await ebaas.from("users").select("*");
 
-// Insert data (POST /sdk/v1/users?operation=insert)
-// Retorna automaticamente os dados inseridos (com campos sensíveis filtrados)
-const { data, error } = await ebaas
-  .from('users')
-  .insert([
-    { name: 'John Doe', email: 'john@example.com' },
-    { name: 'Jane Smith', email: 'jane@example.com' }
-  ]); // data contém os registros criados com IDs gerados
+if (error) {
+  console.error("Error fetching users:", error);
+} else {
+  console.log("Users found:", users.length);
+}
 
-// Update data (PATCH /sdk/v1/users?operation=update&id=eq.123)
+// Select specific fields for better performance
 const { data, error } = await ebaas
-  .from('users')
-  .update({ status: 'inactive' })
-  .eq('id', 123);
+  .from("users")
+  .select("id, name, email")
+  .eq("status", "active")
+  .order("created_at", { ascending: false })
+  .limit(10);
+
+// Insert data
+const { data: newUser, error: insertError } = await ebaas.from("users").insert({
+  name: "John Doe",
+  email: "john@example.com",
+});
 
-// Delete data (DELETE /sdk/v1/users?operation=delete&id=eq.123)
-// IMPORTANTE: DELETE requer pelo menos um filtro por motivos de segurança
-const { data, error } = await ebaas
-  .from('users')
-  .delete()
-  .eq('id', 123); // Filtro obrigatório para segurança
+if (insertError) {
+  console.error("Error creating user:", insertError);
+} else {
+  console.log("User created successfully:", newUser);
+}
+
+// Update data
+const { data: updated, error: updateError } = await ebaas.from("users").update({ name: "John Smith" }).eq("id", 123);
+
+if (updateError) {
+  console.error("Error updating user:", updateError);
+} else {
+  console.log("User updated successfully:", updated);
+}
+
+// Delete data
+const { data, error } = await ebaas.from("users").delete().eq("id", 123);
+
+if (error) {
+  console.error("Error deleting user:", error);
+} else {
+  console.log("User deleted successfully");
+}
 
 // RPC (stored procedures)
-const { data, error } = await ebaas.rpc('get_user_stats', {
-  user_id: 123
+const { data, error } = await ebaas.rpc("get_user_stats", {
+  user_id: 123,
 });
 ```
 
@@ -105,105 +243,68 @@ const { data, error } = await ebaas.rpc('get_user_stats', {
 
 ```typescript
 // Configure with automatic custom database detection
-const ebaas = createClient(url, key, {
+const ebaas = createClient(EBAAS_URL, EBAAS_KEY, {
   database: {
-    workspaceId: 'your-workspace-id',
-    autoDetectCustomDatabase: true
-  }
+    workspaceId: WORKSPACE_ID,
+    autoDetectCustomDatabase: true, // Enable custom database auto-detection
+  },
 });
-
-// Configure custom database credentials
-const credentials = {
-  host: 'your-postgres-host.com',
-  port: 5432,
-  database: 'your_custom_db',
-  username: 'db_user',
-  password: 'db_password',
-  schema: 'custom_schema',
-  sslEnabled: true
-};
-
-// Test connection
-const testResult = await ebaas.database.testCustomConnection(credentials);
-if (testResult.success) {
-  await ebaas.database.configureCustomDatabase(credentials);
-}
-
-// Check status
-const status = ebaas.getCustomDatabaseStatus();
-console.log('Using custom database:', status.hasConfig);
-
-// Use with different schema (GET /sdk/v1/users?operation=select&select=*)
-const data = await ebaas.database
-  .schema('custom_schema')
-  .from('users')
-  .select('*')
-  .execute();
 ```
 
-For detailed information about custom database features, see [Custom Database Guide](./CUSTOM_DATABASE_GUIDE.md).
-
 ### Storage
 
 ```typescript
 // Upload file
-const { data, error } = await ebaas.storage
-  .from('avatars')
-  .upload('user-123.jpg', file, {
-    cacheControl: '3600',
-    upsert: true
-  });
+const { data, error } = await ebaas.storage.from("avatars").upload("user-123.jpg", file, {
+  cacheControl: "3600",
+  upsert: true,
+});
 
 // Download file
-const { data, error } = await ebaas.storage
-  .from('avatars')
-  .download('user-123.jpg');
+const { data, error } = await ebaas.storage.from("avatars").download("user-123.jpg");
 
 // Get public URL
-const { data } = ebaas.storage
-  .from('avatars')
-  .getPublicUrl('user-123.jpg');
+const { data } = ebaas.storage.from("avatars").getPublicUrl("user-123.jpg");
 
 // Get signed URL (for private files)
-const { data, error } = await ebaas.storage
-  .from('private-docs')
-  .createSignedUrl('document.pdf', 60); // 60 seconds
+const { data, error } = await ebaas.storage.from("private-docs").createSignedUrl("document.pdf", 60); // 60 seconds
 
 // List files
-const { data, error } = await ebaas.storage
-  .from('avatars')
-  .list('', {
-    limit: 100,
-    offset: 0,
-    sortBy: { column: 'name', order: 'asc' }
-  });
+const { data, error } = await ebaas.storage.from("avatars").list("", {
+  limit: 100,
+  offset: 0,
+  sortBy: { column: "name", order: "asc" },
+});
 ```
 
 ### Realtime Subscriptions
 
 ```typescript
 // Subscribe to database changes
-const channel = ebaas.channel('realtime:users');
-
-channel.onPostgresChanges({
-  event: '*', // INSERT, UPDATE, DELETE, or *
-  schema: 'public',
-  table: 'users'
-}, (payload) => {
-  console.log('Change received!', payload);
-});
+const channel = ebaas.channel("realtime:users");
+
+channel.onPostgresChanges(
+  {
+    event: "*", // INSERT, UPDATE, DELETE, or *
+    schema: "public",
+    table: "users",
+  },
+  (payload) => {
+    console.log("Change received!", payload);
+  }
+);
 
 channel.subscribe();
 
 // Broadcast messages
 channel.send({
-  type: 'broadcast',
-  event: 'message',
-  payload: { text: 'Hello World!' }
+  type: "broadcast",
+  event: "message",
+  payload: { text: "Hello World!" },
 });
 
 // Presence tracking
-channel.track({ user_id: 123, status: 'online' });
+channel.track({ user_id: 123, status: "online" });
 
 // Unsubscribe
 channel.unsubscribe();
@@ -214,144 +315,118 @@ channel.unsubscribe();
 #### Client-side Function Invocation
 
 ```typescript
-// Invoke function from client
-const { data, error } = await ebaas.functions.invoke('hello-world', {
-  body: { name: 'John' },
-  headers: { 'Content-Type': 'application/json' }
+// Invoke authenticated function (requires session)
+const { data, error } = await ebaas.functions.invoke("hello-world", {
+  body: { name: "John" },
+  headers: { "Content-Type": "application/json" },
+});
+
+// Invoke public function (no authentication required)
+const response = await fetch("https://your-api-domain.com/functions/v1/public/hello-world", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: "John" }),
 });
+const data = await response.json();
 
 // List functions
 const { data, error } = await ebaas.functions.list();
 
 // Get function details
-const { data, error } = await ebaas.functions.get('hello-world');
+const { data, error } = await ebaas.functions.get("hello-world");
 ```
 
 #### Native SDK Integration in Edge Functions
 
-**NEW in v1.0.1+**: The SDK is now natively available within Edge Functions:
+The SDK is natively available within Edge Functions with global methods:
 
 ```typescript
-// Edge Function example with native SDK access
-const { method, url } = req;
-
-if (method === 'POST') {
-  const body = await req.json();
-  
-  // Native database access - no imports needed!
-  const users = await from('users').select('*').limit(10);
-  
-  // Native storage access
-  const bucket = bucket('uploads');
-  await bucket.upload('file.jpg', body.fileData);
-  
-  // Native realtime notifications
-  await channel('notifications').send('user_created', { 
-    user: body.userData 
-  });
-  
-  // Call other edge functions
-  const result = await invoke('send-email', { 
-    body: { email: body.email } 
-  });
-  
-  return createResponse({ success: true, users, result });
-}
+// Edge Function with native SDK access
+const users = await from("users").select("*").limit(10);
+const bucket = bucket("uploads");
+await channel("notifications").send("user_created", { user: userData });
+return createResponse({ success: true, users });
 ```
 
-#### Available Globals in Edge Functions
-
-- `from(table)` - Database table access
-- `rpc(function, args)` - RPC calls
-- `bucket(name)` - Storage bucket access  
-- `channel(name)` - Realtime channel access
-- `invoke(functionName, options)` - Function orchestration
-- `ebaas.*` - Full SDK object access
-- `env.*` - Environment variables
-- `context.*` - Function execution context
+**Available globals**: `from()`, `rpc()`, `bucket()`, `channel()`, `invoke()`, `ebaas.*`
 
 ## Advanced Configuration
 
 ```typescript
-const ebaas = createClient('https://your-project.e-baas.io', 'your-anon-key', {
-  auth: {
-    autoRefreshToken: true,
-    persistSession: true,
-    detectSessionInUrl: true
-  },
-  realtime: {
-    params: {
-      eventsPerSecond: 10
-    }
-  },
-  global: {
-    headers: {
-      'x-custom-header': 'custom-value'
-    }
+const ebaas = createClient(
+  "https://your-api-domain.com", // required - API URL
+  "your-api-key", // required - API Key
+  {
+    // Database configuration (required)
+    database: {
+      workspaceId: "your-workspace-id", // required - Workspace ID
+      autoDetectCustomDatabase: true, // optional (default: false)
+    },
+    // Authentication configuration (optional)
+    auth: {
+      autoRefreshToken: true, // optional (default: true)
+      persistSession: true, // optional (default: true)
+      detectSessionInUrl: true, // optional (default: true)
+    },
+    // Realtime configuration (optional)
+    realtime: {
+      params: {
+        eventsPerSecond: 10, // optional (default: 10)
+      },
+    },
+    // Global configuration (optional)
+    global: {
+      headers: {
+        "x-custom-header": "custom-value", // optional - custom headers
+      },
+    },
   }
-});
+);
 ```
 
 ## Error Handling
 
 ```typescript
-import { EBaaSError } from '@e-techsolutions/e-baas-sdk';
+import { EBaaSError } from "@e-techsolutions/e-baas-sdk";
 
 try {
-  // GET /sdk/v1/users?operation=select&select=*
-  const { data } = await ebaas.from('users').select('*').execute();
+  const { data } = await ebaas.from("users").select("*");
 } catch (error) {
   if (error instanceof EBaaSError) {
-    console.error('E-BaaS Error:', error.message);
-    console.error('Status:', error.status);
-    console.error('Details:', error.details);
+    console.error("E-BaaS Error:", error.message);
+    console.error("Status:", error.status);
+    console.error("Details:", error.details);
   }
 }
 ```
 
-## Operações DELETE Seguras
+## Secure DELETE Operations
+
+### Security Validation
 
-### Validação de Segurança
-O E-BaaS implementa validação rigorosa para operações DELETE e UPDATE, exigindo **pelo menos um filtro** para prevenir exclusões acidentais em massa:
+E-BaaS implements strict validation for DELETE and UPDATE operations, requiring **at least one filter** to prevent accidental mass deletions:
 
 ```typescript
-// ✅ CORRETO: DELETE com filtro específico
-const { data, error } = await ebaas
-  .from('users')
-  .delete()
-  .eq('id', 123);
+// ✅ CORRECT: DELETE with specific filter
+const { data, error } = await ebaas.from("users").delete().eq("id", 123);
 
-// ❌ ERRO: DELETE sem filtros (retorna "Security violation")
-const { data, error } = await ebaas
-  .from('users')
-  .delete(); // Falha com erro de segurança
+// ❌ ERROR: DELETE without filters (returns "Security violation")
+const { data, error } = await ebaas.from("users").delete(); // Fails with security error
 ```
 
-### Workaround para Casos Específicos
-Em casos onde o SDK nativo apresenta problemas com operações DELETE, você pode usar requisições HTTP diretas:
+### Secure DELETE Operations with Required Filters
+
+Always use the SDK with proper filters for safe DELETE operations:
 
 ```typescript
-// Workaround usando fetch direta
-const deleteUser = async (userId, session, workspaceId, apiUrl, apiKey) => {
-  const url = `${apiUrl}/sdk/v1/users?operation=delete&id=${userId}`;
-  
-  const response = await fetch(url, {
-    method: 'DELETE',
-    headers: {
-      'Authorization': `Bearer ${session.access_token}`,
-      'apikey': apiKey,
-      'x-workspace-id': workspaceId,
-      'Content-Type': 'application/json'
-    }
-  });
-  
-  if (!response.ok) {
-    const errorData = await response.json();
-    throw new Error(errorData.error || `HTTP ${response.status}`);
-  }
-  
-  return { error: null };
-};
+// DELETE using SDK with required filter
+const { data, error } = await ebaas.from("users").delete().eq("id", userId);
+
+if (error) {
+  console.error("Error deleting user:", error);
+} else {
+  console.log("User deleted successfully");
+}
 ```
 
 ## TypeScript Support
@@ -366,90 +441,15 @@ interface User {
   created_at: string;
 }
 
-// GET /sdk/v1/users?operation=select&select=*
-const { data, error } = await ebaas
-  .from<User>('users')
-  .select('*')
-  .execute();
+const { data, error } = await ebaas.from<User>("users").select("*");
 
 // data is now typed as User[] | null
 ```
 
 ## Edge Functions Runtime Support
 
-**NEW in v1.0.1+**: Enhanced Edge Functions with dual runtime support:
-
-### Runtime Options
-- **Node.js VM** (Default) - Docker/K3s friendly, isolated-vm execution
-- **Deno** (Optional) - TypeScript-first runtime with Web APIs
-
-### Features
-- **Native SDK Integration** - Full platform access within functions
-- **Auto-detected Runtime** - Automatically chooses Node.js in Docker environments
-- **Secure Execution** - Isolated VM with memory and timeout limits
-- **Function Orchestration** - Functions can call other functions
-- **Supabase-compatible API** - Same developer experience as Supabase Edge Functions
-
-### Example Edge Function
-
-```typescript
-// my-function.ts
-const { method, url } = req;
-
-// CORS handling
-if (method === 'OPTIONS') {
-  return corsResponse(createResponse(null, { status: 200 }));
-}
-
-try {
-  // Database operations
-  const users = await from('users').select('name, email').limit(5);
-  
-  // Storage operations  
-  const files = await bucket('uploads').list('public/');
-  
-  // Realtime notifications
-  await channel('notifications').send('function_executed', {
-    timestamp: new Date().toISOString(),
-    userCount: users.data?.length || 0
-  });
-  
-  // Function orchestration
-  const emailResult = await invoke('send-notification', {
-    body: { message: 'Function executed successfully' }
-  });
-  
-  return createResponse({
-    success: true,
-    users: users.data,
-    files: files.data,
-    emailSent: emailResult.data
-  });
-  
-} catch (error) {
-  console.error('Function error:', error);
-  return createResponse({ error: error.message }, { status: 500 });
-}
-```
-
-## Changelog
-
-### v1.0.8 (2025-07-17)
-- 🔧 **FIX**: Correção crítica em operações DELETE no SDK
-- 🔧 **FIX**: Implementação de workaround HTTP para casos de falha do SDK nativo
-- 📚 **DOCS**: Documentação expandida sobre operações DELETE seguras
-- 🛡️ **SECURITY**: Validação rigorosa de filtros em operações DELETE/UPDATE
-- ✅ **TESTED**: Operações DELETE testadas e confirmadas funcionando
-
-### v1.0.1 (2024-06-24)
-- 🚀 **NEW**: Native SDK integration in Edge Functions
-- 🚀 **NEW**: Dual runtime support (Node.js VM + Deno)
-- 🚀 **NEW**: Auto-runtime detection for Docker environments
-- 🚀 **NEW**: Global SDK methods in Edge Functions
-- 🚀 **NEW**: Function orchestration capabilities
-- 🔧 Enhanced security with isolated VM execution
-- 🔧 Improved Docker/K3s compatibility
+Enhanced Edge Functions with dual runtime support (Node.js VM + Deno) and native SDK integration.
 
 ## License
 
-MIT
+MIT