@webwaka/core 1.3.0

package/src/core/kyc/index.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { KYCEngine } from './index';
+
+const T1 = 'tenant_alpha';
+const T2 = 'tenant_beta';
+
+describe('CORE-12: Universal KYC/KYB Verification', () => {
+  let kycEngine: KYCEngine;
+
+  beforeEach(() => {
+    kycEngine = new KYCEngine();
+  });
+
+  it('should submit a verification request', () => {
+    const request = kycEngine.submitVerification(T1, 'user_1', 'NIN', '12345678901');
+    expect(request.status).toBe('pending');
+    expect(request.tenantId).toBe(T1);
+    expect(request.userId).toBe('user_1');
+    expect(request.documentType).toBe('NIN');
+    expect(request.id).toMatch(/^kyc_/);
+    expect(request.documentNumber).toBe('12345678901');
+  });
+
+  it('should verify a valid document', async () => {
+    const request = kycEngine.submitVerification(T1, 'user_1', 'BVN', '12345678901');
+    const processed = await kycEngine.processVerification(T1, request.id);
+
+    expect(processed.status).toBe('verified');
+    expect(processed.verifiedAt).toBeDefined();
+    expect(processed.rejectionReason).toBeUndefined();
+  });
+
+  it('should reject an invalid document', async () => {
+    const request = kycEngine.submitVerification(T1, 'user_1', 'NIN', '00012345678');
+    const processed = await kycEngine.processVerification(T1, request.id);
+
+    expect(processed.status).toBe('rejected');
+    expect(processed.rejectionReason).toBeDefined();
+    expect(processed.verifiedAt).toBeUndefined();
+  });
+
+  it('should retrieve user verification status scoped to tenant', () => {
+    kycEngine.submitVerification(T1, 'user_1', 'NIN', '12345678901');
+    kycEngine.submitVerification(T1, 'user_1', 'BVN', '12345678901');
+    kycEngine.submitVerification(T1, 'user_2', 'NIN', '98765432109');
+
+    const user1Status = kycEngine.getUserVerificationStatus(T1, 'user_1');
+    expect(user1Status).toHaveLength(2);
+
+    const user2Status = kycEngine.getUserVerificationStatus(T1, 'user_2');
+    expect(user2Status).toHaveLength(1);
+  });
+
+  it('should return empty array for user with no verifications', () => {
+    const status = kycEngine.getUserVerificationStatus(T1, 'unknown_user');
+    expect(status).toHaveLength(0);
+  });
+
+  it('should throw when processing a non-existent request', async () => {
+    await expect(
+      kycEngine.processVerification(T1, 'kyc_nonexistent')
+    ).rejects.toThrow('KYC request not found');
+  });
+
+  it('should throw when processing an already-processed request', async () => {
+    const request = kycEngine.submitVerification(T1, 'user_1', 'BVN', '12345678901');
+    await kycEngine.processVerification(T1, request.id);
+
+    await expect(
+      kycEngine.processVerification(T1, request.id)
+    ).rejects.toThrow('Request is already processed');
+  });
+
+  it('should support all valid document types', () => {
+    const types = ['NIN', 'BVN', 'PASSPORT', 'DRIVERS_LICENSE'] as const;
+    for (const type of types) {
+      const request = kycEngine.submitVerification(T1, 'user_x', type, '12345678901');
+      expect(request.documentType).toBe(type);
+    }
+  });
+
+  it('should assign unique IDs to each request', () => {
+    const r1 = kycEngine.submitVerification(T1, 'user_1', 'NIN', '11111111111');
+    const r2 = kycEngine.submitVerification(T1, 'user_1', 'BVN', '22222222222');
+    expect(r1.id).not.toBe(r2.id);
+  });
+
+  // ─── Cross-Tenant Isolation ───────────────────────────────────────────────
+
+  it('cross-tenant: getUserVerificationStatus for tenant_A user returns empty for tenant_B', () => {
+    kycEngine.submitVerification(T1, 'user_1', 'NIN', '12345678901');
+    kycEngine.submitVerification(T1, 'user_1', 'BVN', '12345678901');
+
+    const result = kycEngine.getUserVerificationStatus(T2, 'user_1');
+    expect(result).toHaveLength(0);
+  });
+
+  it('cross-tenant: tenant_B cannot process a KYC request belonging to tenant_A', async () => {
+    const request = kycEngine.submitVerification(T1, 'user_1', 'NIN', '12345678901');
+
+    await expect(
+      kycEngine.processVerification(T2, request.id)
+    ).rejects.toThrow('KYC request not found');
+  });
+});

