@temboplus/afloat 0.1.77-beta.9 → 0.1.79

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/mod.d.ts

@@ -0,0 +1,8 @@
+export * from "./src/features/auth/index.js";
+export * from "./src/features/contact/index.js";
+export * from "./src/features/wallet/index.js";
+export * from "./src/features/payout/index.js";
+export * from "./src/features/admin/index.js";
+export * from "./src/errors/index.js";
+export * from "./src/models/index.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAE9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC"}

package/esm/mod.js

@@ -0,0 +1,7 @@
+export * from "./src/features/auth/index.js";
+export * from "./src/features/contact/index.js";
+export * from "./src/features/wallet/index.js";
+export * from "./src/features/payout/index.js";
+export * from "./src/features/admin/index.js";
+export * from "./src/errors/index.js";
+export * from "./src/models/index.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/{dist/lib/error/error.api.d.ts → esm/src/errors/api_error.d.ts}

@@ -60,3 +60,4 @@ export declare class APIError extends Error {
         details: z.ZodOptional<z.AnyZodObject>;
     }>;
 }
+//# sourceMappingURL=api_error.d.ts.map

package/esm/src/errors/api_error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api_error.d.ts","sourceRoot":"","sources":["../../../src/src/errors/api_error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC;;;OAGG;IACH,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC;;;OAGG;IACH,SAAgB,KAAK,CAAC,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElD;;;;;;;OAOG;gBACS,IAAI,EAAE;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;IASD;;;;;;;;;;;;;;;;;OAiBG;WACW,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ;WAKrC,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ;IAOjD,WAAkB,MAAM,IAAI,CAAC,CAAC,SAAS,CAAC;QACtC,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC;QACrB,UAAU,EAAE,CAAC,CAAC,SAAS,CAAC;QACxB,KAAK,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAClC,OAAO,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;KACxC,CAAC,CAOD;CACF"}

