@temboplus/afloat 0.1.77-beta.9 → 0.1.78

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2025 TemboPlus Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,6 +1,8 @@
 # @temboplus/afloat
 
-A foundational JavaScript/TypeScript library for TemboPlus-Afloat projects, providing abstracted server communication, shared utilities, and standardized data models for consistent development.
+**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. 
 
 ## Key Features
 
@@ -20,7 +22,7 @@ A foundational JavaScript/TypeScript library for TemboPlus-Afloat projects, prov
 
 * **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
+    * Supports both synchronous and asynchronous initialization patterns
 
 ## Usage
 
@@ -28,7 +30,7 @@ A foundational JavaScript/TypeScript library for TemboPlus-Afloat projects, prov
 
 #### Client-Side Usage
 
-In client-side applications, use the `AfloatAuth` singleton for authentication management:
+In client-side applications, authentication is initialized synchronously:
 
 ```typescript
 import { AfloatAuth } from "@temboplus/afloat";
@@ -37,67 +39,42 @@ import { AfloatAuth } from "@temboplus/afloat";
 const auth = AfloatAuth.instance;
 
 // Check if user is authenticated
-console.log("User authenticated:", auth.isAuthenticated);
+console.log("User authenticated:", !!auth.currentUser);
 
 // 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, **do not use `AfloatAuth`**. Instead, extract the authentication token from requests and pass it directly to repositories:
+In server-side environments, authentication requires asynchronous initialization:
 
 ```typescript
-import { WalletRepository } from "@temboplus/afloat";
+import { AfloatAuth } from "@temboplus/afloat";
 
-// In a server route handler or API endpoint
+// In a server route handler or similar context
 async function handleRequest(req, res) {
   try {
-    // Extract token from request headers
+    // Extract token from request
     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 });
+    // Initialize server-side auth
+    const auth = await AfloatAuth.initializeServer(token);
     
-    // Use repository methods directly
-    const balance = await walletRepo.getBalance({ wallet });
-    const wallets = await walletRepo.getWallets();
+    // Now you can use auth for permission checks
+    const isAdmin = auth.checkPermission(Permissions.Payout.View);
     
-    return res.json({ balance, wallets });
+    // Continue with your handler logic...
   } catch (error) {
-    console.error('Server request error:', error);
-    return res.status(500).json({ error: 'Internal server error' });
+    console.error('Authentication error:', error);
+    return res.status(500).json({ error: 'Authentication failed' });
   }
 }
 ```
@@ -109,235 +86,54 @@ Repositories provide a consistent interface for data operations across environme
 #### Client-Side Repository Usage
 
 ```typescript
-import { WalletRepository } from "@temboplus/afloat";
-
-// Option 1: Let repository use service locator (default behavior)
-const walletRepo = new WalletRepository();
+import { WalletRepo } from "@temboplus/afloat";
 
-// Option 2: Explicitly pass token from auth manager
-const auth = AfloatAuth.instance;
-const walletRepo = new WalletRepository({ token: auth.getUserToken() });
+// Create repository - auth is automatically handled
+const walletRepo = new WalletRepo();
 
 // Use repository methods
 async function displayBalance() {
   try {
-    const balance = await walletRepo.getBalance({ wallet });
-    console.log(`Current balance: ${balance.value} ${balance.currency}`);
+    const balance = await walletRepo.getBalance();
+    console.log(`Current balance: ${balance}`);
   } 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 { WalletRepository } from "@temboplus/afloat";
+import { AfloatAuth, WalletRepo } from "@temboplus/afloat";
 
-async function processServerRequest(token: string) {
-  // Create repository with explicit token (no auth manager needed)
-  const walletRepo = new WalletRepository({ token });
+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 directly
-  const balance = await walletRepo.getBalance({ wallet });
+  // Use repository methods
+  const balance = await walletRepo.getBalance();
   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
 
-### 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
+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
 
-All repositories accept optional configuration:
-- `token` - Authentication token for API calls
-- `root` - Custom API root URL
+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
 
-Example repositories:
-- `WalletRepository` - Wallet operations and balance management
-- `AuthRepository` - Authentication operations
+3. **Testing**
+   - Use the `AuthContext` to inject mock auth instances during testing
+   - Reset `AuthContext.current` after each test to prevent test pollution

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/mod.d.ts

@@ -0,0 +1,5 @@
+export * from "./src/models/index.js";
+export * from "./src/utils/index.js";
+export * from "./src/reports/index.js";
+export * from "./src/config/index.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../../../src/deps/jsr.io/@temboplus/frontend-core/0.2.21/mod.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC"}

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/mod.js

@@ -0,0 +1,4 @@
+export * from "./src/models/index.js";
+export * from "./src/utils/index.js";
+export * from "./src/reports/index.js";
+export * from "./src/config/index.js";

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/config/config_service.d.ts

@@ -0,0 +1,11 @@
+export declare class ConfigService {
+    private static _instance;
+    private _pdfMakerBaseUrl;
+    private constructor();
+    static get instance(): ConfigService;
+    initialize(config: {
+        pdfMakerBaseUrl: string;
+    }): void;
+    get pdfMakerBaseUrl(): string;
+}
+//# sourceMappingURL=config_service.d.ts.map

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/config/config_service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config_service.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/config/config_service.ts"],"names":[],"mappings":"AAAA,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,SAAS,CAAgB;IACxC,OAAO,CAAC,gBAAgB,CAAc;IAEtC,OAAO;IAEP,WAAkB,QAAQ,kBAEzB;IAEM,UAAU,CAAC,MAAM,EAAE;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE;IAIrD,IAAW,eAAe,IAAI,MAAM,CAEnC;CACF"}

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/config/config_service.js

@@ -0,0 +1,19 @@
+export class ConfigService {
+    constructor() {
+        Object.defineProperty(this, "_pdfMakerBaseUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ""
+        });
+    }
+    static get instance() {
+        return this._instance || (this._instance = new this());
+    }
+    initialize(config) {
+        this._pdfMakerBaseUrl = config.pdfMakerBaseUrl;
+    }
+    get pdfMakerBaseUrl() {
+        return this._pdfMakerBaseUrl;
+    }
+}

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/config/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./config_service.js";
+//# sourceMappingURL=index.d.ts.map

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/config/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA"}

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/config/index.js

