joopjs 2.0.5 → 2.0.6

package/ai-rules/AGENTS.md

@@ -0,0 +1,220 @@
+# 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/...`).
+
+---
+
+## 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
+```
+
+---
+
+## 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>;
+}
+```
+
+---
+
+## 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,169 @@
+# 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/...`).
+
+---
+
+## 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
+```
+
+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
+import { provideJoop } from 'joopjs/angular';
+bootstrapApplication(AppComponent, { providers: [provideJoop(joop)] });
+```

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "joopjs",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "Framework-agnostic JavaScript SDK for enterprise web applications. Works with React, Angular, Vue, and any JavaScript project.",
-  "author": {
-    "name": "Kundan Singh"
-  },
+  "keywords": [
+    "sdk",
+    "encryption",
+    "session",
+    "storage",
+    "auth",
+    "http",
+    "logger",
+    "aes",
+    "x25519",
+    "typescript"
+  ],
   "license": "MIT",
   "homepage": "https://kundan-leo.github.io/JoopJs/demo/",
   "repository": {
@@ -14,30 +23,9 @@
   "bugs": {
     "url": "https://github.com/kundan-leo/JoopJs/issues"
   },
-  "keywords": [
-    "sdk",
-    "banking",
-    "fintech",
-    "finance",
-    "encryption",
-    "auth",
-    "aml",
-    "sanctions",
-    "wallet",
-    "loan",
-    "typescript",
-    "react",
-    "angular",
-    "vue"
-  ],
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md"
-  ],
   "exports": {
     ".": {
       "import": "./dist/index.mjs",
@@ -94,6 +82,11 @@
       "require": "./dist/device/index.js",
       "types": "./dist/device/index.d.ts"
     },
+    "./dev": {
+      "import": "./dist/dev/index.mjs",
+      "require": "./dist/dev/index.js",
+      "types": "./dist/dev/index.d.ts"
+    },
     "./theme": {
       "import": "./dist/theme/index.mjs",
       "require": "./dist/theme/index.js",
@@ -210,6 +203,43 @@
       "types": "./dist/india/index.d.ts"
     }
   },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "ai-rules",
+    "scripts/setup-ai.mjs",
+    ".claude/skills/setup.md",
+    ".claude/skills/banking.md",
+    ".claude/skills/finance.md",
+    ".claude/skills/security.md",
+    ".claude/skills/auth.md",
+    ".claude/skills/encryption.md",
+    ".claude/skills/observables.md",
+    ".cursor/rules/joopjs.mdc",
+    ".windsurf/rules/joopjs.md",
+    ".github/copilot-instructions.md"
+  ],
+  "bin": {
+    "joopjs": "scripts/setup-ai.mjs"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist dist-playground",
+    "test": "vitest run",
+    "test:ui": "vitest --ui --open",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "playground": "vite playground/ --config playground/vite.config.ts",
+    "playground:build": "vite build playground/ --config playground/vite.config.ts",
+    "preflight": "node scripts/preflight.mjs",
+    "release:dry": "node scripts/release.mjs --dry-run",
+    "release:patch": "node scripts/release.mjs patch",
+    "release:minor": "node scripts/release.mjs minor",
+    "release:major": "node scripts/release.mjs major",
+    "release": "node scripts/release.mjs"
+  },
   "dependencies": {
     "@noble/ciphers": "^2.2.0",
     "@noble/curves": "^2.2.0",
@@ -222,14 +252,34 @@
     "vue": ">=3.0.0"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "@angular/core": { "optional": true },
-    "rxjs": { "optional": true },
-    "vue": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.0",
+    "@vitest/ui": "^2.1.0",
+    "fake-indexeddb": "^6.2.5",
+    "jsdom": "^29.1.1",
+    "rimraf": "^5.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.3.3",
+    "vite": "^5.4.0",
+    "vitest": "^2.1.0"
   },
   "engines": {
     "node": ">=18.0.0"
   },
-  "sideEffects": false
+  "author": {
+    "name": "Kundan Singh"
+  }
 }
-