package/esm/src/errors/api_error.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+/**
+ * Custom error class representing API-related errors.
+ * Extends the built-in `Error` class to include additional properties such as `statusCode`, `error`, and `details`.
+ */
+export class APIError extends Error {
+    /**
+     * Creates a new `APIError` instance.
+     * @param {Object} args - The arguments to initialize the error.
+     * @param {string} args.message - The error message.
+     * @param {number} args.statusCode - The HTTP status code associated with the error.
+     * @param {string} [args.error] - An optional error identifier or code.
+     * @param {Record<string, unknown>} [args.details] - Additional details about the error.
+     */
+    constructor(args) {
+        super(args.message);
+        /**
+         * The HTTP status code associated with the error.
+         * @type {number}
+         */
+        Object.defineProperty(this, "statusCode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * An optional error identifier or code.
+         * @type {string | undefined}
+         */
+        Object.defineProperty(this, "error", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Additional details about the error, often used for debugging purposes.
+         * @type {Record<string, unknown> | undefined}
+         */
+        Object.defineProperty(this, "details", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "ApiError";
+        this.statusCode = args.statusCode;
+        if (this.error)
+            this.error = args.error;
+        if (args.details)
+            this.details = args.details;
+    }
+    /**
+     * Validates whether an unknown value conforms to the APIError schema.
+     * This is more thorough than an instanceof check as it verifies all required properties
+     * and their types using the defined schema.
+     *
+     * @param {unknown} error - Any value to be validated
+     * @returns {error is APIError} Type predicate indicating if the value is a valid APIError
+     *
+     * @example
+     * try {
+     *   throw new Error('Network failed');
+     * } catch (err) {
+     *   if (APIError.is(err)) {
+     *     // err is typed as APIError here
+     *     console.log(err.statusCode);
+     *   }
+     * }
+     */
+    static is(error) {
+        const result = APIError.schema.safeParse(error);
+        return result.success;
+    }
+    static unknown(message) {
+        return new APIError({
+            message: message ?? "An unknown error occurred",
+            statusCode: 502,
+        });
+    }
+    static get schema() {
+        return z.object({
+            message: z.string(),
+            statusCode: z.number().int(),
+            error: z.string().optional(),
+            details: z.object({}).optional(),
+        });
+    }
+}

package/esm/src/errors/index.d.ts

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

package/esm/src/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC"}

package/esm/src/errors/index.js

@@ -0,0 +1,2 @@
+export * from "./api_error.js";
+export * from "./permission_error.js";

package/{dist/lib/error/error.permission.d.ts → esm/src/errors/permission_error.d.ts}

@@ -1,4 +1,4 @@
-import { Permission } from "@/modules/login/permission.type.js";
+import { type Permission } from "../models/permission.js";
 /**
  * Custom error class representing an error caused by missing required permissions.
  * Extends the built-in {@link Error} class to include the `requiredPermissions` property.
@@ -45,3 +45,4 @@ export declare class PermissionError extends Error {
      */
     static is(error: unknown): error is PermissionError;
 }
+//# sourceMappingURL=permission_error.d.ts.map

package/esm/src/errors/permission_error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission_error.d.ts","sourceRoot":"","sources":["../../../src/src/errors/permission_error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAe,MAAM,yBAAyB,CAAC;AAGvE;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC;;;OAGG;IACH,SAAgB,mBAAmB,EAAE,UAAU,EAAE,CAAC;IAElD;;;;;OAKG;gBACS,IAAI,EAAE;QAChB,mBAAmB,EAAE,UAAU,EAAE,CAAC;QAClC,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB;IASD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;WACW,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe;CAkB3D"}

package/esm/src/errors/permission_error.js

@@ -0,0 +1,70 @@
+import { Permissions } from "../models/permission.js";
+import { z } from "zod";
+/**
+ * Custom error class representing an error caused by missing required permissions.
+ * Extends the built-in {@link Error} class to include the `requiredPermissions` property.
+ */
+export class PermissionError extends Error {
+    /**
+     * Creates a new `PermissionError` instance.
+     * @param {Object} args - The constructor arguments.
+     * @param {Permission[]} args.requiredPermissions - An array of permissions required for the operation.
+     * @param {string} [args.message] - An optional custom error message. Defaults to listing the missing permissions.
+     */
+    constructor(args) {
+        super(args.message ??
+            `Missing required permissions: ${args.requiredPermissions.join(", ")}`);
+        /**
+         * The permissions that are required but were not present, causing the error.
+         * @type {Permission[]}
+         */
+        Object.defineProperty(this, "requiredPermissions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "PermissionError";
+        this.requiredPermissions = args.requiredPermissions;
+    }
+    /**
+     * Validates if an unknown value is a valid PermissionError instance.
+     * Performs structural validation of the error object and its properties.
+     *
+     * @param {unknown} error - The value to validate.
+     * @returns {error is PermissionError} Type predicate indicating if the value is a valid PermissionError.
+     *
+     * @example
+     * try {
+     *   throw new Error('Access denied');
+     * } catch (error) {
+     *   if (PermissionError.is(error)) {
+     *     // error is typed as PermissionError with properly typed requiredPermissions
+     *     console.log(error.requiredPermissions);
+     *   }
+     * }
+     *
+     * @remarks
+     * Validates the following:
+     * - Has all required Error properties
+     * - Has correct error name
+     * - Contains properly structured requiredPermissions array
+     * - Maintains proper prototype chain
+     */
+    static is(error) {
+        const permissionSchema = z.union([
+            z.enum(Object.values(Permissions.Profile)),
+            z.enum(Object.values(Permissions.Contact)),
+            z.enum(Object.values(Permissions.Payment)),
+            z.enum(Object.values(Permissions.Payout)),
+            z.enum(Object.values(Permissions.Transfer)),
+            z.enum(Object.values(Permissions.Wallet)),
+        ]);
+        const errorSchema = z.object({
+            name: z.literal("PermissionError"),
+            message: z.string(),
+            requiredPermissions: z.array(permissionSchema),
+        });
+        return errorSchema.safeParse(error).success;
+    }
+}