@@ -0,0 +1 @@
+export * from "./config_service.js";

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/data/banks_tz.d.ts

@@ -0,0 +1,7 @@
+declare const _default: {
+    fullName: string;
+    shortName: string;
+    swiftCode: string;
+}[];
+export default _default;
+//# sourceMappingURL=banks_tz.d.ts.map

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/data/banks_tz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"banks_tz.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/data/banks_tz.js"],"names":[],"mappings":""}

package/esm/deps/jsr.io/@temboplus/frontend-core/0.2.21/src/data/banks_tz.js

@@ -0,0 +1,197 @@
+export default [
+    {
+        "fullName": "CRDB BANK PLC",
+        "shortName": "CRDB",
+        "swiftCode": "CORUTZTZ"
+    },
+    {
+        "fullName": "PEOPLE'S BANK OF ZANZIBAR LTD",
+        "shortName": "PBZ",
+        "swiftCode": "PBZATZTZ"
+    },
+    {
+        "fullName": "STANDARD CHARTERED BANK (T) LIMITED",
+        "shortName": "SCB",
+        "swiftCode": "SCBLTZTX"
+    },
+    {
+        "fullName": "STANBIC BANK TANZANIA LTD.",
+        "shortName": "STANBIC",
+        "swiftCode": "SBICTZTX"
+    },
+    {
+        "fullName": "CITIBANK TANZANIA LTD",
+        "shortName": "CITI",
+        "swiftCode": "CITITZTZ"
+    },
+    {
+        "fullName": "BANK OF AFRICA TANZANIA LIMITED",
+        "shortName": "BOA",
+        "swiftCode": "EUAFTZTZ"
+    },
+    {
+        "fullName": "DIAMOND TRUST BANK TANZANIA LTD",
+        "shortName": "DTB",
+        "swiftCode": "DTKETZTZ"
+    },
+    {
+        "fullName": "AKIBA COMMERCIAL BANK LTD",
+        "shortName": "AKIBA",
+        "swiftCode": "AKCOTZTZ"
+    },
+    {
+        "fullName": "EXIM BANK (TANZANIA) LTD",
+        "shortName": "EXIM",
+        "swiftCode": "EXTNTZTZ"
+    },
+    {
+        "fullName": "KILIMANJARO CO-OPERATIVE BANK LTD",
+        "shortName": "KILIMANJARO",
+        "swiftCode": "KLMJTZTZ"
+    },
+    {
+        "fullName": "NATIONAL BANK OF COMMERCE LTD",
+        "shortName": "NBC",
+        "swiftCode": "NLCBTZTX"
+    },
+    {
+        "fullName": "NATIONAL MICROFINANCE BANK LIMITED",
+        "shortName": "NMB",
+        "swiftCode": "NMIBTZTZ"
+    },
+    {
+        "fullName": "KCB BANK TANZANIA LIMITED",
+        "shortName": "KCB",
+        "swiftCode": "KCBLTZTZ"
+    },
+    {
+        "fullName": "HABIB AFRICAN BANK LIMITED",
+        "shortName": "HABIB",
+        "swiftCode": "HABLTZTZ"
+    },
+    {
+        "fullName": "INTERNATIONAL COMMERCIAL BANK (TANZANIA) LIMITED",
+        "shortName": "ICB",
+        "swiftCode": "BKMYTZTZ"
+    },
+    {
+        "fullName": "ABSA BANK TANZANIA LTD",
+        "shortName": "ABSA",
+        "swiftCode": "BARCTZTZ"
+    },
+    {
+        "fullName": "I&M BANK LIMITED",
+        "shortName": "IMBANK",
+        "swiftCode": "IMBLTZTZ"
+    },
+    {
+        "fullName": "NCBA BANK LIMITED",
+        "shortName": "NCBA",
+        "swiftCode": "CBAFTZTZ"
+    },
+    {
+        "fullName": "DAR ES SALAAM COMMUNITY BANK LTD",
+        "shortName": "DCB",
+        "swiftCode": "DASUTZTZ"
+    },
+    {
+        "fullName": "BANK OF BARODA (TANZANIA) LTD",
+        "shortName": "BARODA",
+        "swiftCode": "BARBTZTZ"
+    },
+    {
+        "fullName": "AZANIA BANK LIMITED",
+        "shortName": "AZANIA",
+        "swiftCode": "AZANTZTZ"
+    },
+    {
+        "fullName": "UCHUMI COMMERCIAL BANK (T) LTD",
+        "shortName": "UCHUMI",
+        "swiftCode": "UCCTTZTZ"
+    },
+    {
+        "fullName": "ACCESS BANK TANZANIA LIMITED (Formerly BancABC)",
+        "shortName": "ABT",
+        "swiftCode": "FMBZTZTX"
+    },
+    {
+        "fullName": "SELCOM MICROFINANCE BANK (Formerly Access Microfinance Bank Tanzania)",
+        "shortName": "SMFB",
+        "swiftCode": "ACTZTZTZ"
+    },
+    {
+        "fullName": "BANK OF INDIA (TANZANIA) LIMITED",
+        "shortName": "BOI",
+        "swiftCode": "BKIDTZTZ"
+    },
+    {
+        "fullName": "UNITED BANK FOR AFRICA (T) LTD",
+        "shortName": "UBA",
+        "swiftCode": "UNAFTZTZ"
+    },
+    {
+        "fullName": "MKOMBOZI COMMERCIAL BANK",
+        "shortName": "MKOMBOZI",
+        "swiftCode": "MKCBTZTZ"
+    },
+    {
+        "fullName": "ECOBANK TANZANIA LIMITED",
+        "shortName": "ECOBANK",
+        "swiftCode": "ECOCTZTZ"
+    },
+    {
+        "fullName": "MWANGA HAKIKA MICROFINANCE BANK LIMITED",
+        "shortName": "MWANGA",
+        "swiftCode": "MWCBTZTZ"
+    },
+    {
+        "fullName": "FIRST NATIONAL BANK LIMITED",
+        "shortName": "FNB",
+        "swiftCode": "FIRNTZTX"
+    },
+    {
+        "fullName": "AMANA BANK LIMITED",
+        "shortName": "AMANA",
+        "swiftCode": "AMNNTZTZ"
+    },
+    {
+        "fullName": "EQUITY BANK TANZANIA LIMITED",
+        "shortName": "EQUITY",
+        "swiftCode": "EQBLTZTZ"
+    },
+    {
+        "fullName": "TANZANIA COMMERCIAL BANK PLC",
+        "shortName": "TCB",
+        "swiftCode": "TAPBTZTZ"
+    },
+    {
+        "fullName": "MAENDELEO BANK LTD",
+        "shortName": "MAENDELEO",
+        "swiftCode": "MBTLTZTZ"
+    },
+    {
+        "fullName": "CANARA BANK TANZANIA LTD",
+        "shortName": "CANARA",
+        "swiftCode": "CNRBTZTZ"
+    },
+    {
+        "fullName": "MWALIMU COMMERCIAL BANK PLC",
+        "shortName": "MWALIMU",
+        "swiftCode": "MWCOTZTZ"
+    },
+    {
+        "fullName": "GUARANTY TRUST BANK (T) LTD",
+        "shortName": "GT BANK",
+        "swiftCode": "GTBITZTZ"
+    },
+    {
+        "fullName": "YETU MICROFINANCE BANK PLC",
+        "shortName": "YETU",
+        "swiftCode": "YETMTZTZ"
+    },
+    {
+        "fullName": "CHINA DASHENG BANK LIMITED",
+        "shortName": "DASHENG",
+        "swiftCode": "CDSHTZTZ"
+    }
+];