@temboplus/afloat 0.1.12 → 0.1.13

package/README.md

@@ -8,7 +8,7 @@ This JavaScript/TypeScript package provides a central hub for shared utilities,
 
 * **Abstracted Server Communication**
     * Simplifies front-end development by abstracting all interactions with the server behind model-specific repositories
-    * Front-end projects only need to interact with these repositories, decoupling them from the underlying API implementation
+    * Consuming projects only need to interact with these repositories, decoupling them from the underlying API implementation
 
 * **Shared Utilities**
     * Provides a collection of reusable helper functions for common tasks across Afloat projects, such as error handling
@@ -18,4 +18,122 @@ This JavaScript/TypeScript package provides a central hub for shared utilities,
 
 * **Enhanced Maintainability**
     * Centralizes common logic, making it easier to maintain and update across all consuming projects
-    * Reduces code duplication and improves consistency
+    * Reduces code duplication and improves consistency
+
+* **Cross-Environment Compatibility**
+    * Works seamlessly in both client-side and server-side environments
+    * Supports both synchronous and asynchronous initialization patterns
+
+## Usage
+
+### Authentication Setup
+
+#### Client-Side Usage
+
+In client-side applications, authentication is initialized synchronously:
+
+```typescript
+import { AfloatAuth } from "@temboplus/afloat";
+
+// Initialize client auth (typically in your app entry point)
+const auth = AfloatAuth.instance;
+
+// Check if user is authenticated
+console.log("User authenticated:", !!auth.currentUser);
+
+// Access current user
+const user = auth.currentUser;
+if (user) {
+  console.log(`Logged in as: ${user.email}`);
+}
+```
+
+#### Server-Side Usage
+
+In server-side environments, authentication requires asynchronous initialization:
+
+```typescript
+import { AfloatAuth } from "@temboplus/afloat";
+
+// In a server route handler or similar context
+async function handleRequest(req, res) {
+  try {
+    // Extract token from request
+    const token = req.headers.authorization?.replace('Bearer ', '');
+    
+    if (!token) {
+      return res.status(401).json({ error: 'Unauthorized' });
+    }
+    
+    // Initialize server-side auth
+    const auth = await AfloatAuth.initializeServer(token);
+    
+    // Now you can use auth for permission checks
+    const isAdmin = auth.checkPermission(Permissions.Payout.View);
+    
+    // Continue with your handler logic...
+  } catch (error) {
+    console.error('Authentication error:', error);
+    return res.status(500).json({ error: 'Authentication failed' });
+  }
+}
+```
+
+### Using Repositories
+
+Repositories provide a consistent interface for data operations across environments.
+
+#### Client-Side Repository Usage
+
+```typescript
+import { WalletRepo } from "@temboplus/afloat";
+
+// Create repository - auth is automatically handled
+const walletRepo = new WalletRepo();
+
+// Use repository methods
+async function displayBalance() {
+  try {
+    const balance = await walletRepo.getBalance();
+    console.log(`Current balance: ${balance}`);
+  } catch (error) {
+    console.error('Error fetching balance:', error);
+  }
+}
+```
+
+#### Server-Side Repository Usage
+
+```typescript
+import { AfloatAuth, WalletRepo } from "@temboplus/afloat";
+
+async function processServerRequest(token) {
+  // Initialize auth for this request
+  const auth = await AfloatAuth.initializeServer(token);
+  
+  // Create repository with explicit auth instance
+  const walletRepo = new WalletRepo({ auth });
+  
+  // Use repository methods
+  const balance = await walletRepo.getBalance();
+  const wallets = await walletRepo.getWallets();
+  
+  return { balance, wallets };
+}
+```
+
+## Best Practices
+
+1. **Client-Side Applications**
+   - Initialize `AfloatAuth.instance` early in your application lifecycle
+   - Create repositories without explicit auth parameters
+   - Handle permission errors appropriately in your UI
+
+2. **Server-Side Applications**
+   - Always use `await AfloatAuth.initializeServer(token)` for each request
+   - Pass the auth instance explicitly to repositories
+   - Implement proper error handling for authentication failures
+
+3. **Testing**
+   - Use the `AuthContext` to inject mock auth instances during testing
+   - Reset `AuthContext.current` after each test to prevent test pollution

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temboplus/afloat",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "A JavaScript/TypeScript package providing common utilities and logic shared across all Temboplus-Afloat Projects",
   "repository": {
     "type": "git",