@e-techsolutions/e-baas-sdk 1.1.2 → 1.1.4

package/README.md

@@ -52,7 +52,8 @@ 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("*");
+const query = ebaas.from("users").select("*");
+const { data, error } = await query.execute();
 
 if (error) {
   console.error("Error fetching users:", error);
@@ -187,45 +188,50 @@ const restoreSession = () => {
 
 ```typescript
 // Select data
-const { data: users, error } = await ebaas.from("users").select("*");
+const query = ebaas.from("users").select("*");
+const { data, error } = await query.execute();
 
 if (error) {
   console.error("Error fetching users:", error);
 } else {
-  console.log("Users found:", users.length);
+  console.log("Users found:", data.length);
 }
 
 // Select specific fields for better performance
-const { data, error } = await ebaas
+const query = ebaas
   .from("users")
   .select("id, name, email")
   .eq("status", "active")
   .order("created_at", { ascending: false })
   .limit(10);
+const { data, error } = await query.execute();
 
 // Insert data
-const { data: newUser, error: insertError } = await ebaas.from("users").insert({
+const query = ebaas.from("users").insert({
   name: "John Doe",
   email: "john@example.com",
 });
+const { data, error } = await query.execute();
 
-if (insertError) {
-  console.error("Error creating user:", insertError);
+if (error) {
+  console.error("Error creating user:", error);
 } else {
-  console.log("User created successfully:", newUser);
+  console.log("User created successfully:", data);
 }
 
 // Update data
-const { data: updated, error: updateError } = await ebaas.from("users").update({ name: "John Smith" }).eq("id", 123);
+const query = ebaas.from("users").update({ name: "John Smith" }).eq("id", 123);
+const { data, error } = await query.execute();
 
-if (updateError) {
-  console.error("Error updating user:", updateError);
+if (error) {
+  console.error("Error updating user:", error);
 } else {
-  console.log("User updated successfully:", updated);
+  console.log("User updated successfully:", data);
 }
 
 // Delete data
-const { data, error } = await ebaas.from("users").delete().eq("id", 123);
+const query = ebaas.from("users").delete().eq("id", 123);
+const { data, error } = await query.execute();
 
 if (error) {
   console.error("Error deleting user:", error);
@@ -234,9 +240,10 @@ if (error) {
 }
 
 // RPC (stored procedures)
-const { data, error } = await ebaas.rpc("get_user_stats", {
+const query = ebaas.rpc("get_user_stats", {
   user_id: 123,
 });
+const { data, error } = await query.execute();
 ```
 
 ### Custom Database
@@ -390,7 +397,8 @@ const ebaas = createClient(
 import { EBaaSError } from "@e-techsolutions/e-baas-sdk";
 
 try {
-  const { data } = await ebaas.from("users").select("*");
+  const query = ebaas.from("users").select("*");
+  const { data, error } = await query.execute();
 } catch (error) {
   if (error instanceof EBaaSError) {
     console.error("E-BaaS Error:", error.message);
@@ -408,10 +416,12 @@ E-BaaS implements strict validation for DELETE and UPDATE operations, requiring
 
 ```typescript
 // ✅ CORRECT: DELETE with specific filter
-const { data, error } = await ebaas.from("users").delete().eq("id", 123);
+const query = ebaas.from("users").delete().eq("id", 123);
+const { data, error } = await query.execute();
 
 // ❌ ERROR: DELETE without filters (returns "Security violation")
-const { data, error } = await ebaas.from("users").delete(); // Fails with security error
+const query = ebaas.from("users").delete();
+const { data, error } = await query.execute(); // Fails with security error
 ```
 
 ### Secure DELETE Operations with Required Filters
@@ -420,7 +430,8 @@ Always use the SDK with proper filters for safe DELETE operations:
 
 ```typescript
 // DELETE using SDK with required filter
-const { data, error } = await ebaas.from("users").delete().eq("id", userId);
+const query = ebaas.from("users").delete().eq("id", userId);
+const { data, error } = await query.execute();
 
 if (error) {
   console.error("Error deleting user:", error);
@@ -429,6 +440,201 @@ if (error) {
 }
 ```
 
+## Refresh Token Management
+
+### Automatic Token Refresh (Default)
+
+The E-BaaS SDK automatically manages refresh tokens for workspace users, ensuring seamless authentication without manual intervention:
+
+```typescript
+const ebaas = createClient(EBAAS_URL, EBAAS_KEY, {
+  database: {
+    workspaceId: WORKSPACE_ID,
+  },
+  auth: {
+    autoRefreshToken: true, // Default: true - automatic refresh enabled
+    persistSession: true,   // Default: true - session persistence
+  },
+});
+```
+
+### How Automatic Refresh Works
+
+1. **Login Phase**: When a user logs in, they receive both an access token and a refresh token
+2. **Background Monitoring**: The SDK monitors token expiration automatically
+3. **Seamless Refresh**: Before expiration, the SDK calls `/auth/v1/sdk/refresh` to get new tokens
+4. **Token Rotation**: Old refresh tokens are invalidated for security (refresh token rotation)
+5. **Continued Operation**: All database operations continue without interruption
+
+### Manual Refresh Token Management
+
+For advanced use cases, you can disable automatic refresh and manage tokens manually:
+
+```typescript
+const ebaas = createClient(EBAAS_URL, EBAAS_KEY, {
+  database: {
+    workspaceId: WORKSPACE_ID,
+  },
+  auth: {
+    autoRefreshToken: false, // Disable automatic refresh
+  },
+});
+
+// Manual refresh when needed
+const refreshTokens = async () => {
+  try {
+    const query = ebaas.auth.refreshSession();
+    const { data, error } = await query.execute();
+    
+    if (error) {
+      console.error('Failed to refresh token:', error);
+      // Redirect to login page
+      return;
+    }
+    
+    // Update session in SDK
+    ebaas.auth.setSession(data.session);
+    
+    // Update localStorage
+    localStorage.setItem('ebaas_session', JSON.stringify(data.session));
+    
+    console.log('✅ Tokens refreshed successfully');
+  } catch (error) {
+    console.error('Token refresh error:', error);
+    // Handle refresh failure - redirect to login
+  }
+};
+```
+
+### React Hook for Token Management
+
+Here's a custom React hook for handling token refresh and expiration:
+
+```typescript
+import { useEffect, useCallback } from 'react';
+import { ebaas } from './ebaas-client';
+
+export const useTokenRefresh = () => {
+  const checkTokenExpiration = useCallback(async () => {
+    const session = ebaas.auth.getSession();
+    
+    if (!session?.expires_at) return;
+    
+    const expiresAt = new Date(session.expires_at);
+    const now = new Date();
+    const timeToExpiry = expiresAt.getTime() - now.getTime();
+    
+    // Refresh if token expires in less than 5 minutes
+    if (timeToExpiry < 5 * 60 * 1000) {
+      try {
+        const query = ebaas.auth.refreshSession();
+        const { data, error } = await query.execute();
+        
+        if (error) {
+          console.error('Token refresh failed:', error);
+          // Redirect to login
+          window.location.href = '/login';
+          return;
+        }
+        
+        // Update session
+        ebaas.auth.setSession(data.session);
+        localStorage.setItem('ebaas_session', JSON.stringify(data.session));
+        
+        console.log('✅ Token refreshed proactively');
+      } catch (error) {
+        console.error('Token refresh error:', error);
+        // Handle error - redirect to login
+        window.location.href = '/login';
+      }
+    }
+  }, []);
+  
+  useEffect(() => {
+    // Check immediately
+    checkTokenExpiration();
+    
+    // Check every 2 minutes
+    const interval = setInterval(checkTokenExpiration, 2 * 60 * 1000);
+    
+    return () => clearInterval(interval);
+  }, [checkTokenExpiration]);
+};
+
+// Usage in your main App component
+const App = () => {
+  useTokenRefresh(); // Add this hook to your main App
+  
+  return (
+    <div>
+      {/* Your app content */}
+    </div>
+  );
+};
+```
+
+### Token Refresh Error Handling
+
+```typescript
+const handleDatabaseOperation = async () => {
+  try {
+    const query = ebaas.from('users').select('*');
+    const { data, error } = await query.execute();
+    
+    if (error) {
+      // Check if error is due to token expiration
+      if (error.status === 401 || error.message?.includes('token')) {
+        console.log('Token expired, attempting refresh...');
+        
+        const { session, error } = await ebaas.auth.refreshSession();
+        
+        if (error) {
+          // Refresh failed - redirect to login
+          console.error('Token refresh failed:', error);
+          window.location.href = '/login';
+          return;
+        }
+        
+        // Update session and retry operation
+        ebaas.auth.setSession(session);
+        const { data, error } = await query.execute();
+        
+        if (!error) {
+          console.log('✅ Operation successful after token refresh');
+          return data;
+        }
+      }
+      
+      console.error('Database operation failed:', error);
+    }
+    
+    return data;
+  } catch (error) {
+    console.error('Unexpected error:', error);
+  }
+};
+```
+
+### Security Benefits
+
+- **Token Rotation**: Each refresh generates new tokens and invalidates old ones
+- **Short-lived Access Tokens**: Access tokens have shorter lifespans for security
+- **Automatic Cleanup**: Expired and revoked tokens are automatically cleaned up
+- **Session Tracking**: Each session is tracked with IP address and user agent
+- **Workspace Isolation**: Refresh tokens are isolated per workspace for multi-tenancy
+
+### Configuration Options
+
+```typescript
+const ebaas = createClient(EBAAS_URL, EBAAS_KEY, {
+  auth: {
+    autoRefreshToken: true,    // Enable/disable automatic refresh
+    persistSession: true,      // Persist session in localStorage
+    detectSessionInUrl: true,  // Detect session from URL params
+  },
+});
+```
+
 ## TypeScript Support
 
 The SDK is built with TypeScript and provides full type safety:
@@ -441,7 +647,8 @@ interface User {
   created_at: string;
 }
 
-const { data, error } = await ebaas.from<User>("users").select("*");
+const query = ebaas.from<User>("users").select("*");
+const { data, error } = await query.execute();
 
 // data is now typed as User[] | null
 ```