package/src/core/kyc/index.ts

@@ -0,0 +1,86 @@
+/**
+ * CORE-12: Universal KYC/KYB Verification
+ * Blueprint Reference: Part 10.11 (Fintech), Part 10.3 (Transport)
+ *
+ * Centralized identity verification system with Nigeria-First integrations.
+ *
+ * Tenant Isolation: every mutating and querying method requires a tenantId.
+ * KYC requests are scoped per tenant — cross-tenant leakage is impossible by construction.
+ */
+
+export interface KYCRequest {
+  id: string;
+  tenantId: string;
+  userId: string;
+  documentType: 'NIN' | 'BVN' | 'PASSPORT' | 'DRIVERS_LICENSE';
+  documentNumber: string;
+  status: 'pending' | 'verified' | 'rejected';
+  verifiedAt?: Date;
+  rejectionReason?: string;
+}
+
+export class KYCEngine {
+  private requests: Map<string, KYCRequest> = new Map();
+
+  /**
+   * Submits a new KYC verification request, scoped to the tenant.
+   */
+  submitVerification(
+    tenantId: string,
+    userId: string,
+    documentType: 'NIN' | 'BVN' | 'PASSPORT' | 'DRIVERS_LICENSE',
+    documentNumber: string
+  ): KYCRequest {
+    const request: KYCRequest = {
+      id: `kyc_${crypto.randomUUID()}`,
+      tenantId,
+      userId,
+      documentType,
+      documentNumber,
+      status: 'pending',
+    };
+
+    this.requests.set(request.id, request);
+    return request;
+  }
+
+  /**
+   * Processes a verification request, scoped to the tenant.
+   * Mocks external API calls to NIMC (NIN) / NIBSS (BVN).
+   */
+  async processVerification(tenantId: string, requestId: string): Promise<KYCRequest> {
+    const request = this.requests.get(requestId);
+    if (!request || request.tenantId !== tenantId) {
+      throw new Error('KYC request not found');
+    }
+
+    if (request.status !== 'pending') {
+      throw new Error('Request is already processed');
+    }
+
+    const isValid = this.mockExternalVerification(request.documentNumber);
+
+    if (isValid) {
+      request.status = 'verified';
+      request.verifiedAt = new Date();
+    } else {
+      request.status = 'rejected';
+      request.rejectionReason = 'Document verification failed against national database';
+    }
+
+    return request;
+  }
+
+  /**
+   * Retrieves all verification requests for a user, scoped to the tenant.
+   */
+  getUserVerificationStatus(tenantId: string, userId: string): KYCRequest[] {
+    return Array.from(this.requests.values()).filter(
+      r => r.tenantId === tenantId && r.userId === userId
+    );
+  }
+
+  private mockExternalVerification(documentNumber: string): boolean {
+    return !documentNumber.startsWith('000');
+  }
+}

