joopjs 2.0.5 → 2.1.0

package/README.md

@@ -2,10 +2,10 @@
 
 **Enterprise-grade, framework-agnostic TypeScript SDK for financial applications.**
 
-[![npm version](https://img.shields.io/badge/npm-v2.0.2-blue)](https://www.npmjs.com/package/joopjs)
+[![npm version](https://img.shields.io/badge/npm-v2.1.0-blue)](https://www.npmjs.com/package/joopjs)
 [![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
-[![tests](https://img.shields.io/badge/tests-2168%20passed-success)](#)
+[![tests](https://img.shields.io/badge/tests-2189%20passed-success)](#)
 [![playground](https://img.shields.io/badge/playground-live-orange)](https://kundan-leo.github.io/JoopJs/demo/)
 [![github](https://img.shields.io/badge/github-kundan--leo%2FJoopJs-black?logo=github)](https://github.com/kundan-leo/JoopJs)
 
@@ -17,11 +17,14 @@
 
 JoopJS provides 80+ production-ready services covering banking, finance, security, authentication, and encryption — all as plain TypeScript classes with no framework dependencies. Works with **React 18+**, **Angular 17+**, **Vue 3+**, or any plain TypeScript/JavaScript project.
 
+**New in 2.1.0:** real Angular 17+ DI in `joopjs/angular` (`provideJoopAngular`, `injectJoop`, `joopSignal`), federation-safe singletons in `joopjs/core` (`globalSingleton`, `joopCopyCount`, `silenceDuplicateCopyWarning`) for Module Federation micro-frontends, and error-isolated observable emission.
+
 ---
 
 ## Table of Contents
 
 - [Install](#install)
+- [AI Assistant Setup](#ai-assistant-setup)
 - [Quick Start](#quick-start)
 - [Service Catalogue](#service-catalogue)
   - [Banking](#banking-26-services)
@@ -60,6 +63,33 @@ No mandatory peer dependencies — React / Angular / Vue bindings are opt-in.
 
 ---
 
+## AI Assistant Setup
+
+JoopJS ships rules for all major AI coding tools. One command sets them up in your project:
+
+```bash
+npx joopjs setup-ai
+```
+
+This copies joopjs-aware rules so that **Claude Code**, **Cursor**, **Windsurf**, **GitHub Copilot**, **Gemini CLI**, and **Codex** all understand the joopjs API — correct imports, service patterns, observable rules, and data types.
+
+| Tool | What gets copied |
+|------|-----------------|
+| Claude Code | `.claude/skills/joopjs-*.md` — 7 skills (setup, banking, finance, security, auth, encryption, observables) |
+| Cursor | `.cursor/rules/joopjs.mdc` — auto-applied to all `.ts` / `.tsx` / `.js` files |
+| Windsurf | `.windsurf/rules/joopjs.md` — loaded by Cascade automatically |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Gemini CLI | `GEMINI.md` |
+| Codex / OpenAI | `AGENTS.md` |
+
+```bash
+npx joopjs setup-ai --force   # overwrite after upgrading joopjs
+```
+
+> **Claude Code users:** after running, the command output shows the exact skill lines to add to your `CLAUDE.md`.
+
+---
+
 ## Quick Start
 
 ### 1. Initialise
@@ -446,27 +476,33 @@ function BalanceCard({ walletId }: { walletId: string }) {
 
 ### Angular
 
+Real Angular 17+ DI. Only the `joopjs/angular` adapter imports `@angular/*` — the core SDK stays framework-agnostic.
+
 ```typescript
 // app.config.ts (standalone)
 import { ApplicationConfig } from '@angular/core';
-import { provideJoop } from 'joopjs/angular';
+import { provideJoopAngular } from 'joopjs/angular';
 import { createJoop } from 'joopjs';
 
 export const appConfig: ApplicationConfig = {
   providers: [
-    provideJoop(createJoop({ env: 'production', appId: 'my-app' })),
+    ...provideJoopAngular(createJoop({ env: 'production', appId: 'my-app' })),
   ],
 };
 ```
 
 ```typescript
 // component.ts
-import { inject } from '@angular/core';
-import { JOOP_AUTH } from 'joopjs/angular';
+import { injectJoop, joopSignal } from 'joopjs/angular';
+import { JoopAuthService } from 'joopjs';
 
 @Component({ ... })
 export class LoginComponent {
-  private auth = inject(JOOP_AUTH);
+  private joop = injectJoop();               // typed JoopInstance via JOOP_INSTANCE
+  private auth = new JoopAuthService();
+
+  // Bridge any JoopJS observable to an Angular signal — auto-teardown via DestroyRef
+  session = joopSignal(this.auth.session$());
 
   async login(email: string, password: string) {
     const session = await this.auth.login(email, password);
@@ -475,6 +511,8 @@ export class LoginComponent {
 }
 ```
 
+> Granular injection tokens still exist, and `joopAuthGuard()` (a `CanActivateFn`) plus `joopAuthInterceptor()` (an `HttpInterceptorFn`) are available for routing and HTTP. `provideJoop()`, `JoopModule`, and `fromJoop()` are deprecated but still functional.
+
 ### Vue
 
 ```typescript
@@ -533,6 +571,8 @@ unsub();
 
 **Critical rule:** Always use `.next(value)` to emit — **never `.emit(value)`** (that method does not exist).
 
+Emission is **error-isolated**: `next()` wraps each subscriber call in try/catch over a snapshot of its listeners, so one bad subscriber won't break the stream for the others. Route subscriber errors anywhere with `setSubjectErrorHandler` (default: `console.error`).
+
 ---
 
 ## TypeScript Types

package/ai-rules/AGENTS.md

@@ -0,0 +1,241 @@
+# AGENTS.md — JoopJS SDK
+
+This file instructs AI coding agents (Codex, OpenAI Agents, and similar) on how to generate code using the **joopjs** SDK.
+
+---
+
+## Package
+
+```bash
+npm install joopjs
+```
+
+**joopjs** is a framework-agnostic TypeScript SDK for enterprise financial applications. Works with React, Angular, Vue, Node.js, and plain TypeScript.
+
+---
+
+## Import Rules
+
+```ts
+// Main entry — everything
+import { JoopAuthService, JoopDigitalWalletService } from 'joopjs';
+
+// Sub-path imports (tree-shakeable, preferred)
+import { JoopGcmService }   from 'joopjs/encryption';
+import { JoopAuthService }  from 'joopjs/auth';
+import { JoopCacheService } from 'joopjs/cache';
+```
+
+Available sub-paths: `auth`, `encryption`, `banking`, `security`, `api`, `core`, `session`, `device`, `observability`, `theme`, `i18n`, `ui`, `forms`, `router`, `state`, `workers`, `workflow`, `sync`, `platform`, `cache`, `network`, `analytics`, `validation`, `utilities`, `pwa`, `native-bridge`, `deeplink`, `react`, `angular`, `vue`, `india`.
+
+**Never** import from internal paths (`joopjs/src/...`, `joopjs/dist/...`).
+
+`joopjs/core` exposes `globalSingleton`, `joopCopyCount`, and `silenceDuplicateCopyWarning`. In Module Federation micro-frontends, share joopjs as a singleton (`shared: { joopjs: { singleton: true } }`) so logger/config/event-bus state does not fragment across multiple loaded copies.
+
+---
+
+## Service Instantiation
+
+All services are plain classes — no DI framework, no `@Injectable`, no container:
+
+```ts
+const wallet  = new JoopDigitalWalletService();
+const auth    = new JoopAuthService();
+const gcm     = new JoopGcmService();
+const loans   = new JoopLoanServicingService();
+```
+
+Create once per module and reuse as singletons.
+
+---
+
+## Reactive Observables — Critical Rules
+
+joopjs uses its own `JoopSubject` — **not RxJS**:
+
+```ts
+// Subscribe — always returns an unsubscribe function
+const unsub = service.event$().subscribe(value => {
+  console.log(value);
+});
+
+// Emit
+subject.next(newValue);       // CORRECT
+subject.emit(newValue);       // WRONG — throws, does not exist
+
+// Current value (BehaviorSubject only)
+const val = behaviorSubject.getValue();
+
+// Clean up
+unsub();                      // call the returned function
+// NOT .unsubscribe()         // wrong — does not exist
+// NOT subject.pipe(map(...)) // wrong — not RxJS
+```
+
+`next()` is error-isolated: if one subscriber throws, delivery to the other subscribers still proceeds. Route subscriber errors with `setSubjectErrorHandler(fn)` (default `console.error`).
+
+---
+
+## Data Type Rules — Always Follow These
+
+| Concept | Correct type | Never use |
+|---------|-------------|-----------|
+| Money amount | `number` | `BigDecimal`, `Money`, `string` |
+| Currency | `string` ISO-4217 | enum, number |
+| Timestamp | `number` Unix epoch ms — `Date.now()` | `new Date()`, `string` |
+| ID | `string` | `number` |
+
+---
+
+## Error Handling
+
+```ts
+try {
+  const result = await service.doSomething(config);
+} catch (err) {
+  if (err instanceof Error) {
+    console.error(err.message);
+  }
+}
+```
+
+---
+
+## Common Code Patterns
+
+### 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-id', 'Coffee');
+wallet.transfer(w.id, toWalletId, 200);
+const bal = wallet.getBalance(w.id);
+wallet.balance$().subscribe(({ walletId, balance }) => { /* update UI */ });
+```
+
+### Auth + JWT
+```ts
+import { JoopAuthService } from 'joopjs/auth';
+
+const auth = new JoopAuthService();
+const session = await auth.login(email, password);
+auth.session$().subscribe(session => { /* null = logged out */ });
+await auth.logout(session.sessionId);
+```
+
+### AES-GCM Encryption
+```ts
+import { JoopGcmService } from 'joopjs/encryption';
+
+const gcm = new JoopGcmService();
+const key = await gcm.generateKey();
+const { ciphertext, iv } = await gcm.encrypt('sensitive', key);
+const plain = await gcm.decrypt(ciphertext, key, iv);
+```
+
+### Loan Servicing
+```ts
+import { JoopLoanServicingService } from 'joopjs';
+
+const loans = new JoopLoanServicingService();
+const loan = loans.createLoan({
+  borrowerName: 'Alice', borrowerId: 'u-001',
+  principalAmount: 10000, annualInterestRatePercent: 8,
+  tenureMonths: 12, currency: 'USD'
+});
+loans.recordPayment(loan.id, loan.emiAmount);
+const schedule = loans.getSchedule(loan.id);
+```
+
+### Sanctions Screening
+```ts
+import { JoopSanctionsScreeningService } from 'joopjs';
+
+const sanctions = new JoopSanctionsScreeningService();
+sanctions.loadList('ofac', entities);
+const result = sanctions.screen({ name: customerName, country: customerCountry });
+if (result.status !== 'clear') { /* block or escalate */ }
+```
+
+### AML
+```ts
+import { JoopAmlService } from 'joopjs';
+
+const aml = new JoopAmlService();
+aml.addRule({ id: 'r1', name: 'Large cash', type: 'cash', threshold: 10000, currency: 'USD', action: 'flag', enabled: true });
+const alert = aml.checkTransaction({ id: 'tx1', amount: 15000, currency: 'USD', type: 'cash', userId: 'u-001', timestamp: Date.now() });
+// null = passes; JoopAmlAlert = flagged
+```
+
+### Mutual Fund SIP
+```ts
+import { JoopMutualFundService } from 'joopjs';
+
+const mf = new JoopMutualFundService();
+mf.registerFund({ id: 'f1', name: 'Growth Fund', category: 'equity', currentNav: 45.5, currency: 'USD' });
+mf.invest('f1', 'investor-001', 1000);
+const sip = mf.createSip('f1', 'investor-001', 500, 'monthly', Date.now());
+mf.executeSip(sip.id);
+```
+
+### Framework Integration — React
+```tsx
+import React, { useEffect } from 'react';
+import { JoopDigitalWalletService } from 'joopjs';
+
+const wallet = new JoopDigitalWalletService();
+
+function WalletBalance() {
+  const [balance, setBalance] = React.useState(0);
+
+  useEffect(() => {
+    const unsub = wallet.balance$().subscribe(({ balance }) => setBalance(balance));
+    return unsub; // cleanup on unmount
+  }, []);
+
+  return <div>{balance}</div>;
+}
+```
+
+### Framework Integration — Angular (17+ DI)
+```ts
+// adapter imports @angular/*; the core SDK never does
+import { provideJoopAngular, injectJoop, joopSignal } from 'joopjs/angular';
+bootstrapApplication(AppComponent, { providers: [...provideJoopAngular(joop)] });
+// in a component:  const joop = injectJoop(); balance = joopSignal(joop.wallet.balance$());
+```
+
+`joopjs/angular` (Angular 17+) provides real DI:
+- `JOOP_INSTANCE` — typed `InjectionToken<JoopInstance>`; `injectJoop()` is shorthand for `inject(JOOP_INSTANCE)`.
+- `provideJoopAngular(instance)` — bootstrap providers (replaces deprecated `provideJoop`).
+- `joopSignal(obs, opts?)` — bridges a `JoopObservable` to an Angular `signal`, auto-teardown via `DestroyRef`. Preferred over `fromJoop` and over manual subscribe.
+- `joopAuthGuard(opts?)` — functional `CanActivateFn` (`{ redirectTo?: string }`, default `/login`).
+- `joopAuthInterceptor(opts?)` — `HttpInterceptorFn` attaching the access token (`{ header?, scheme? }`).
+- Deprecated but still functional: string tokens, `provideJoop()`, `JoopModule`, `fromJoop()`. `toJoop()` is not deprecated.
+- New optional peers: `@angular/common`, `@angular/router`.
+
+---
+
+## TypeScript Types (prefix `Joop*`)
+
+All types are exported from `'joopjs'`:
+
+```ts
+// Auth
+JoopAuthUser, JoopAuthSession, JoopAuthToken
+
+// Banking
+JoopWallet, JoopWalletTransaction, JoopWalletTxnType
+JoopLoanAccount, JoopInstallment, JoopLoanAccountStatus
+JoopFxForward, JoopForwardType, JoopForwardStatus
+JoopLedgerAccount, JoopJournalEntry, JoopTrialBalance
+
+// Finance
+JoopMutualFund, JoopFundHolding, JoopSip, JoopSipStatus
+
+// Security
+JoopSanctionsEntity, JoopScreeningResult, JoopAmlAlert
+```

package/ai-rules/GEMINI.md

@@ -0,0 +1,183 @@
+# GEMINI.md — JoopJS SDK
+
+This file instructs Gemini CLI on how to generate code using the **joopjs** SDK.
+
+---
+
+## Package
+
+```bash
+npm install joopjs
+```
+
+**joopjs** is a framework-agnostic TypeScript SDK for enterprise financial applications. Works with React, Angular, Vue, Node.js, and plain TypeScript.
+
+---
+
+## Import Rules
+
+```ts
+// Main entry — everything
+import { JoopAuthService, JoopDigitalWalletService } from 'joopjs';
+
+// Sub-path imports (tree-shakeable, preferred)
+import { JoopGcmService }   from 'joopjs/encryption';
+import { JoopAuthService }  from 'joopjs/auth';
+import { JoopCacheService } from 'joopjs/cache';
+```
+
+Available sub-paths: `auth`, `encryption`, `banking`, `security`, `api`, `core`, `session`, `device`, `observability`, `theme`, `i18n`, `ui`, `forms`, `router`, `state`, `workers`, `workflow`, `sync`, `platform`, `cache`, `network`, `analytics`, `validation`, `utilities`, `pwa`, `native-bridge`, `deeplink`, `react`, `angular`, `vue`, `india`.
+
+Never import from internal paths (`joopjs/src/...`, `joopjs/dist/...`).
+
+`joopjs/core` exposes `globalSingleton`, `joopCopyCount`, and `silenceDuplicateCopyWarning`. In Module Federation micro-frontends, share joopjs as a singleton (`shared: { joopjs: { singleton: true } }`) so logger/config/event-bus state does not fragment across multiple loaded copies.
+
+---
+
+## Service Instantiation
+
+All services are plain classes — no DI framework required:
+
+```ts
+const wallet  = new JoopDigitalWalletService();
+const auth    = new JoopAuthService();
+const gcm     = new JoopGcmService();
+const loans   = new JoopLoanServicingService();
+```
+
+Create once per module and reuse as singletons.
+
+---
+
+## Reactive Observables
+
+joopjs uses its own `JoopSubject` — **not RxJS**:
+
+```ts
+// Subscribe — returns an unsubscribe function
+const unsub = service.event$().subscribe(value => {
+  console.log(value);
+});
+
+// Emit (only from inside a service or your own subject)
+subject.next(newValue);      // CORRECT
+subject.emit(newValue);      // WRONG — .emit() does not exist
+
+// Read current value (BehaviorSubject only)
+const current = behaviorSubject.getValue();
+
+// Unsubscribe
+unsub();                     // call the returned function
+// NOT .unsubscribe()        // wrong — does not exist
+```
+
+`next()` is error-isolated: if one subscriber throws, delivery to the other subscribers still proceeds. Route subscriber errors with `setSubjectErrorHandler(fn)` (default `console.error`).
+
+Do not use RxJS operators (`.pipe()`, `.map()`, etc.) — these are not RxJS Observables.
+
+---
+
+## Data Types
+
+| Concept | Type | Example |
+|---------|------|---------|
+| Money amount | `number` | `5000.50` |
+| Currency | `string` ISO-4217 | `'USD'`, `'AED'`, `'INR'` |
+| Timestamp | `number` epoch ms | `Date.now()` |
+| ID | `string` | `'u-001'` |
+
+Never use a Money class, BigDecimal, or `Date` objects.
+
+---
+
+## Error Handling
+
+All services throw standard `Error` on invalid input:
+
+```ts
+try {
+  const result = await service.doSomething(config);
+} catch (err) {
+  if (err instanceof Error) {
+    console.error(err.message);
+  }
+}
+```
+
+---
+
+## Key Services Quick Reference
+
+### Banking
+```ts
+import { JoopDigitalWalletService, JoopLoanServicingService } from 'joopjs';
+
+const wallet = new JoopDigitalWalletService();
+const w = wallet.createWallet('user-001', { currency: 'USD' });
+wallet.topUp(w.id, 500);
+wallet.pay(w.id, 50, 'merchant-id', 'Coffee');
+wallet.balance$().subscribe(({ walletId, balance }) => { /* update UI */ });
+
+const loans = new JoopLoanServicingService();
+const loan = loans.createLoan({ borrowerName: 'Alice', borrowerId: 'u-001', principalAmount: 10000, annualInterestRatePercent: 8, tenureMonths: 12, currency: 'USD' });
+loans.recordPayment(loan.id, loan.emiAmount);
+```
+
+### Auth
+```ts
+import { JoopAuthService } from 'joopjs/auth';
+
+const auth = new JoopAuthService();
+const session = await auth.login(email, password);
+auth.session$().subscribe(session => { /* null = logged out */ });
+await auth.logout(session.sessionId);
+```
+
+### Encryption
+```ts
+import { JoopGcmService } from 'joopjs/encryption';
+
+const gcm = new JoopGcmService();
+const key = await gcm.generateKey();
+const { ciphertext, iv } = await gcm.encrypt('sensitive data', key);
+const plain = await gcm.decrypt(ciphertext, key, iv);
+```
+
+### Security
+```ts
+import { JoopAmlService, JoopSanctionsScreeningService } from 'joopjs';
+
+const aml = new JoopAmlService();
+aml.addRule({ id: 'r1', name: 'Large cash', type: 'cash', threshold: 10000, currency: 'USD', action: 'flag', enabled: true });
+const alert = aml.checkTransaction({ id: 'tx1', amount: 15000, currency: 'USD', type: 'cash', userId: 'u-001', timestamp: Date.now() });
+
+const sanctions = new JoopSanctionsScreeningService();
+sanctions.loadList('ofac', entities);
+const result = sanctions.screen({ name: 'John Doe', country: 'US' });
+// result.status: 'clear' | 'hit' | 'review'
+```
+
+### Framework Integrations
+```tsx
+// React
+import { createJoopReact } from 'joopjs/react';
+const { JoopProvider, useJoopAuth, useJoopTheme } = createJoopReact(React);
+
+// Vue
+import { createJoopVue } from 'joopjs/vue';
+const { provideJoop, useJoopAuth } = createJoopVue(Vue);
+
+// Angular (17+ DI — adapter imports @angular/*; the core SDK never does)
+import { provideJoopAngular, injectJoop, joopSignal } from 'joopjs/angular';
+bootstrapApplication(AppComponent, { providers: [...provideJoopAngular(joop)] });
+// in a component:  const joop = injectJoop(); balance = joopSignal(joop.wallet.balance$());
+```
+
+`joopjs/angular` (Angular 17+) provides real DI:
+- `JOOP_INSTANCE` — typed `InjectionToken<JoopInstance>`; `injectJoop()` is shorthand for `inject(JOOP_INSTANCE)`.
+- `provideJoopAngular(instance)` — bootstrap providers (replaces deprecated `provideJoop`).
+- `joopSignal(obs, opts?)` — bridges a `JoopObservable` to an Angular `signal`, auto-teardown via `DestroyRef`. Preferred over `fromJoop` and over manual subscribe.
+- `joopAuthGuard(opts?)` — functional `CanActivateFn` (`{ redirectTo?: string }`, default `/login`).
+- `joopAuthInterceptor(opts?)` — `HttpInterceptorFn` attaching the access token (`{ header?, scheme? }`).
+- Deprecated but still functional: string tokens, `provideJoop()`, `JoopModule`, `fromJoop()`. `toJoop()` is not deprecated.
+- New optional peers: `@angular/common`, `@angular/router`.

package/dist/ai/index.js

@@ -1,6 +1,9 @@
 'use strict';
 
 // src/events/index.ts
+var _onListenerError = (error) => {
+  console.error("[joopjs] a subject subscriber threw during emission:", error);
+};
 var JoopSubject = class {
   _listeners = [];
   subscribe(listener) {
@@ -10,8 +13,13 @@ var JoopSubject = class {
     };
   }
   next(value) {
-    for (const listener of this._listeners) {
-      listener(value);
+    const listeners = this._listeners.slice();
+    for (const listener of listeners) {
+      try {
+        listener(value);
+      } catch (error) {
+        _onListenerError(error);
+      }
     }
   }
   asObservable() {
@@ -32,7 +40,11 @@ var JoopBehaviorSubject = class extends JoopSubject {
     super.next(value);
   }
   subscribe(listener) {
-    listener(this._value);
+    try {
+      listener(this._value);
+    } catch (error) {
+      _onListenerError(error);
+    }
     return super.subscribe(listener);
   }
   asObservable() {