@temboplus/afloat 0.1.60 → 0.1.62

package/README.md

@@ -1,8 +1,6 @@
 # @temboplus/afloat
 
-**A foundational library for Temboplus-Afloat projects.**
-
-This JavaScript/TypeScript package provides a central hub for shared utilities, logic, and data access mechanisms within the Temboplus-Afloat ecosystem. 
+A foundational JavaScript/TypeScript library for TemboPlus-Afloat projects, providing abstracted server communication, shared utilities, and standardized data models for consistent development.
 
 ## Key Features
 
@@ -22,7 +20,7 @@ This JavaScript/TypeScript package provides a central hub for shared utilities,
 
 * **Cross-Environment Compatibility**
     * Works seamlessly in both client-side and server-side environments
-    * Supports both synchronous and asynchronous initialization patterns
+    * Different patterns for client-side authentication management vs server-side token handling
 
 ## Usage
 
@@ -30,7 +28,7 @@ This JavaScript/TypeScript package provides a central hub for shared utilities,
 
 #### Client-Side Usage
 
-In client-side applications, authentication is initialized synchronously:
+In client-side applications, use the `AfloatAuth` singleton for authentication management:
 
 ```typescript
 import { AfloatAuth } from "@temboplus/afloat";
@@ -39,42 +37,67 @@ import { AfloatAuth } from "@temboplus/afloat";
 const auth = AfloatAuth.instance;
 
 // Check if user is authenticated
-console.log("User authenticated:", !!auth.currentUser);
+console.log("User authenticated:", auth.isAuthenticated);
 
 // Access current user
 const user = auth.currentUser;
 if (user) {
   console.log(`Logged in as: ${user.email}`);
 }
+
+// Login a user
+try {
+  const user = await auth.logIn("user@example.com", "password123");
+  console.log("Login successful!");
+} catch (error) {
+  console.error("Login failed:", error.message);
+}
+
+// Check permissions
+if (auth.checkPermission(Permission.ViewBalance)) {
+  console.log("User can view balance");
+}
+
+// React hook for reactive user state
+function UserProfile() {
+  const user = auth.useCurrentUser();
+  
+  if (!user) {
+    return <LoginForm />;
+  }
+  
+  return <div>Hello, {user.name}!</div>;
+}
 ```
 
 #### Server-Side Usage
 
-In server-side environments, authentication requires asynchronous initialization:
+In server-side environments, **do not use `AfloatAuth`**. Instead, extract the authentication token from requests and pass it directly to repositories:
 
 ```typescript
-import { AfloatAuth } from "@temboplus/afloat";
+import { WalletRepository } from "@temboplus/afloat";
 
-// In a server route handler or similar context
+// In a server route handler or API endpoint
 async function handleRequest(req, res) {
   try {
-    // Extract token from request
+    // Extract token from request headers
     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);
+    // Create repository with explicit token
+    const walletRepo = new WalletRepository({ token });
     
-    // Now you can use auth for permission checks
-    const isAdmin = auth.checkPermission(Permissions.Payout.View);
+    // Use repository methods directly
+    const balance = await walletRepo.getBalance({ wallet });
+    const wallets = await walletRepo.getWallets();
     
-    // Continue with your handler logic...
+    return res.json({ balance, wallets });
   } catch (error) {
-    console.error('Authentication error:', error);
-    return res.status(500).json({ error: 'Authentication failed' });
+    console.error('Server request error:', error);
+    return res.status(500).json({ error: 'Internal server error' });
   }
 }
 ```
@@ -86,54 +109,235 @@ Repositories provide a consistent interface for data operations across environme
 #### Client-Side Repository Usage
 
 ```typescript
-import { WalletRepo } from "@temboplus/afloat";
+import { WalletRepository } from "@temboplus/afloat";
+
+// Option 1: Let repository use service locator (default behavior)
+const walletRepo = new WalletRepository();
 
-// Create repository - auth is automatically handled
-const walletRepo = new WalletRepo();
+// Option 2: Explicitly pass token from auth manager
+const auth = AfloatAuth.instance;
+const walletRepo = new WalletRepository({ token: auth.getUserToken() });
 
 // Use repository methods
 async function displayBalance() {
   try {
-    const balance = await walletRepo.getBalance();
-    console.log(`Current balance: ${balance}`);
+    const balance = await walletRepo.getBalance({ wallet });
+    console.log(`Current balance: ${balance.value} ${balance.currency}`);
   } catch (error) {
     console.error('Error fetching balance:', error);
   }
 }
+
+// Get all wallets
+const wallets = await walletRepo.getWallets();
+
+// Get wallet statement
+const entries = await walletRepo.getStatement({ 
+  wallet,
+  range: {
+    startDate: new Date('2024-01-01'),
+    endDate: new Date('2024-01-31')
+  }
+});
 ```
 
 #### Server-Side Repository Usage
 
 ```typescript
-import { AfloatAuth, WalletRepo } from "@temboplus/afloat";
+import { WalletRepository } 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 });
+async function processServerRequest(token: string) {
+  // Create repository with explicit token (no auth manager needed)
+  const walletRepo = new WalletRepository({ token });
   
-  // Use repository methods
-  const balance = await walletRepo.getBalance();
+  // Use repository methods directly
+  const balance = await walletRepo.getBalance({ wallet });
   const wallets = await walletRepo.getWallets();
   
   return { balance, wallets };
 }
+
+// In Express.js middleware
+app.use('/api/wallet', async (req, res, next) => {
+  const token = extractTokenFromRequest(req);
+  
+  if (!token) {
+    return res.status(401).json({ error: 'No token provided' });
+  }
+  
+  req.walletRepo = new WalletRepository({ token });
+  next();
+});
 ```
 
