@temboplus/afloat 0.2.1-beta.8 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 TemboPlus
+
+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,255 +1,102 @@
 # @temboplus/afloat
 
-A foundational JavaScript/TypeScript library for TemboPlus-Afloat projects, providing abstracted server communication, shared utilities, and standardized data models for consistent development.
+Type-safe client library for the TemboPlus-Afloat API. Repository classes wrap each resource (wallets, payouts, beneficiaries, profile, team members, identity, auth) so consumers never talk to HTTP directly.
 
-## Key Features
+## Quick Start
 
-* **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
-
-* **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
-
-* **Cross-Environment Compatibility**
-    * Works seamlessly in both client-side and server-side environments
-
-## Usage
-
-### Login
-
-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 { AuthRepository } from "@temboplus/afloat";
-
-try {
-  const authRepo = new AuthRepository();
-  const user = await authRepo.logIn("user@example.com", "password123");
-
-  storeSession({
-    token: user.token,
-    user: user.toJSON(),
-  });
-} catch (error) {
-  const message = error instanceof Error ? error.message : "Unknown error";
-  console.error("Login failed:", message);
-}
+```bash
+bun add @temboplus/afloat
+# or: npm install @temboplus/afloat
 ```
 
-`AuthRepository` also has authenticated methods. Construct it with a token before calling those:
-
 ```typescript
-import { AuthRepository } from "@temboplus/afloat";
+import { AuthRepository, WalletRepository } from "@temboplus/afloat";
 
-const authRepo = new AuthRepository({ token });
+// 1. Log in. The returned User contains the token.
+const authRepo = new AuthRepository();
+const user = await authRepo.logIn("user@example.com", "password123");
 
-await authRepo.updatePassword("currentPassword", "newPassword");
-const accessList = await authRepo.getAccessList();
+// 2. Pass the token to any other repository.
+const walletRepo = new WalletRepository({ token: user.token });
+const [wallet] = await walletRepo.getWallets();
 ```
 
-### Repository Usage
+## Usage
 
-Authenticated repositories share the same construction shape:
+afloat is **session-agnostic** — it does not own login state or export an auth singleton. Your application logs in, stores the token, and passes it into every authenticated repository.
 
 ```typescript
 const repo = new SomeRepository({
   token: "user-auth-token",
-  root: "https://api.afloat.money/v1", // optional
+  root: "https://api.afloat.money/v1", // optional override
 });
 ```
 
-Use this shape for:
+Available repositories:
 
-* `WalletRepository`
-* `PayoutRepository`
-* `BeneficiaryRepository`
-* `ProfileRepository`
-* `TeamMemberRepository`
-* `IdentityRepository`
-* `AuthRepository` when calling authenticated methods like `updatePassword` or `getAccessList`
+- `AuthRepository` — `logIn`, `updatePassword`, `getAccessList`
+- `WalletRepository` — wallets, balances, statements
+- `PayoutRepository` — create, approve, reject, list, count
+- `BeneficiaryRepository` — create, edit, remove, lookup
+- `ProfileRepository` — current profile
+- `TeamMemberRepository` — team members and roles
+- `IdentityRepository` — authenticated `/login/me`
 
-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.
+### Permissions
 
-#### Wallet Example
+The `User` returned by `logIn` carries the permission set:
 
 ```typescript
-import { Permissions, WalletRepository } from "@temboplus/afloat";
-
-const walletRepo = new WalletRepository({ token });
-const [wallet] = await walletRepo.getWallets();
-
-if (!wallet) {
-  throw new Error("No wallet available");
-}
+import { Permissions, PayoutRepository } from "@temboplus/afloat";
 
-if (user.can(Permissions.Wallet.ViewBalance)) {
-  const balance = await walletRepo.getBalance({ wallet });
-  console.log(balance.label);
+if (user.can(Permissions.Payout.Create)) {
+  const payoutRepo = new PayoutRepository({ token: user.token });
+  await payoutRepo.pay(input);
 }
-
-const entries = await walletRepo.getStatement({
-  wallet,
-  range: {
-    startDate: new Date("2024-01-01"),
-    endDate: new Date("2024-01-31"),
-  },
-});
 ```
 
