@temboplus/afloat-legacy

⚠️ Legacy package

This package contains the previous implementation of the Afloat foundational library. It is maintained for existing products that rely on the legacy architecture.

Status: Maintenance mode

• Bug fixes only
• Security fixes only
• No new features

For new development, use:

@temboplus/afloat

Overview

A foundational library for Temboplus-Afloat projects (Legacy Implementation).

This JavaScript/TypeScript package provides a central hub for shared utilities, logic, and data access mechanisms within the legacy Temboplus-Afloat ecosystem.

Key Features

• Abstracted Server Communication

  • 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 reusable helper functions for common tasks such as error handling

• Data Models

  • Defines standardized data structures and interfaces for consistent data representation

• Enhanced Maintainability

  • Centralizes common logic across legacy Afloat projects
  • Reduces code duplication and improves consistency

• Cross-Environment Compatibility

  • Works in both client-side and server-side environments
  • Supports synchronous and asynchronous initialization patterns

Migration Note

Existing projects may continue using:

@temboplus/afloat-legacy

New projects should use:

@temboplus/afloat

Migration timelines depend on product requirements and will be handled incrementally.

Usage

Authentication Setup

Client-Side Usage

In client-side applications, authentication is initialized synchronously:

import { AfloatAuth } from "@temboplus/afloat-legacy";

// 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:

import { AfloatAuth } from "@temboplus/afloat-legacy";

// 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

import { WalletRepo } from "@temboplus/afloat-legacy";

// 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

import { AfloatAuth, WalletRepo } from "@temboplus/afloat-legacy";

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