package/src/core/logger/index.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { logger } from './index';
+
+describe('Platform Logger', () => {
+  let consoleInfoSpy: any;
+  let consoleWarnSpy: any;
+  let consoleErrorSpy: any;
+  let consoleDebugSpy: any;
+
+  beforeEach(() => {
+    consoleInfoSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    consoleDebugSpy = vi.spyOn(console, 'debug').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleInfoSpy.mockRestore();
+    consoleWarnSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+    consoleDebugSpy.mockRestore();
+  });
+
+  it('logs info messages with context', () => {
+    logger.info('User logged in', { tenantId: 'tenant-123', userId: 'user-456' });
+
+    expect(consoleInfoSpy).toHaveBeenCalledOnce();
+    const call = consoleInfoSpy.mock.calls[0][0];
+    const entry = JSON.parse(call);
+
+    expect(entry.level).toBe('info');
+    expect(entry.message).toBe('User logged in');
+    expect(entry.context.tenantId).toBe('tenant-123');
+    expect(entry.context.userId).toBe('user-456');
+    expect(entry.timestamp).toBeDefined();
+  });
+
+  it('logs warning messages', () => {
+    logger.warn('API rate limit approaching', { tenantId: 'tenant-123' });
+
+    expect(consoleWarnSpy).toHaveBeenCalledOnce();
+    const call = consoleWarnSpy.mock.calls[0][0];
+    const entry = JSON.parse(call);
+
+    expect(entry.level).toBe('warn');
+    expect(entry.message).toBe('API rate limit approaching');
+    expect(entry.context.tenantId).toBe('tenant-123');
+  });
+
+  it('logs error messages with error object', () => {
+    const error = new Error('Database connection failed');
+    logger.error('Database operation failed', { tenantId: 'tenant-123' }, error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledOnce();
+    const call = consoleErrorSpy.mock.calls[0][0];
+    const entry = JSON.parse(call);
+
+    expect(entry.level).toBe('error');
+    expect(entry.message).toBe('Database operation failed');
+    expect(entry.context.tenantId).toBe('tenant-123');
+    expect(entry.error.message).toBe('Database connection failed');
+    expect(entry.error.stack).toBeDefined();
+  });
+
+  it('handles error as second parameter', () => {
+    const error = new Error('Connection timeout');
+    logger.error('Request failed', error);
+
+    expect(consoleErrorSpy).toHaveBeenCalledOnce();
+    const call = consoleErrorSpy.mock.calls[0][0];
+    const entry = JSON.parse(call);
+
+    expect(entry.level).toBe('error');
+    expect(entry.message).toBe('Request failed');
+    expect(entry.error.message).toBe('Connection timeout');
+  });
+
+  it('logs messages without context', () => {
+    logger.info('System started');
+
+    expect(consoleInfoSpy).toHaveBeenCalledOnce();
+    const call = consoleInfoSpy.mock.calls[0][0];
+    const entry = JSON.parse(call);
+
+    expect(entry.level).toBe('info');
+    expect(entry.message).toBe('System started');
+    expect(entry.context).toBeUndefined();
+  });
+
+  it('includes timestamp in all log entries', () => {
+    logger.info('Test message');
+
+    expect(consoleInfoSpy).toHaveBeenCalledOnce();
+    const call = consoleInfoSpy.mock.calls[0][0];
+    const entry = JSON.parse(call);
+
+    expect(entry.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+  });
+
+  it('never uses console.log (uses console.info/warn/error)', () => {
+    const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    logger.info('Test info');
+    logger.warn('Test warn');
+    logger.error('Test error');
+
+    expect(consoleLogSpy).not.toHaveBeenCalled();
+    consoleLogSpy.mockRestore();
+  });
+});

package/src/core/logger/index.ts

@@ -0,0 +1,127 @@
+/**
+ * Platform Logger Utility
+ * 
+ * Enforces the "Zero Console Logs" invariant across the WebWaka platform.
+ * All logging must go through this module, never direct console.log/warn/error calls.
+ * 
+ * Blueprint Reference: Part 9.3 — "Zero Console Logs: No console.log statements. Must use platform logger."
+ */
+
+export interface LogContext {
+  tenantId?: string;
+  userId?: string;
+  requestId?: string;
+  [key: string]: any;
+}
+
+export interface SerializedError {
+  message: string;
+  stack?: string;
+}
+
+export interface LogEntry {
+  timestamp: string;
+  level: 'info' | 'warn' | 'error' | 'debug';
+  message: string;
+  context?: LogContext;
+  error?: SerializedError;
+}
+
+/**
+ * Platform Logger
+ * 
+ * Usage:
+ *   logger.info("User logged in", { tenantId: "tenant-123", userId: "user-456" });
+ *   logger.warn("API rate limit approaching", { tenantId: "tenant-123" });
+ *   logger.error("Database connection failed", { tenantId: "tenant-123" }, error);
+ *   logger.debug("Cache hit", { tenantId: "tenant-123", key: "user-profile" });
+ */
+class PlatformLogger {
+  private isDevelopment = (globalThis as any).process?.env?.NODE_ENV === 'development';
+
+  /**
+   * Log informational message
+   */
+  info(message: string, context?: LogContext): void {
+    this.log('info', message, context);
+  }
+
+  /**
+   * Log warning message
+   */
+  warn(message: string, context?: LogContext): void {
+    this.log('warn', message, context);
+  }
+
+  /**
+   * Log error message
+   */
+  error(message: string, context?: LogContext | Error, error?: Error): void {
+    let ctx = context as LogContext | undefined;
+    let err = error;
+
+    // Handle overload: error(message, error) or error(message, context, error)
+    if (context instanceof Error) {
+      err = context;
+      ctx = undefined;
+    }
+
+    this.log('error', message, ctx, err);
+  }
+
+  /**
+   * Log debug message (development only)
+   */
+  debug(message: string, context?: LogContext): void {
+    if (this.isDevelopment) {
+      this.log('debug', message, context);
+    }
+  }
+
+  /**
+   * Internal logging implementation
+   */
+  private log(
+    level: 'info' | 'warn' | 'error' | 'debug',
+    message: string,
+    context?: LogContext,
+    error?: Error
+  ): void {
+    const serializedError: SerializedError | undefined = error !== undefined
+      ? { message: error.message, ...(error.stack !== undefined ? { stack: error.stack } : {}) }
+      : undefined;
+
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      message,
+      ...(context !== undefined ? { context } : {}),
+      ...(serializedError !== undefined ? { error: serializedError } : {}),
+    };
+
+    // In production, this would send to a logging service (e.g., Datadog, Sentry)
+    // For now, we output to stderr to avoid stdout pollution
+    if (typeof console !== 'undefined') {
+      const output = JSON.stringify(entry);
+
+      switch (level) {
+        case 'error':
+          console.error(output);
+          break;
+        case 'warn':
+          console.warn(output);
+          break;
+        case 'debug':
+          console.debug(output);
+          break;
+        case 'info':
+        default:
+          console.info(output);
+          break;
+      }
+    }
+  }
+}
+
+// Export singleton instance
+export const logger = new PlatformLogger();

package/src/core/notifications/index.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { NotificationService, NotificationPayload } from './index';
+
+// Mock fetch for external APIs
+global.fetch = vi.fn();
+
+describe('CORE-7: Unified Notification Service (Nigeria-First)', () => {
+  let notificationService: NotificationService;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+    notificationService = new NotificationService({
+      yournotifyApiKey: 'yn-key-123',
+      termiiApiKey: 'termii-key-456',
+      termiiSenderId: 'WebWakaTest'
+    });
+  });
+
+  it('should send email via Yournotify', async () => {
+    (global.fetch as any).mockResolvedValueOnce({ ok: true });
+
+    const payload: NotificationPayload = {
+      tenantId: 't1',
+      userId: 'u1',
+      type: 'email',
+      recipient: 'test@example.com',
+      subject: 'Test Email',
+      body: '<h1>Hello</h1>'
+    };
+
+    const result = await notificationService.dispatch(payload);
+
+    expect(result).toBe(true);
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+    
+    const fetchArgs = (global.fetch as any).mock.calls[0];
+    expect(fetchArgs[0]).toBe('https://api.yournotify.com/v1/campaigns/email');
+    expect(fetchArgs[1].headers['Authorization']).toBe('Bearer yn-key-123');
+    
+    const body = JSON.parse(fetchArgs[1].body);
+    expect(body.to).toBe('test@example.com');
+    expect(body.subject).toBe('Test Email');
+  });
+
+  it('should send SMS via Termii', async () => {
+    (global.fetch as any).mockResolvedValueOnce({ ok: true });
+
+    const payload: NotificationPayload = {
+      tenantId: 't1',
+      userId: 'u1',
+      type: 'sms',
+      recipient: '2348012345678',
+      body: 'Hello from WebWaka'
+    };
+
+    const result = await notificationService.dispatch(payload);
+
+    expect(result).toBe(true);
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+    
+    const fetchArgs = (global.fetch as any).mock.calls[0];
+    expect(fetchArgs[0]).toBe('https://api.ng.termii.com/api/sms/send');
+    
+    const body = JSON.parse(fetchArgs[1].body);
+    expect(body.to).toBe('2348012345678');
+    expect(body.from).toBe('WebWakaTest');
+    expect(body.api_key).toBe('termii-key-456');
+  });
+
+  it('should fail gracefully if API keys are missing', async () => {
+    const emptyService = new NotificationService({});
+    
+    const emailResult = await emptyService.dispatch({
+      tenantId: 't1', userId: 'u1', type: 'email', recipient: 'test@example.com', body: 'test'
+    });
+    
+    const smsResult = await emptyService.dispatch({
+      tenantId: 't1', userId: 'u1', type: 'sms', recipient: '2348012345678', body: 'test'
+    });
+
+    expect(emailResult).toBe(false);
+    expect(smsResult).toBe(false);
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+});

package/src/core/notifications/index.ts

@@ -0,0 +1,136 @@
+/**
+ * CORE-7: Unified Notification Service
+ * Blueprint Reference: Part 10.12 (Cross-Cutting Functional Modules)
+ * Blueprint Reference: Part 9.1 #5 (Nigeria First - Yournotify, Termii)
+ * 
+ * Implements event-driven email, SMS, and push notification dispatchers.
+ */
+
+import { logger } from '../logger';
+
+export interface NotificationPayload {
+  tenantId: string;
+  userId: string;
+  type: 'email' | 'sms' | 'push';
+  recipient: string; // email address, phone number, or device token
+  subject?: string;
+  body: string;
+}
+
+export interface NotificationConfig {
+  yournotifyApiKey?: string;
+  termiiApiKey?: string;
+  termiiSenderId?: string;
+}
+
+export class NotificationService {
+  private config: NotificationConfig;
+
+  constructor(config: NotificationConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Dispatches a notification based on its type.
+   */
+  async dispatch(payload: NotificationPayload): Promise<boolean> {
+    switch (payload.type) {
+      case 'email':
+        return this.sendEmail(payload);
+      case 'sms':
+        return this.sendSms(payload);
+      case 'push':
+        return this.sendPush(payload);
+      default:
+        throw new Error(`Unsupported notification type: ${payload.type}`);
+    }
+  }
+
+  /**
+   * Sends an email using Yournotify (Nigeria-First Service)
+   */
+  private async sendEmail(payload: NotificationPayload): Promise<boolean> {
+    if (!this.config.yournotifyApiKey) {
+      logger.warn('Yournotify API key missing. Email not sent.', {
+        tenantId: payload.tenantId,
+        recipient: payload.recipient,
+      });
+      return false;
+    }
+
+    try {
+      const response = await fetch('https://api.yournotify.com/v1/campaigns/email', {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.config.yournotifyApiKey}`,
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          to: payload.recipient,
+          subject: payload.subject || 'Notification from WebWaka',
+          html: payload.body
+        })
+      });
+
+      if (!response.ok) {
+        throw new Error(`Yournotify API error: ${response.statusText}`);
+      }
+
+      return true;
+    } catch (error) {
+      logger.error('Failed to send email via Yournotify', { tenantId: payload.tenantId }, error as Error);
+      return false;
+    }
+  }
+
+  /**
+   * Sends an SMS using Termii (Nigeria-First Service)
+   */
+  private async sendSms(payload: NotificationPayload): Promise<boolean> {
+    if (!this.config.termiiApiKey) {
+      logger.warn('Termii API key missing. SMS not sent.', {
+        tenantId: payload.tenantId,
+        recipient: payload.recipient,
+      });
+      return false;
+    }
+
+    try {
+      const response = await fetch('https://api.ng.termii.com/api/sms/send', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          to: payload.recipient,
+          from: this.config.termiiSenderId || 'WebWaka',
+          sms: payload.body,
+          type: 'plain',
+          channel: 'generic',
+          api_key: this.config.termiiApiKey
+        })
+      });
+
+      if (!response.ok) {
+        throw new Error(`Termii API error: ${response.statusText}`);
+      }
+
+      return true;
+    } catch (error) {
+      logger.error('Failed to send SMS via Termii', { tenantId: payload.tenantId }, error as Error);
+      return false;
+    }
+  }
+
+  /**
+   * Sends a push notification (Mock implementation for now)
+   */
+  private async sendPush(payload: NotificationPayload): Promise<boolean> {
+    logger.info('Push notification sent', {
+      tenantId: payload.tenantId,
+      recipient: payload.recipient,
+      body: payload.body,
+    });
+    return true;
+  }
+}