-#### Identity Example
+### Server-side usage
 
-`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
+Repositories work on the server too — extract the bearer token from the incoming request and pass it through:
 
 ```typescript
 import { WalletRepository } from "@temboplus/afloat";
 
-function extractBearerToken(req): string | undefined {
-  return req.headers.authorization?.replace(/^Bearer\s+/i, "");
-}
-
 app.get("/api/wallets", async (req, res) => {
-  const token = extractBearerToken(req);
-
-  if (!token) {
-    return res.status(401).json({ error: "Unauthorized" });
-  }
+  const token = req.headers.authorization?.replace(/^Bearer\s+/i, "");
+  if (!token) return res.status(401).json({ error: "Unauthorized" });
 
   const walletRepo = new WalletRepository({ token });
-  const wallets = await walletRepo.getWallets();
-
-  return res.json({ wallets });
+  return res.json({ wallets: await walletRepo.getWallets() });
 });
 ```
 
-## Architecture Overview
-
-### Host Application Responsibilities
-
-* 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)`
-
-### Library Responsibilities
-
-* 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
-
-## Best Practices
-
-### Token Handling
-
-```typescript
-import {
-  AuthRepository,
-  ProfileRepository,
-  WalletRepository,
-} from "@temboplus/afloat";
-
-const authRepo = new AuthRepository();
-const user = await authRepo.logIn(email, password);
-
-saveToken(user.token);
-
-const walletRepo = new WalletRepository({ token: user.token });
-const profileRepo = new ProfileRepository({ token: user.token });
-```
-
-### Permission Checks
-
-```typescript
-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
-
-#### `AfloatAuth` Import Errors
-
-**Problem**: `AfloatAuth` is undefined or cannot be imported.
-
-**Solution**: Replace `AfloatAuth` usage with `AuthRepository.logIn(...)` plus application-owned session state.
-
-```typescript
-import { AuthRepository } from "@temboplus/afloat";
-
-const authRepo = new AuthRepository();
-const user = await authRepo.logIn(email, password);
-const token = user.token;
-```
-
-#### Repository Token Issues
+## Consumed By
 
-**Problem**: Repository calls fail with authentication errors.
+- **TemboPlus Afloat** (Next.js frontend) — customer-facing app.
+- **TemboPlus Reports** (NestJS backend) — Afloat-specific report generation.
 
-**Solution**: Ensure the token from login or the incoming request is passed into the repository.
+## Development
 
-```typescript
-if (!extractedToken) {
-  throw new Error("Missing authentication token");
-}
+Bun for everything, Biome for lint+format, mise for the toolchain pin.
 
-const repo = new WalletRepository({ token: extractedToken });
+```bash
+mise install        # one-time: installs pinned Bun
+bun install
+bun run dev         # rollup build in watch mode
 ```
 
-#### Identity Repository Confusion
-
-**Problem**: `IdentityRepository` is used for login.
-
-**Solution**: Use `AuthRepository.logIn(...)` for login. Use `IdentityRepository({ token }).getIdentity()` only after you have a token.
+| Script | Does |
+| --- | --- |
+| `bun run dev` | Rollup build in watch mode |
+| `bun run build` | Rollup build to `dist/` (CJS + ESM + `.d.ts`) |
+| `bun run test` | `bun:test` (passes with zero tests; smoke test only) |
+| `bun run lint` | Biome check |
+| `bun run format` | Biome auto-fix |
+| `bun run typecheck` | `tsc --noEmit` |
 
-## API Reference
+Tag-driven releases via `.github/workflows/release.yml` — update `CHANGELOG.md`, bump `package.json`, push a `vX.Y.Z` tag.
 
-### 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
-
-### Authenticated Repositories
-
-All authenticated repositories use:
-
-```typescript
-new RepositoryName({
-  token: "user-auth-token",
-  root: "custom-api-root", // optional
-});
-```
-
-Available repositories:
+## License
 
-* `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
+[MIT](./LICENSE) © TemboPlus