@temboplus/afloat 0.2.0-beta.1 → 0.2.0-beta.10

package/README.md

@@ -8,336 +8,248 @@ A foundational JavaScript/TypeScript library for TemboPlus-Afloat projects, prov
     * Simplifies front-end development by abstracting all interactions with the server behind model-specific repositories
     * 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
+* **Authentication-Agnostic Repositories**
+    * The library does not own session state or export an auth singleton
+    * Consuming applications log in, store the returned token, and pass that token to repositories
 
 * **Data Models**
     * Defines standardized data structures and interfaces for consistent data representation throughout the Afloat ecosystem
 
-* **Enhanced Maintainability**
-    * Centralizes common logic, making it easier to maintain and update across all consuming projects
-    * Reduces code duplication and improves consistency
-
 * **Cross-Environment Compatibility**
     * Works seamlessly in both client-side and server-side environments
-    * Different patterns for client-side authentication management vs server-side token handling
 
 ## Usage
 
-### Authentication Setup
-
-#### Client-Side Usage
+### Login
 
-In client-side applications, use the `AfloatAuth` singleton for authentication management:
+Use `AuthRepository.logIn(...)` for the unauthenticated login request. The returned `User` contains the token that should be stored by your app and passed to other repositories.
 
 ```typescript
-import { AfloatAuth } from "@temboplus/afloat";
-
-// Initialize client auth (typically in your app entry point)
-const auth = AfloatAuth.instance;
+import { AuthRepository } from "@temboplus/afloat";
 
-// Check if user is authenticated
-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!");
+  const authRepo = new AuthRepository();
+  const user = await authRepo.logIn("user@example.com", "password123");
+
+  storeSession({
+    token: user.token,
+    user: user.toJSON(),
+  });
 } catch (error) {
-  console.error("Login failed:", error.message);
+  const message = error instanceof Error ? error.message : "Unknown error";
+  console.error("Login failed:", message);
 }
+```
 
-// Check permissions
-if (auth.checkPermission(Permission.ViewBalance)) {
-  console.log("User can view balance");
-}
+`AuthRepository` also has authenticated methods. Construct it with a token before calling those:
 
-// React hook for reactive user state
-function UserProfile() {
-  const user = auth.useCurrentUser();
-  
-  if (!user) {
-    return <LoginForm />;
-  }
-  
-  return <div>Hello, {user.name}!</div>;
-}
+```typescript
+import { AuthRepository } from "@temboplus/afloat";
+
+const authRepo = new AuthRepository({ token });
+
+await authRepo.updatePassword("currentPassword", "newPassword");
+const accessList = await authRepo.getAccessList();
 ```
 
-#### Server-Side Usage
+### Repository Usage
 
-In server-side environments, **do not use `AfloatAuth`**. Instead, extract the authentication token from requests and pass it directly to repositories:
+Authenticated repositories share the same construction shape:
 
 ```typescript
-import { WalletRepository } from "@temboplus/afloat";
-
-// In a server route handler or API endpoint
-async function handleRequest(req, res) {
-  try {
-    // Extract token from request headers
-    const token = req.headers.authorization?.replace('Bearer ', '');
-    
-    if (!token) {
-      return res.status(401).json({ error: 'Unauthorized' });
-    }
-    
-    // Create repository with explicit token
-    const walletRepo = new WalletRepository({ token });
-    
-    // Use repository methods directly
-    const balance = await walletRepo.getBalance({ wallet });
-    const wallets = await walletRepo.getWallets();
-    
-    return res.json({ balance, wallets });
-  } catch (error) {
-    console.error('Server request error:', error);
-    return res.status(500).json({ error: 'Internal server error' });
-  }
-}
+const repo = new SomeRepository({
+  token: "user-auth-token",
+  root: "https://api.afloat.money/v1", // optional
+});
 ```
 
-### Using Repositories
+Use this shape for:
 
-Repositories provide a consistent interface for data operations across environments.
+* `WalletRepository`
+* `PayoutRepository`
+* `BeneficiaryRepository`
+* `ProfileRepository`
+* `TeamMemberRepository`
+* `IdentityRepository`
+* `AuthRepository` when calling authenticated methods like `updatePassword` or `getAccessList`
 
-#### Client-Side Repository Usage
+The TypeScript constructors accept optional fields because the base repository supports a global token getter, but authenticated Afloat API calls still require a token. Passing `{ token }` explicitly is the recommended and documented integration path.
 