package/scripts/setup-ai.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * joopjs setup-ai
+ *
+ * Copies AI assistant rules for joopjs into your project so that
+ * Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, and Codex
+ * all understand how to use the joopjs SDK correctly.
+ *
+ * Usage:
+ *   npx joopjs setup-ai           # copy rules (skip existing files)
+ *   npx joopjs setup-ai --force   # overwrite existing files
+ *   npx joopjs                    # show help
+ */
+
+import { copyFileSync, mkdirSync, existsSync } from 'fs';
+import { resolve, dirname, join, basename } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = resolve(__dirname, '..');
+const PROJECT_DIR = process.cwd();
+const FORCE = process.argv.includes('--force');
+const CMD = process.argv[2];
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+const ok   = msg => console.log(`  ✓  ${msg}`);
+const skip = msg => console.log(`  ·  skipped  ${msg}  (use --force to overwrite)`);
+const info = msg => console.log(`     ${msg}`);
+const hr   = ()  => console.log(`\n${'━'.repeat(52)}`);
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+function copyFile(src, dest) {
+  const label = dest.replace(PROJECT_DIR + '/', '').replace(PROJECT_DIR + '\\', '');
+  if (!existsSync(src)) return;
+  if (existsSync(dest) && !FORCE) { skip(label); return; }
+  ensureDir(dirname(dest));
+  copyFileSync(src, dest);
+  ok(label);
+}
+
+// ── help ─────────────────────────────────────────────────────────────────────
+function showHelp() {
+  console.log(`
+  joopjs — AI rules setup for joopjs
+
+  Usage:
+    npx joopjs setup-ai           Copy AI rules to your project
+    npx joopjs setup-ai --force   Overwrite existing rule files
+
+  What gets copied:
+    .claude/skills/joopjs-*.md    Claude Code skills (7 skills)
+    .cursor/rules/joopjs.mdc      Cursor rule
+    .windsurf/rules/joopjs.md     Windsurf Cascade rule
+    .github/copilot-instructions.md   GitHub Copilot instructions
+    GEMINI.md                     Gemini CLI instructions
+    AGENTS.md                     Codex / OpenAI Agents instructions
+`);
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+if (CMD !== 'setup-ai') {
+  showHelp();
+  process.exit(0);
+}
+
+hr();
+console.log('  joopjs — AI Rules Setup');
+if (FORCE) console.log('  MODE: --force (existing files will be overwritten)');
+hr();
+console.log('');
+
+// ── 1. Claude Code skills ─────────────────────────────────────────────────────
+console.log('  Claude Code skills:');
+const CONSUMER_SKILLS = ['setup', 'banking', 'finance', 'security', 'auth', 'encryption', 'observables'];
+for (const skill of CONSUMER_SKILLS) {
+  copyFile(
+    join(PACKAGE_DIR, '.claude', 'skills', `${skill}.md`),
+    join(PROJECT_DIR, '.claude', 'skills', `joopjs-${skill}.md`)
+  );
+}
+
+// ── 2. Cursor ─────────────────────────────────────────────────────────────────
+console.log('\n  Cursor:');
+copyFile(
+  join(PACKAGE_DIR, '.cursor', 'rules', 'joopjs.mdc'),
+  join(PROJECT_DIR, '.cursor', 'rules', 'joopjs.mdc')
+);
+
+// ── 3. Windsurf ───────────────────────────────────────────────────────────────
+console.log('\n  Windsurf Cascade:');
+copyFile(
+  join(PACKAGE_DIR, '.windsurf', 'rules', 'joopjs.md'),
+  join(PROJECT_DIR, '.windsurf', 'rules', 'joopjs.md')
+);
+
+// ── 4. GitHub Copilot ─────────────────────────────────────────────────────────
+console.log('\n  GitHub Copilot:');
+copyFile(
+  join(PACKAGE_DIR, '.github', 'copilot-instructions.md'),
+  join(PROJECT_DIR, '.github', 'copilot-instructions.md')
+);
+
+// ── 5. Gemini CLI ─────────────────────────────────────────────────────────────
+console.log('\n  Gemini CLI:');
+copyFile(
+  join(PACKAGE_DIR, 'ai-rules', 'GEMINI.md'),
+  join(PROJECT_DIR, 'GEMINI.md')
+);
+
+// ── 6. Codex / OpenAI Agents ─────────────────────────────────────────────────
+console.log('\n  Codex / OpenAI Agents:');
+copyFile(
+  join(PACKAGE_DIR, 'ai-rules', 'AGENTS.md'),
+  join(PROJECT_DIR, 'AGENTS.md')
+);
+
+// ── summary ───────────────────────────────────────────────────────────────────
+hr();
+console.log('  Done! Your AI tools now understand joopjs.\n');
+console.log('  Next steps:');
+console.log('  1. Claude Code — add skills to your CLAUDE.md:');
+console.log('');
+for (const skill of CONSUMER_SKILLS) {
+  console.log(`       | /joopjs-${skill.padEnd(11)} | JoopJS ${skill} guide |`);
+}
+console.log('');
+console.log('  2. Cursor / Windsurf — rules are auto-detected from their folders.');
+console.log('  3. Copilot / Gemini / Codex — files are at project root, ready to use.');
+hr();
+console.log('');