joopjs 2.0.5 → 2.1.0

package/.claude/skills/observables.md

@@ -0,0 +1,270 @@
+# /observables — JoopJS Reactive Patterns
+
+> Author: Kundan Singh
+
+JoopJS has its own lightweight reactive primitives — `JoopSubject` and `JoopBehaviorSubject`. They are **not** RxJS Observables. Never use `.emit()`, `.pipe()`, or RxJS operators.
+
+---
+
+## Core API
+
+### JoopSubject — event stream (no initial value)
+
+```ts
+import { JoopSubject } from 'joopjs';
+
+const subject = new JoopSubject<number>();
+
+// Subscribe
+const unsub = subject.subscribe((value) => {
+  console.log('Got:', value);
+});
+
+// Emit
+subject.next(42);    // all subscribers receive 42
+
+// Unsubscribe
+unsub();
+
+// Complete (all subscribers removed)
+subject.complete();
+```
+
+### JoopBehaviorSubject — holds current value + emits to new subscribers immediately
+
+```ts
+import { JoopBehaviorSubject } from 'joopjs';
+
+const balance = new JoopBehaviorSubject<number>(0);  // initial value
+
+// New subscriber gets current value immediately
+balance.subscribe(v => console.log('Balance:', v));  // logs 0 right away
+
+balance.next(100);     // logs 100
+
+// Read current value synchronously
+const current = balance.getValue();  // 100
+
+// Check if completed
+const done = balance.isCompleted();
+```
+
+---
+
+## Subscribing to Service Streams
+
+Every JoopJS service exposes reactive streams for key state changes. Always use the returned `unsubscribe` function to avoid memory leaks.
+
+```ts
+import { JoopDigitalWalletService } from 'joopjs';
+const wallet = new JoopDigitalWalletService();
+
+// Subscribe to balance changes
+const unsub = wallet.balance$().subscribe(({ walletId, balance }) => {
+  updateUI(walletId, balance);
+});
+
+// On component/page destroy
+unsub();
+```
+
+### Common service streams
+
+```ts
+// Auth
+auth.session$().subscribe(session => { /* null when logged out */ });
+
+// Wallet
+wallet.balance$().subscribe(({ walletId, balance }) => { });
+
+// AML
+aml.alert$().subscribe(alert => { });
+
+// Fraud Detection
+fraud.alert$().subscribe(result => { });
+
+// Sanctions
+sanctions.hit$().subscribe(hit => { });  // only fires on non-clear results
+
+// Risk Engine
+risk.score$().subscribe(({ score, level }) => { });
+
+// KYC
+kyc.status$().subscribe(update => { });
+
+// MFA
+mfa.status$().subscribe(event => { });
+
+// Sessions
+sessions.expired$().subscribe(session => { });
+```
+
+---
+
+## Common Patterns
+
+### React — useEffect subscription
+
+```tsx
+import { useEffect, useState } from 'react';
+import { JoopDigitalWalletService } from 'joopjs';
+
+const wallet = new JoopDigitalWalletService();
+
+function BalanceDisplay({ walletId }: { walletId: string }) {
+  const [balance, setBalance] = useState(0);
+
+  useEffect(() => {
+    const unsub = wallet.balance$().subscribe(({ walletId: id, balance }) => {
+      if (id === walletId) setBalance(balance);
+    });
+    return unsub;   // cleanup on unmount
+  }, [walletId]);
+
+  return <div>{balance}</div>;
+}
+```
+
+### Angular — async pipe
+
+```ts
+import { Observable } from 'rxjs';   // only needed to bridge to Angular async pipe
+import { JoopDigitalWalletService } from 'joopjs';
+
+@Component({ template: `<div>{{ balance$ | async }}</div>` })
+export class BalanceComponent {
+  balance$ = new Observable<number>(observer => {
+    // bridge JoopSubject → RxJS Observable for async pipe
+    const unsub = wallet.balance$().subscribe(({ balance }) => observer.next(balance));
+    return () => unsub();
+  });
+}
+```
+
+### Vue — ref + onMounted/onUnmounted
+
+```ts
+import { ref, onMounted, onUnmounted } from 'vue';
+import { JoopDigitalWalletService } from 'joopjs';
+
+const wallet = new JoopDigitalWalletService();
+
+export function useWalletBalance(walletId: string) {
+  const balance = ref(0);
+  let unsub: () => void;
+
+  onMounted(() => {
+    unsub = wallet.balance$().subscribe(({ walletId: id, b }) => {
+      if (id === walletId) balance.value = b;
+    });
+  });
+
+  onUnmounted(() => unsub?.());
+  return { balance };
+}
+```
+
+### Vanilla TypeScript — manual lifecycle
+
+```ts
+const wallet = new JoopDigitalWalletService();
+const subscriptions: Array<() => void> = [];
+
+function init() {
+  subscriptions.push(
+    wallet.balance$().subscribe(upd => renderBalance(upd.balance))
+  );
+}
+
+function destroy() {
+  subscriptions.forEach(unsub => unsub());
+  subscriptions.length = 0;
+}
+```
+
+---
+
+## Creating Your Own Subjects
+
+```ts
+import { JoopSubject, JoopBehaviorSubject } from 'joopjs';
+
+class MyPaymentService {
+  private _status$ = new JoopBehaviorSubject<'idle' | 'processing' | 'done'>('idle');
+
+  status$() { return this._status$; }    // expose as read-only
+
+  async processPayment(amount: number) {
+    this._status$.next('processing');
+    await doPayment(amount);
+    this._status$.next('done');
+  }
+}
+```
+
+---
+
+## Error Isolation
+
+`JoopSubject.next()` and `JoopBehaviorSubject` replay (the immediate value sent to new subscribers) are **error-isolated**. `next()` snapshots its listener list and wraps each subscriber call in try/catch, so:
+
+- One subscriber that throws no longer aborts delivery to the others.
+- A `subscribe()` / `unsubscribe()` triggered mid-emission can't disturb the in-flight notification.
+
+Subscriber errors are routed to a handler instead of bubbling out of `next()`. By default the handler is `console.error`. Override it globally with `setSubjectErrorHandler`:
+
+```ts
+import { JoopSubject, setSubjectErrorHandler } from 'joopjs';
+
+// Route subscriber errors wherever you want (default: console.error)
+setSubjectErrorHandler((error) => {
+  errorReporter.captureException(error);
+});
+
+const subject = new JoopSubject<number>();
+subject.subscribe(() => { throw new Error('boom'); });  // handled, isolated
+subject.subscribe((v) => console.log('still delivered:', v));
+
+subject.next(1);   // logs 'still delivered: 1' — the throwing subscriber does not block this one
+```
+
+This is still **not** RxJS — `.subscribe()` returns an unsubscribe function and there are no operators.
+
+---
+
+## Critical Rules
+
+| Rule | Correct | Wrong |
+|------|---------|-------|
+| Emit values | `.next(value)` | `.emit(value)` |
+| Read current value | `.getValue()` | `.value` |
+| Stop listening | Call the returned `unsub()` function | `.unsubscribe()` (doesn't exist) |
+| Add listeners | `.subscribe(callback)` | `.addListener()` |
+| One-time listen | Subscribe, call `unsub()` inside the callback | `.once()` (doesn't exist) |
+| Merge/combine | Compose in application code | `.pipe()` (not available) |
+| Check completion | `.isCompleted()` | `.closed` |
+
+---
+
+## 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/security.md

@@ -0,0 +1,240 @@
+# /security — JoopJS Security Services
+
+> Author: Kundan Singh
+
+All security services are imported from `'joopjs'`. Instantiate as plain singletons.
+
+---
+
+## Sanctions Screening
+
+```ts
+import { JoopSanctionsScreeningService } from 'joopjs';
+const sanctions = new JoopSanctionsScreeningService();
+
+sanctions.loadList('ofac', [
+  { id: 'e-001', name: 'Kim Jong-un', aliases: ['Dear Leader', 'Supreme Leader'],
+    type: 'individual', lists: ['ofac', 'un'] },
+]);
+
+const result = sanctions.screen({ name: 'Kim Jong-un', country: 'KP' });
+// result.status: 'clear' | 'hit' | 'review'
+// result.matches[]: [{ entity, matchType, score, matchedOn }]
+// matchType: 'exact' | 'alias' | 'fuzzy'
+
+sanctions.disableList('eu');   sanctions.enableList('eu');
+sanctions.hit$().subscribe(hit => console.log('SANCTIONS HIT:', hit));  // fires only on non-clear
+
+// Screen with custom threshold (default 0.85)
+const strict = sanctions.screen({ name: 'John Smith' }, { threshold: 0.95 });
+```
+
+**Key types:** `JoopSanctionsEntity`, `JoopScreeningResult`, `JoopSanctionMatch`, `JoopSanctionsList`, `JoopSanctionMatchType`
+
+---
+
+## AML (Anti-Money Laundering)
+
+```ts
+import { JoopAmlService } from 'joopjs';
+const aml = new JoopAmlService();
+
+aml.addRule({ id: 'R01', name: 'Large Cash', type: 'threshold', threshold: 10000, currency: 'USD', action: 'flag', enabled: true });
+
+const tx = { id: 'TXN-001', amount: 15000, currency: 'USD', type: 'cash-deposit', userId: 'u-001', timestamp: Date.now() };
+const alert = aml.checkTransaction(tx);
+// alert: null (pass) | JoopAmlAlert { alertId, ruleId, severity, recommendation }
+
+aml.flag(tx.id, 'TXN-001', 'manual review required');
+aml.alert$().subscribe(alert => console.log('AML ALERT:', alert));   // reactive
+```
+
+---
+
+## Risk Engine
+
+```ts
+import { JoopRiskEngineService } from 'joopjs';
+const risk = new JoopRiskEngineService();
+
+risk.addFactor({ key: 'velocityScore', weight: 0.3, transform: (v: number) => Math.min(v / 10, 1) });
+risk.addFactor({ key: 'locationScore', weight: 0.2 });
+risk.addFactor({ key: 'deviceScore',   weight: 0.5 });
+
+const score = risk.evaluate({ velocityScore: 8, locationScore: 3, deviceScore: 7 });
+// score.total ∈ [0,1], score.level: 'low'|'medium'|'high'|'critical'
+
+risk.setThreshold('medium', 0.4);   // adjust thresholds
+risk.score$().subscribe(({ score, level }) => { });
+```
+
+---
+
+## Fraud Detection
+
+```ts
+import { JoopFraudDetectionService } from 'joopjs';
+const fraud = new JoopFraudDetectionService();
+
+fraud.addRule({ id: 'velocity', name: 'TX Velocity', condition: (ctx) => ctx.txnCount > 5, risk: 40 });
+fraud.addRule({ id: 'geo', name: 'Geo Anomaly', condition: (ctx) => ctx.countries.size > 3, risk: 60 });
+
+const result = fraud.assess({ txnCount: 10, countries: new Set(['US', 'NG', 'RU', 'CN']), amount: 5000 });
+// result.risk ∈ [0,100], result.level, result.triggeredRules[]
+
+fraud.alert$().subscribe(alert => console.log('FRAUD:', alert));
+```
+
+---
+
+## Identity Verification (KYC)
+
+```ts
+import { JoopIdentityVerificationService } from 'joopjs';
+const kyc = new JoopIdentityVerificationService();
+
+const submission = kyc.submit({ userId: 'u-001', documentType: 'passport', documentNumber: 'P123456', expiryDate: Date.now() + 730 * 86_400_000 });
+kyc.verify(submission.id, 'approved', { notes: 'Document verified' });
+const status = kyc.getStatus('u-001');
+// { verificationStatus: 'verified', riskLevel, kycLevel }
+kyc.status$().subscribe(update => { });
+```
+
+---
+
+## Behavioral Biometrics
+
+```ts
+import { JoopBehavioralBiometricsService } from 'joopjs';
+const bio = new JoopBehavioralBiometricsService();
+
+bio.startSession('u-001', 'session-1');
+bio.recordEvent('session-1', { type: 'keystroke', key: 'a', duration: 92, interval: 145 });
+bio.recordEvent('session-1', { type: 'mouse', x: 450, y: 300, velocity: 2.3 });
+bio.recordEvent('session-1', { type: 'swipe', direction: 'right', duration: 180, distance: 200 });
+
+const analysis = bio.analyzeSession('session-1');
+// analysis.anomalyScore ∈ [0,1], analysis.confidence, analysis.flags[]
+
+bio.setBaseline('u-001', { avgKeystrokeDuration: 90, avgMouseVelocity: 2.5 });
+bio.anomaly$().subscribe(({ sessionId, score, flags }) => { });
+```
+
+---
+
+## Threat Intelligence
+
+```ts
+import { JoopThreatIntelligenceService } from 'joopjs';
+const ti = new JoopThreatIntelligenceService();
+
+ti.addIndicator({ type: 'ip', value: '192.168.1.100', threat: 'botnet', severity: 'high', confidence: 0.9 });
+ti.addIndicator({ type: 'domain', value: 'evil.com', threat: 'phishing', severity: 'critical', confidence: 1.0 });
+
+const check = ti.checkIp('192.168.1.100');
+// { found: true, threat, severity, confidence } | { found: false }
+
+const block = ti.isBlocked('domain', 'evil.com');       // boolean
+ti.blockIndicator('ip', '10.0.0.1');
+ti.alert$().subscribe(threat => { });
+```
+
+---
+
+## Compliance Policy
+
+```ts
+import { JoopCompliancePolicyService } from 'joopjs';
+const compliance = new JoopCompliancePolicyService();
+
+compliance.addPolicy({ id: 'KYC-001', name: 'Customer Verification', jurisdiction: 'US', regulation: 'BSA', requirement: 'Verify all customers above $10k threshold', enabled: true });
+compliance.recordAudit({ policyId: 'KYC-001', action: 'check', outcome: 'pass', details: 'Customer ID verified', performedBy: 'system' });
+
+const status = compliance.getPolicyStatus('KYC-001');   // { policy, lastAudit, auditCount, passRate }
+const failures = compliance.getRecentFailures(7 * 86_400_000);
+compliance.violation$().subscribe(v => { });
+```
+
+---
+
+## Penetration Test Reporter
+
+```ts
+import { JoopPenTestReporterService } from 'joopjs';
+const pentest = new JoopPenTestReporterService();
+
+const engagement = pentest.createEngagement({ name: 'Q4 2025 Assessment', target: 'Banking API', scope: ['authentication', 'data validation'] });
+pentest.addFinding(engagement.id, { title: 'SQL Injection in login', severity: 'critical', cvss: 9.1, description: '...', recommendation: 'Use parameterized queries' });
+const report = pentest.generateReport(engagement.id);   // { executiveSummary, findings, riskMatrix }
+const stats = pentest.getStats(engagement.id);          // { critical, high, medium, low, info }
+```
+
+---
+
+## Vulnerability Tracker
+
+```ts
+import { JoopVulnerabilityTrackerService } from 'joopjs';
+const vulns = new JoopVulnerabilityTrackerService();
+
+vulns.add({ id: 'CVE-2025-001', title: 'Auth bypass', severity: 'high', cvss: 8.5, affectedComponent: 'login-service', status: 'open' });
+vulns.updateStatus('CVE-2025-001', 'patched', 'Applied fix in v1.2.3');
+const open = vulns.getOpen();                           // unresolved vulnerabilities
+const overdue = vulns.getOverdue(30 * 86_400_000);      // open longer than 30 days
+const stats = vulns.getStats();                         // { total, open, patched, bySeverity }
+```
+
+---
+
+## Security Audit Log
+
+```ts
+import { JoopSecurityAuditService } from 'joopjs';
+const audit = new JoopSecurityAuditService();
+
+audit.log({ userId: 'u-001', action: 'login', resource: 'auth', outcome: 'success', ip: '10.0.0.1' });
+audit.log({ userId: 'u-001', action: 'transfer', resource: 'wallet', outcome: 'success', amount: 1000 });
+const logs = audit.query({ userId: 'u-001', from: startTs, to: endTs });
+const failures = audit.getFailures('login', 24 * 3600_000);  // login failures in last 24h
+const suspicious = audit.getSuspiciousActivity('u-001');    // multiple failures, unusual hours
+```
+
+---
+
+## Data Masking
+
+```ts
+import { JoopDataMaskingService } from 'joopjs';
+const masking = new JoopDataMaskingService();
+
+const masked = masking.maskPan('4111111111111111');       // '**** **** **** 1111'
+const maskedEmail = masking.maskEmail('user@bank.com');  // 'u***@bank.com'
+const maskedPhone = masking.maskPhone('+1-555-123-4567'); // '+1-555-***-4567'
+masking.addRule({ field: 'ssn', pattern: /^\d{9}$/, mask: (v) => `***-**-${v.slice(-4)}` });
+const obj = masking.maskObject({ name: 'Alice', ssn: '123456789', pan: '4111111111111111' });
+```
+
+---
+
+## 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/setup.md

@@ -0,0 +1,196 @@
+# /setup — Install and Configure JoopJS
+
+> Author: Kundan Singh
+
+Use this skill when a developer needs to add joopjs to a project, bootstrap it, or configure it.
+
+---
+
+## Installation
+
+```bash
+npm install joopjs
+# or
+yarn add joopjs
+pnpm add joopjs
+```
+
+No peer dependencies are required for core features. React / Angular / Vue bindings are optional.
+
+---
+
+## Bootstrap
+
+### Plain TypeScript / Vanilla JS
+```ts
+import { createJoop } from 'joopjs';
+
+const joop = createJoop({
+  env: 'production',          // 'development' | 'staging' | 'production'
+  appId: 'my-banking-app',
+  version: '1.0.0',
+  locale: 'en',
+  currency: 'USD',
+});
+```
+
+### React
+```tsx
+// app.tsx
+import { createJoop } from 'joopjs';
+export const joop = createJoop({ env: 'production', appId: 'app' });
+
+// Use services as singletons
+import { JoopAuthService } from 'joopjs';
+const auth = new JoopAuthService();
+```
+
+### Angular (standalone)
+```ts
+// main.ts
+import { provideJoopAngular } from 'joopjs/angular';
+import { createJoop } from 'joopjs';
+
+bootstrapApplication(AppComponent, {
+  providers: [provideJoopAngular(createJoop({ env: 'production', appId: 'app' }))]
+});
+```
+
+Inject the instance with `injectJoop()` and bridge any JoopJS observable to an Angular signal with `joopSignal()` (auto-teardown via `DestroyRef`):
+```ts
+import { injectJoop, joopSignal } from 'joopjs/angular';
+
+const joop = injectJoop();
+const session = joopSignal(auth.session$());   // Angular signal, no manual unsubscribe
+```
+
+> Optional peers for the Angular adapter: `@angular/common` and `@angular/router` (only needed if you use the HTTP interceptor / guard). The core SDK never imports a framework.
+
+### Angular (NgModule — legacy)
+```ts
+// Deprecated but still functional — prefer provideJoopAngular() above.
+import { JoopModule } from 'joopjs/angular';
+import { createJoop } from 'joopjs';
+
+@NgModule({
+  imports: [JoopModule.forRoot(createJoop({ env: 'production', appId: 'app' }))]
+})
+export class AppModule {}
+```
+
+### Vue
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { JoopVuePlugin } from 'joopjs/vue';
+import { createJoop } from 'joopjs';
+
+createApp(App)
+  .use(JoopVuePlugin, createJoop({ env: 'production', appId: 'app' }))
+  .mount('#app');
+```
+
+---
+
+## Configuration Reference
+
+```ts
+interface JoopConfig {
+  env: 'development' | 'staging' | 'production';
+  appId: string;
+  version?: string;
+  locale?: string;           // default: 'en'
+  currency?: string;         // default: 'USD'
+  logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'none';
+  apiBaseUrl?: string;       // base URL for JoopHttpClient
+  timeout?: number;          // HTTP timeout ms, default 30000
+}
+```
+
+---
+
+## Service Instantiation Pattern
+
+All services are plain classes — no DI required:
+```ts
+import {
+  JoopDigitalWalletService,
+  JoopLoanServicingService,
+  JoopAmlService,
+} from 'joopjs';
+
+// Create once at module/app level (singletons)
+const wallet  = new JoopDigitalWalletService();
+const loans   = new JoopLoanServicingService();
+const aml     = new JoopAmlService();
+```
+
+---
+
+## Tree-Shakeable Sub-path Imports
+
+```ts
+import { JoopGcmService }  from 'joopjs/encryption';
+import { JoopAuthService } from 'joopjs/auth';
+import { JoopCacheService } from 'joopjs/cache';
+```
+
+Available sub-paths: `encryption`, `auth`, `api`, `core`, `session`, `banking`, `security`, `device`, `observability`, `theme`, `i18n`, `ui`, `native-bridge`, `deeplink`, `cache`, `network`, `analytics`, `validation`, `utilities`, `forms`, `pwa`, `router`, `ai`, `state`, `workers`, `workflow`, `sync`, `platform`, `react`, `angular`, `vue`, `india`.
+
+---
+
+## Environment-Specific Setup
+
+```ts
+// Use JoopConfigService for runtime config
+import { JoopConfigService } from 'joopjs';
+const config = new JoopConfigService();
+config.set('apiBaseUrl', 'https://api.mybank.com');
+config.set('currency', 'AED');
+
+// Use JoopEnvironmentService for env detection
+import { JoopEnvironmentService } from 'joopjs';
+const env = new JoopEnvironmentService();
+env.set('production', { debug: false, apiUrl: 'https://api.prod.com' });
+const profile = env.get('production'); // { debug, apiUrl }
+```
+
+---
+
+## Health Check
+
+```ts
+import { JoopHealthService } from 'joopjs';
+const health = new JoopHealthService();
+health.register('api', async () => {
+  const ok = await fetch('/health').then(r => r.ok);
+  return { name: 'api', healthy: ok };
+});
+const report = await health.check();
+// { healthy: true, checks: [{ name: 'api', healthy: true }] }
+```
+
+---
+
+## 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
+```