-```typescript
-import { WalletRepository } from "@temboplus/afloat";
+#### Wallet Example
 
-// Option 1: Let repository use service locator (default behavior)
-const walletRepo = new WalletRepository();
+```typescript
+import { Permissions, WalletRepository } from "@temboplus/afloat";
 
-// Option 2: Explicitly pass token from auth manager
-const auth = AfloatAuth.instance;
-const walletRepo = new WalletRepository({ token: auth.getUserToken() });
+const walletRepo = new WalletRepository({ token });
+const [wallet] = await walletRepo.getWallets();
 
-// Use repository methods
-async function displayBalance() {
-  try {
-    const balance = await walletRepo.getBalance({ wallet });
-    console.log(`Current balance: ${balance.value} ${balance.currency}`);
-  } catch (error) {
-    console.error('Error fetching balance:', error);
-  }
+if (!wallet) {
+  throw new Error("No wallet available");
 }
 
-// Get all wallets
-const wallets = await walletRepo.getWallets();
+if (user.can(Permissions.Wallet.ViewBalance)) {
+  const balance = await walletRepo.getBalance({ wallet });
+  console.log(balance.label);
+}
 
-// Get wallet statement
-const entries = await walletRepo.getStatement({ 
+const entries = await walletRepo.getStatement({
   wallet,
   range: {
-    startDate: new Date('2024-01-01'),
-    endDate: new Date('2024-01-31')
-  }
+    startDate: new Date("2024-01-01"),
+    endDate: new Date("2024-01-31"),
+  },
 });
 ```
 
-#### Server-Side Repository Usage
+#### Identity Example
+
+`IdentityRepository` reads the authenticated `/login/me` data. It is not the login request itself, so it requires a token.
+
+```typescript
+import { IdentityRepository } from "@temboplus/afloat";
+
+const identityRepo = new IdentityRepository({ token });
+const identity = await identityRepo.getIdentity();
+```
+
+#### Server Route Example
 
 ```typescript
 import { WalletRepository } from "@temboplus/afloat";
 
-async function processServerRequest(token: string) {
-  // Create repository with explicit token (no auth manager needed)
-  const walletRepo = new WalletRepository({ token });
-  
-  // Use repository methods directly
-  const balance = await walletRepo.getBalance({ wallet });
-  const wallets = await walletRepo.getWallets();
-  
-  return { balance, wallets };
+function extractBearerToken(req): string | undefined {
+  return req.headers.authorization?.replace(/^Bearer\s+/i, "");
 }
 
-// In Express.js middleware
-app.use('/api/wallet', async (req, res, next) => {
-  const token = extractTokenFromRequest(req);
-  
+app.get("/api/wallets", async (req, res) => {
+  const token = extractBearerToken(req);
+
   if (!token) {
-    return res.status(401).json({ error: 'No token provided' });
+    return res.status(401).json({ error: "Unauthorized" });
   }
-  
-  req.walletRepo = new WalletRepository({ token });
-  next();
+
+  const walletRepo = new WalletRepository({ token });
+  const wallets = await walletRepo.getWallets();
+
+  return res.json({ wallets });
 });
 ```
 
 ## 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
+### Host Application Responsibilities
 
-### 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
+* Call `AuthRepository.logIn(...)` to create a session
+* Store the returned token in your own state, cookie, storage, or server session
+* Rehydrate `User` with `User.fromJSON(...)` when needed
+* Pass `{ token }` to repositories before calling authenticated endpoints
+* Check permissions with the returned `User` instance, for example `user.can(Permissions.Wallet.ViewBalance)`
 
-## Best Practices
-
-### Client-Side Applications
+### Library Responsibilities
 
-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
+* Provide typed repositories for Afloat API resources
+* Attach the token and request ID headers to repository calls
+* Convert API responses into domain models where repositories support it
+* Surface API errors through `APIError` or repository-specific errors
 
-```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
+## Best Practices
 
-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
+### Token Handling
 
 ```typescript
-// Good: Extract token from request
-const token = req.headers.authorization?.replace('Bearer ', '');
+import {
+  AuthRepository,
+  ProfileRepository,
+  WalletRepository,
+} from "@temboplus/afloat";
 
-// Good: Explicit token passing
-const repo = new WalletRepository({ token });
+const authRepo = new AuthRepository();
+const user = await authRepo.logIn(email, password);
 
-// 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 });
-});
-```
+saveToken(user.token);
 
-### Testing
+const walletRepo = new WalletRepository({ token: user.token });
+const profileRepo = new ProfileRepository({ token: user.token });
+```
 
-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
+### Permission Checks
 
 ```typescript
-// Client-side testing
-const mockAuth = {
-  currentUser: testUser,
-  getUserToken: () => 'test-token',
-  checkPermission: () => true
-};
-
-// Server-side testing  
-const testRepo = new WalletRepository({ token: 'test-token' });
+import { Permissions, PayoutRepository } from "@temboplus/afloat";
+
+if (user.can(Permissions.Payout.Create)) {
+  const payoutRepo = new PayoutRepository({ token: user.token });
+  await payoutRepo.pay(input);
+}
 ```
 
 ## Troubleshooting
 
 ### Common Issues
 
-#### `"Cannot find package 'react'" in Node.js`
+#### `AfloatAuth` Import Errors
 
-This error occurs when using Zustand v5. Ensure you're using Zustand v4:
-```bash
-npm install zustand@^4.5.7
-```
+**Problem**: `AfloatAuth` is undefined or cannot be imported.
 
-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
+**Solution**: Replace `AfloatAuth` usage with `AuthRepository.logIn(...)` plus application-owned session state.
 
 ```typescript
-// ❌ Don't do this in server code
-const auth = AfloatAuth.instance; // This is client-side only!
+import { AuthRepository } from "@temboplus/afloat";
 
-// ✅ Do this instead
-const token = req.headers.authorization?.replace('Bearer ', '');
-const repo = new WalletRepository({ token });
+const authRepo = new AuthRepository();
+const user = await authRepo.logIn(email, password);
+const token = user.token;
 ```
 
 #### Repository Token Issues
 
-**Problem**: Repository calls failing with authentication errors
-**Solution**: Ensure tokens are properly extracted and passed
+**Problem**: Repository calls fail with authentication errors.
+
+**Solution**: Ensure the token from login or the incoming request is passed into the repository.
 
 ```typescript
-// ❌ Missing token
-const repo = new WalletRepository(); // May fail in server context
+if (!extractedToken) {
+  throw new Error("Missing authentication token");
+}
 
-// ✅ Explicit token
 const repo = new WalletRepository({ token: extractedToken });
 ```
 
-### Debug Information
+#### Identity Repository Confusion
 
-Use the auth manager's debug utilities for troubleshooting:
+**Problem**: `IdentityRepository` is used for login.
 
-```typescript
-// Client-side debugging
-const debugInfo = AfloatAuth.instance.getDebugInfo();
-console.log('Auth Debug Info:', debugInfo);
-```
+**Solution**: Use `AuthRepository.logIn(...)` for login. Use `IdentityRepository({ token }).getIdentity()` only after you have a token.
 
 ## API Reference
 
-### AfloatAuth (Client-Side Only)
+### Login and Auth
+
+* `AuthRepository.logIn(email, password)` - Authenticate without an existing token and return a `User`
+* `AuthRepository({ token }).updatePassword(current, next)` - Update the current user's password
+* `AuthRepository({ token }).getAccessList()` - Fetch the current user's access list
+* `User.token` - Token to pass into repositories
+* `User.can(permission)` - Check a single permission
+* `User.canAny(permissions)` - Check if the user has at least one permission
+* `User.canAll(permissions)` - Check if the user has all permissions
 
-- `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
+### Authenticated Repositories
 
-### Repository Pattern
+All authenticated repositories use:
+
+```typescript
+new RepositoryName({
+  token: "user-auth-token",
+  root: "custom-api-root", // optional
+});
+```
 
-All repositories accept optional configuration:
-- `token` - Authentication token for API calls
-- `root` - Custom API root URL
+Available repositories:
 
-Example repositories:
-- `WalletRepository` - Wallet operations and balance management
-- `AuthRepository` - Authentication operations
+* `WalletRepository` - Wallet operations, balances, and statements
+* `PayoutRepository` - Payout creation, approval, rejection, lookup, and counting
+* `BeneficiaryRepository` - Beneficiary create, edit, remove, and lookup
+* `ProfileRepository` - Current profile lookup
+* `TeamMemberRepository` - Team member and role management
+* `IdentityRepository` - Current `/login/me` identity data
+* `AuthRepository` - Login without token; password and access-list operations with token