joopjs 2.0.4 → 2.0.6

package/.claude/skills/auth.md

@@ -0,0 +1,235 @@
+# /auth — JoopJS Authentication Services
+
+> Author: Kundan Singh
+
+All auth services are imported from `'joopjs'`. Instantiate as plain singletons.
+
+---
+
+## Auth Service
+
+```ts
+import { JoopAuthService } from 'joopjs';
+const auth = new JoopAuthService();
+
+const session = await auth.login('alice@bank.com', 'password123');
+// session: { userId, sessionId, accessToken, refreshToken, expiresAt }
+
+const refreshed = await auth.refresh(session.refreshToken);
+await auth.logout(session.sessionId);
+
+const me = auth.getCurrentUser();                       // JoopAuthUser | null
+auth.session$().subscribe(session => { });              // reactive session changes
+
+auth.onEvent('login',  e => console.log('Login:', e.userId));
+auth.onEvent('logout', e => console.log('Logout'));
+```
+
+**Key types:** `JoopAuthUser`, `JoopAuthSession`, `JoopAuthToken`, `JoopAuthEvent`
+
+---
+
+## OTP Service
+
+```ts
+import { JoopOtpService } from 'joopjs';
+const otp = new JoopOtpService({ expiryMs: 5 * 60_000, length: 6 });
+
+const token = otp.generate('u-001', 'login');           // { otp: '483920', expiresAt }
+const ok     = otp.verify('u-001', 'login', '483920'); // boolean
+// auto-invalidated after single use
+
+// TOTP (time-based)
+const secret = otp.generateTotpSecret();               // base32 secret
+const qrUri  = otp.getTotpUri('alice@bank.com', secret, 'MyBank');
+const valid  = otp.verifyTotp(secret, userEnteredCode);
+```
+
+---
+
+## JWT Service
+
+```ts
+import { JoopJwtService } from 'joopjs';
+const jwt = new JoopJwtService({ secret: 'my-secret', expiryMs: 3600_000 });
+
+const token  = jwt.sign({ userId: 'u-001', role: 'admin' });
+const claims = jwt.verify(token);                      // { userId, role, iat, exp } | null
+const decoded = jwt.decode(token);                     // decode without verification
+const renewed = jwt.renew(token);                      // extends expiry
+const revoked = jwt.revoke(token);                     // blacklists token
+const isRevoked = jwt.isRevoked(token);                // boolean
+```
+
+---
+
+## MFA Service
+
+```ts
+import { JoopMfaService } from 'joopjs';
+const mfa = new JoopMfaService();
+
+mfa.enroll('u-001', 'totp');                           // or 'sms', 'email', 'hardware-key'
+const challenge = mfa.challenge('u-001');              // { challengeId, method, hint }
+const result = mfa.respond(challenge.challengeId, userCode);
+// result: { passed: true, sessionUpgraded: true }
+
+const methods = mfa.getEnrolledMethods('u-001');       // ['totp']
+mfa.unenroll('u-001', 'totp');
+mfa.status$().subscribe(event => { });
+```
+
+---
+
+## PKCE / OAuth 2.0
+
+```ts
+import { JoopPkceService } from 'joopjs';
+const pkce = new JoopPkceService({
+  clientId: 'my-app',
+  redirectUri: 'https://app.example.com/callback',
+  authorizationEndpoint: 'https://auth.bank.com/authorize',
+  tokenEndpoint: 'https://auth.bank.com/token',
+  scopes: ['openid', 'profile', 'accounts'],
+});
+
+const { url, codeVerifier, state } = pkce.buildAuthorizationUrl();
+// Redirect user to `url`, store codeVerifier + state
+
+const tokens = await pkce.exchangeCode(authorizationCode, codeVerifier);
+// { accessToken, refreshToken, idToken, expiresIn }
+
+const refreshed = await pkce.refreshTokens(tokens.refreshToken);
+const claims = pkce.parseIdToken(tokens.idToken);      // OIDC claims
+```
+
+---
+
+## OIDC Service
+
+```ts
+import { JoopOidcService } from 'joopjs';
+const oidc = new JoopOidcService({ issuer: 'https://auth.bank.com', clientId: 'my-app' });
+
+await oidc.loadDiscovery();                            // fetches /.well-known/openid-configuration
+const url = oidc.buildLoginUrl({ redirectUri: 'https://app.example.com/callback', scopes: ['openid', 'email'] });
+const user = await oidc.processCallback(callbackUrl);  // JoopOidcUser
+const info = await oidc.getUserInfo(accessToken);
+await oidc.endSession(idToken, 'https://app.example.com');
+```
+
+---
+
+## SSO Service
+
+```ts
+import { JoopSsoService } from 'joopjs';
+const sso = new JoopSsoService();
+
+sso.registerProvider({ id: 'azure-ad', name: 'Azure AD', type: 'oidc',
+  clientId: '...', clientSecret: '...', discoveryUrl: 'https://login.microsoftonline.com/.../v2.0' });
+
+const loginUrl = sso.getLoginUrl('azure-ad', { redirectUri: '/callback' });
+const session = await sso.handleCallback('azure-ad', callbackParams);
+// session.user: { id, email, name, groups, provider }
+
+sso.setRoleMapping('azure-ad', { 'BankAdmins': 'admin', 'BankUsers': 'user' });
+const appRole = sso.mapRole('azure-ad', 'BankAdmins');  // 'admin'
+```
+
+---
+
+## Biometric Auth
+
+```ts
+import { JoopBiometricAuthService } from 'joopjs';
+const bio = new JoopBiometricAuthService();
+
+const available = await bio.isAvailable();             // { fingerprint, faceId, iris }
+await bio.enroll('u-001', 'fingerprint');
+const result = await bio.authenticate('u-001', 'fingerprint');
+// { authenticated: true, confidence: 0.98, method: 'fingerprint' }
+
+bio.revoke('u-001', 'fingerprint');
+bio.authEvent$().subscribe(event => { });
+```
+
+---
+
+## Permission / RBAC
+
+```ts
+import { JoopPermissionService } from 'joopjs';
+const perms = new JoopPermissionService();
+
+perms.defineRole('admin',  ['accounts:read', 'accounts:write', 'transfers:approve']);
+perms.defineRole('teller', ['accounts:read', 'transfers:initiate']);
+
+perms.assignRole('u-001', 'admin');
+perms.grantPermission('u-002', 'reports:read');
+
+const can = perms.check('u-001', 'transfers:approve');  // true
+const all = perms.getPermissions('u-001');               // string[]
+perms.revokeRole('u-001', 'admin');
+```
+
+---
+
+## Rate Limiter (Auth Protection)
+
+```ts
+import { JoopRateLimiterService } from 'joopjs';
+const rl = new JoopRateLimiterService();
+
+rl.configure('login', { maxAttempts: 5, windowMs: 15 * 60_000, blockDurationMs: 30 * 60_000 });
+
+const result = rl.check('login', 'u-001');
+// { allowed: true, remaining: 4, resetAt: number }
+
+rl.record('login', 'u-001', false);                    // record failed attempt
+rl.record('login', 'u-001', true);                     // success — resets counter
+rl.block('login', 'u-001');                            // force block
+const status = rl.getStatus('login', 'u-001');
+// { blocked: false, attempts: 2, remaining: 3, resetAt }
+```
+
+---
+
+## Session Management
+
+```ts
+import { JoopSessionService } from 'joopjs';
+const sessions = new JoopSessionService({ idleTimeoutMs: 15 * 60_000, absoluteTimeoutMs: 8 * 3600_000 });
+
+const s = sessions.create({ userId: 'u-001', ipAddress: '10.0.0.1', userAgent: 'Chrome/120' });
+sessions.touch(s.id);                                  // reset idle timer
+const valid = sessions.validate(s.id);                 // { valid, reason? }
+sessions.invalidate(s.id);
+sessions.invalidateAll('u-001');                        // logout all devices
+sessions.expired$().subscribe(s => console.log('Session expired:', s.id));
+```
+
+---
+
+## What Gets Published to npm
+
+Controlled by `"files"` in `package.json` — acts as an allowlist. Only these two are included:
+
+| Published to npm | Never published |
+|-----------------|----------------|
+| `dist/` — ESM + CJS + `.d.ts` for all 34 sub-paths | `src/` — TypeScript source |
+| `CHANGELOG.md` — release history | `tests/` — test suite |
+| | `scripts/` — release automation |
+| | `playground/` — Vite demo app |
+| | `.claude/` — Claude skills (including this file) |
+| | `.cursor/` — Cursor rules |
+| | `.windsurf/` — Windsurf rules |
+| | `GEMINI.md`, `AGENTS.md` — AI tool instructions |
+| | `tsup.config.ts`, `vitest.config.ts`, `tsconfig.json` |
+
+Source code, AI rules, and dev tooling are **never** published to npm.
+
+Verify the tarball contents before any publish:
+```bash
+npm pack --dry-run
+```