+## Architecture Overview
+
+### Client-Side Pattern
+- **Authentication Management**: Use `AfloatAuth.instance` singleton
+- **Repository Creation**: Can use service locator or explicit token passing
+- **State Management**: Reactive updates through React hooks
+- **Permission Checking**: Built into the auth manager
+
+### Server-Side Pattern
+- **No Auth Manager**: Extract tokens directly from requests
+- **Repository Creation**: Always pass token explicitly
+- **Stateless**: Each request creates fresh repository instances
+- **Permission Checking**: Handle at route/middleware level
+
 ## 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
+### Client-Side Applications
+
+1. **Initialize Early**: Set up `AfloatAuth.instance` early in your application lifecycle
+2. **Use React Hooks**: Leverage `auth.useCurrentUser()` for reactive UI updates
+3. **Handle Permissions**: Check permissions before attempting restricted operations
+4. **Error Handling**: Implement proper error handling for authentication failures
+
+```typescript
+// Good: Initialize auth early
+const auth = AfloatAuth.instance;
+
+// Good: Use reactive hooks in components
+function Dashboard() {
+  const user = auth.useCurrentUser();
+  
+  if (!user) return <LoginPrompt />;
+  
+  return <UserDashboard user={user} />;
+}
+
+// Good: Check permissions before operations
+if (auth.checkPermission(Permission.ViewBalance)) {
+  const repo = new WalletRepository();
+  const balance = await repo.getBalance({ wallet });
+}
+```
+
+### Server-Side Applications
+
+1. **Token Extraction**: Always extract and validate tokens from requests
+2. **Explicit Dependencies**: Pass tokens explicitly to repositories
+3. **Error Handling**: Implement proper middleware for authentication errors
+4. **Stateless Design**: Create fresh repository instances per request
+
+```typescript
+// Good: Extract token from request
+const token = req.headers.authorization?.replace('Bearer ', '');
+
+// Good: Explicit token passing
+const repo = new WalletRepository({ token });
+
+// Good: Middleware pattern
+const authMiddleware = (req, res, next) => {
+  const token = extractToken(req);
+  
+  if (!token) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+  
+  req.authToken = token;
+  next();
+};
+
+// Good: Use in route handlers
+app.get('/api/balance', authMiddleware, async (req, res) => {
+  const repo = new WalletRepository({ token: req.authToken });
+  const balance = await repo.getBalance({ wallet });
+  res.json({ balance });
+});
+```
+
+### Testing
+
+1. **Client-Side**: Mock the `AfloatAuth` singleton or use dependency injection
+2. **Server-Side**: Mock repositories with test tokens
+3. **Integration**: Test both authentication flows and repository operations
+
+```typescript
+// Client-side testing
+const mockAuth = {
+  currentUser: testUser,
+  getUserToken: () => 'test-token',
+  checkPermission: () => true
+};
+
+// Server-side testing  
+const testRepo = new WalletRepository({ token: 'test-token' });
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### `"Cannot find package 'react'" in Node.js`
+
+This error occurs when using Zustand v5. Ensure you're using Zustand v4:
+```bash
+npm install zustand@^4.5.7
+```
+
+Remove any existing v5 installation:
+```bash
+npm uninstall zustand@5.x.x
+```
+
+#### Authentication Errors in Server Environment
+
+**Problem**: Trying to use `AfloatAuth.instance` in server-side code
+**Solution**: Extract tokens from requests and pass directly to repositories
+
+```typescript
+// ❌ Don't do this in server code
+const auth = AfloatAuth.instance; // This is client-side only!
+
+// ✅ Do this instead
+const token = req.headers.authorization?.replace('Bearer ', '');
+const repo = new WalletRepository({ token });
+```
+
+#### Repository Token Issues
+
+**Problem**: Repository calls failing with authentication errors
+**Solution**: Ensure tokens are properly extracted and passed
+
+```typescript
+// ❌ Missing token
+const repo = new WalletRepository(); // May fail in server context
+
+// ✅ Explicit token
+const repo = new WalletRepository({ token: extractedToken });
+```
+
+### Debug Information
+
+Use the auth manager's debug utilities for troubleshooting:
+
+```typescript
+// Client-side debugging
+const debugInfo = AfloatAuth.instance.getDebugInfo();
+console.log('Auth Debug Info:', debugInfo);
+```
+
+## API Reference
+
+### AfloatAuth (Client-Side Only)
+
+- `AfloatAuth.instance` - Singleton instance for client-side usage
+- `currentUser` - Get current authenticated user
+- `isAuthenticated` - Check authentication status  
+- `getUserToken()` - Get current auth token
+- `useCurrentUser()` - React hook for reactive user state
+- `checkPermission(perm)` - Check user permissions
+- `logIn(email, password)` - Authenticate user
+- `logOut()` - Clear authentication state
+- `resetPassword(current, new)` - Update user password
+
+### Repository Pattern
 
-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
+All repositories accept optional configuration:
+- `token` - Authentication token for API calls
+- `root` - Custom API root URL
 
-3. **Testing**
-   - Use the `AuthContext` to inject mock auth instances during testing
-   - Reset `AuthContext.current` after each test to prevent test pollution
+Example repositories:
+- `WalletRepository` - Wallet operations and balance management
+- `AuthRepository` - Authentication operations