package/.claude/skills/banking.md

@@ -0,0 +1,377 @@
+# /banking — JoopJS Banking Services
+
+> Author: Kundan Singh
+
+All banking services are imported from `'joopjs'`. Instantiate as plain singletons.
+
+---
+
+## Digital Wallet
+
+```ts
+import { JoopDigitalWalletService } from 'joopjs';
+const wallet = new JoopDigitalWalletService();
+
+const w = wallet.createWallet('user-001', { currency: 'USD', label: 'Primary' });
+wallet.topUp(w.id, 500);
+wallet.pay(w.id, 50, 'merchant-1', 'Coffee Shop');
+wallet.transfer(w.id, otherWalletId, 100);
+wallet.freeze(w.id);  wallet.unfreeze(w.id);  wallet.close(w.id);  // requires zero balance
+const bal = wallet.getBalance(w.id);                                 // number
+const txns = wallet.getTransactions(w.id, 20);                      // last 20, newest first
+wallet.balance$().subscribe(({ walletId, balance }) => { });        // reactive
+```
+
+**Key types:** `JoopWallet`, `JoopWalletTransaction`, `JoopWalletStatus`, `JoopWalletTxnType`, `JoopTransferResult`
+
+---
+
+## Loan Servicing
+
+```ts
+import { JoopLoanServicingService } from 'joopjs';
+const loans = new JoopLoanServicingService();
+
+const loan = loans.createLoan({
+  borrowerName: 'Alice', borrowerId: 'u-001',
+  principalAmount: 120_000, annualInterestRatePercent: 12, tenureMonths: 24,
+  currency: 'USD',
+});
+// loan.ref → 'LN-2026-000001', loan.emiAmount auto-calculated
+
+loans.recordPayment(loan.id, loan.emiAmount);           // interest-first allocation
+const sched  = loans.getSchedule(loan.id);              // JoopInstallment[]
+const stmt   = loans.getLoanStatement(loan.id);         // full statement
+const bal    = loans.getOutstandingBalance(loan.id);    // number
+loans.markDefaulted(loan.id);
+loans.waveInstallment(loan.id, 3);                      // waive installment #3
+```
+
+**Key types:** `JoopLoanAccount`, `JoopInstallment`, `JoopLoanPayment`, `JoopLoanStatement`, `JoopLoanAccountStatus`, `JoopRepaymentStatus`
+
+---
+
+## FX Forward Contracts
+
+```ts
+import { JoopFxForwardService } from 'joopjs';
+const fx = new JoopFxForwardService();
+
+fx.setSpotRate('USD', 'EUR', 0.92);                     // auto-creates inverse
+const fwd = fx.createForward({
+  type: 'sell', baseCurrency: 'USD', quoteCurrency: 'EUR',
+  notionalAmount: 100_000, contractRate: 0.92,
+  maturityDate: Date.now() + 90 * 86_400_000,
+});
+// fwd.ref → 'FWD-2026-000001'
+
+const settlement = fx.settleForward(fwd.id, 0.90);      // settlement.pnl = 2000
+fx.cancelForward(fwd.id);
+const mtm = fx.getMarkToMarket(fwd.id);                 // unrealized P&L
+const exp = fx.getExposure('USD');                       // JoopFxExposure[]
+const expiring = fx.getExpiring(7 * 86_400_000);        // due in 7 days
+```
+
+**Key types:** `JoopFxForward`, `JoopForwardSettlement`, `JoopFxExposure`, `JoopForwardType`, `JoopForwardStatus`
+
+---
+
+## Ledger (Double-Entry Bookkeeping)
+
+```ts
+import { JoopLedgerService } from 'joopjs';
+const ledger = new JoopLedgerService();
+
+ledger.addAccount('1001', 'Cash',         'asset');
+ledger.addAccount('4001', 'Sales Revenue','revenue');
+
+const entry = ledger.postEntry('Sale', [
+  { accountCode: '1001', debit: 1000, credit: 0 },
+  { accountCode: '4001', debit: 0,    credit: 1000 },
+]);
+// entry.ref → 'JE-2026-000001'
+
+const bal   = ledger.getBalance('1001');                // 1000
+const trial = ledger.getTrialBalance();                 // { rows, totalDebits, totalCredits, isBalanced }
+```
+
+**Key types:** `JoopAccountType` ('asset'|'liability'|'equity'|'revenue'|'expense'), `JoopLedgerAccount`, `JoopJournalEntry`, `JoopTrialBalance`
+
+---
+
+## Reconciliation
+
+```ts
+import { JoopReconciliationService } from 'joopjs';
+const recon = new JoopReconciliationService();
+
+const session = recon.createSession('ACC-001', bankItems, internalItems);
+recon.autoMatch(session.id, 0, 3);                      // tolerance: $0, 3 days
+recon.manualMatch(session.id, internalId, bankId);
+const summary = recon.getSummary(session.id);
+// { matchedPairs, unmatchedInternal, unmatchedBank, totalDifference, isReconciled }
+```
+
+---
+
+## Limit Management
+
+```ts
+import { JoopLimitManagementService } from 'joopjs';
+const limits = new JoopLimitManagementService();
+
+limits.setLimit({
+  scope: 'account', scopeId: 'ACC-001', type: 'daily',
+  currency: 'USD', maxAmount: 10_000, enabled: true,
+});
+const check = limits.checkLimit('account', 'ACC-001', 'daily', 'USD', 5000);
+// null = no limit configured; { allowed, remaining, used } if configured
+limits.recordUsage('account', 'ACC-001', 'daily', 'USD', 5000);
+```
+
+**Key types:** `JoopLimitType` ('per-transaction'|'daily'|'weekly'|'monthly'|'yearly'), `JoopLimitScope`, `JoopLimit`, `JoopLimitCheckResult`
+
+---
+
+## Standing Orders
+
+```ts
+import { JoopStandingOrderService } from 'joopjs';
+const so = new JoopStandingOrderService();
+
+const order = so.create({
+  fromAccount: 'ACC-001', toAccount: 'ACC-002',
+  toBeneficiaryName: 'Rent', amount: 1500,
+  frequency: 'monthly', startDate: Date.now(),
+  currency: 'USD',
+});
+// order.ref → 'SO-2026-000001'
+
+const exec  = so.execute(order.id, 'success');          // advances nextExecutionAt
+const due   = so.getDue();                              // orders due now
+so.pause(order.id);  so.resume(order.id);  so.cancel(order.id);
+```
+
+---
+
+## Insurance
+
+```ts
+import { JoopInsuranceService } from 'joopjs';
+const ins = new JoopInsuranceService();
+
+const policy = ins.addPolicy({
+  type: 'life', holderName: 'Alice', holderId: 'u-001',
+  coverageAmount: 500_000, annualPremium: 2400,
+  startDate: Date.now(), endDate: Date.now() + 365 * 86_400_000,
+  frequency: 'monthly',
+});
+ins.fileClaim(policy.id, 1000, 'Hospital stay');        // claimNumber CLM-2026-000001
+ins.renewPolicy(policy.id, Date.now() + 730 * 86_400_000);
+ins.recordPremiumPayment(policy.id, 200);
+const expiring = ins.getExpiring(30 * 86_400_000);     // expiring in 30 days
+```
+
+---
+
+## Remittance
+
+```ts
+import { JoopRemittanceService } from 'joopjs';
+const rem = new JoopRemittanceService();
+
+rem.setExchangeRate('USD', 'INR', 83.5);
+const quote = rem.getQuote('USD', 'INR', 1000);
+// { sendAmount:1000, fee:25, receiveAmount:81543.75, exchangeRate:83.5 }
+
+const tx = rem.initiate({
+  senderId: 'u-001', senderName: 'Alice',
+  receiverId: 'u-002', receiverName: 'Bob',
+  sourceCurrency: 'USD', targetCurrency: 'INR',
+  sendAmount: 1000, channel: 'swift',
+});
+// tx.ref → 'RMT-2026-000001'
+
+rem.updateStatus(tx.id, 'completed');
+const history = rem.getHistory('u-001', 5);            // last 5, newest first
+```
+
+---
+
+## Virtual Accounts
+
+```ts
+import { JoopVirtualAccountService } from 'joopjs';
+const va = new JoopVirtualAccountService();
+
+const acct = va.create({ parentAccountId: 'ACC-001', purpose: 'escrow', currency: 'USD', expectedAmount: 5000 });
+va.recordCredit(acct.id, 2500, { reference: 'INV-001' });
+const full = va.isFullyCollected(acct.id);              // false (2500 of 5000)
+va.close(acct.id);
+const byRef = va.getByReference(acct.accountNumber);
+```
+
+---
+
+## Card Management
+
+```ts
+import { JoopCardManagementService } from 'joopjs';
+const cards = new JoopCardManagementService();
+
+const card = cards.issueCard({ userId: 'u-001', cardType: 'virtual', network: 'visa', currency: 'USD' });
+cards.freeze(card.id);  cards.unfreeze(card.id);
+cards.setSpendingLimits(card.id, { daily: 500, monthly: 5000, perTransaction: 200 });
+cards.setControls(card.id, { onlineAllowed: true, internationalAllowed: false });
+const check = cards.checkTransaction(card.id, { amount: 100, merchant: 'Amazon', channel: 'online' });
+// { allowed: true, reason: null }
+```
+
+---
+
+## Dispute Management
+
+```ts
+import { JoopDisputeService } from 'joopjs';
+const disputes = new JoopDisputeService();
+
+const d = disputes.file({ userId: 'u-001', transactionId: 'TXN-001', reason: 'unauthorized', amount: 99.99 });
+disputes.uploadEvidence(d.id, { type: 'screenshot', description: 'Charge I did not make' });
+disputes.resolve(d.id, 'resolved-in-favor', 'Refund issued');
+const stats = disputes.getStats();
+```
+
+---
+
+## Bill Payment
+
+```ts
+import { JoopBillPaymentService } from 'joopjs';
+const bills = new JoopBillPaymentService();
+
+bills.addBiller({ id: 'ELEC-001', name: 'City Electric', category: 'utilities', accountFormat: 'ACCT-####' });
+const bill = bills.createBill({ billerId: 'ELEC-001', accountNumber: 'ACCT-1234', amount: 150, dueDate: Date.now() + 7 * 86_400_000 });
+const payment = bills.pay(bill.id, 150, 'wallet');
+const upcoming = bills.getUpcoming(7 * 86_400_000);    // due in 7 days
+```
+
+---
+
+## Statement Generator
+
+```ts
+import { JoopStatementGeneratorService } from 'joopjs';
+const gen = new JoopStatementGeneratorService();
+
+gen.addTransaction({ id: 'T1', date: Date.now(), amount: -50, description: 'Coffee', type: 'debit', balance: 950 });
+const stmt = gen.generate({ accountId: 'ACC-001', from: startTs, to: endTs, format: 'pdf' });
+```
+
+---
+
+## Beneficiary
+
+```ts
+import { JoopBeneficiaryService } from 'joopjs';
+const bene = new JoopBeneficiaryService();
+
+const b = bene.add({ userId: 'u-001', name: 'Bob', type: 'bank', accountNumber: '12345678', bankCode: 'HSBC' });
+const v = bene.validate(b.id);                         // { valid, errors }
+const list = bene.getAll('u-001');
+bene.remove(b.id);
+```
+
+---
+
+## Mandate (Direct Debit)
+
+```ts
+import { JoopMandateService } from 'joopjs';
+const mandates = new JoopMandateService();
+
+const m = mandates.create({ userId: 'u-001', creditorName: 'Netflix', amount: 15.99, currency: 'USD', frequency: 'monthly', startDate: Date.now() });
+mandates.execute(m.id, 15.99);                         // records execution
+mandates.pause(m.id);  mandates.resume(m.id);  mandates.cancel(m.id);
+const due = mandates.getDue();
+```
+
+---
+
+## Split Payment
+
+```ts
+import { JoopSplitPaymentService } from 'joopjs';
+const split = new JoopSplitPaymentService();
+
+const exp = split.createExpense({ title: 'Dinner', totalAmount: 120, paidById: 'u-001', method: 'equal' });
+split.addParticipant(exp.id, { userId: 'u-002', name: 'Bob' });
+split.addParticipant(exp.id, { userId: 'u-003', name: 'Carol' });
+split.settle(exp.id, 'u-002');                          // mark u-002 as settled
+const balances = split.getBalances(exp.id);
+```
+
+---
+
+## Payment URI (QR / UPI / SEPA)
+
+```ts
+import { JoopPaymentUriService } from 'joopjs';
+const uri = new JoopPaymentUriService();
+
+const upiUri = uri.generate({ scheme: 'upi', payeeVpa: 'merchant@bank', amount: 100, currency: 'INR' });
+const parsed = uri.parse('upi://pay?pa=merchant@bank&am=100');
+```
+
+---
+
+## Open Banking
+
+```ts
+import { JoopOpenBankingClient } from 'joopjs';
+const ob = new JoopOpenBankingClient({ baseUrl: 'https://api.bank.com', clientId: 'my-app' });
+
+const consent = await ob.requestConsent({ permissions: ['accounts', 'transactions'], userId: 'u-001' });
+const accounts = await ob.getAccounts(consent.consentId);
+const txns = await ob.getTransactions(accounts[0].accountId, { from: startTs, to: endTs });
+const payment = await ob.initiatePayment({ debtorAccount: 'ACC-001', creditorAccount: 'ACC-002', amount: 500 });
+```
+
+---
+
+## Chequebook
+
+```ts
+import { JoopChequebookService } from 'joopjs';
+const cheques = new JoopChequebookService();
+
+const book = cheques.requestChequebook({ accountId: 'ACC-001', leaves: 25 });
+cheques.activateChequebook(book.id);
+const leaf = cheques.issueLeaf(book.id, { payeeName: 'Alice', amount: 500, date: Date.now() });
+cheques.markCleared(leaf.chequeNumber);
+const stats = cheques.getStats(book.id);
+```
+
+---
+
+## What Gets Published to npm
+
+Controlled by `"files"` in `package.json` — acts as an allowlist. Only these two are included:
+
+| Published to npm | Never published |
+|-----------------|----------------|
+| `dist/` — ESM + CJS + `.d.ts` for all 34 sub-paths | `src/` — TypeScript source |
+| `CHANGELOG.md` — release history | `tests/` — test suite |
+| | `scripts/` — release automation |
+| | `playground/` — Vite demo app |
+| | `.claude/` — Claude skills (including this file) |
+| | `.cursor/` — Cursor rules |
+| | `.windsurf/` — Windsurf rules |
+| | `GEMINI.md`, `AGENTS.md` — AI tool instructions |
+| | `tsup.config.ts`, `vitest.config.ts`, `tsconfig.json` |
+
+Source code, AI rules, and dev tooling are **never** published to npm.
+
+Verify the tarball contents before any publish:
+```bash
+npm pack --dry-run
+```