@africode/core 5.0.0 → 5.0.2

package/core/html.d.ts

@@ -1,116 +1,30 @@
-/**
+/**
  * AfriCode HTML Template Engine - TypeScript Definitions
  * JSX-free template literal engine
  */
 
-/**
- * HTML template tag function
- * Safely renders template literals as HTML strings
- * 
- * Usage:
- * ```ts
- * const name = 'Alice';
- * const result = html`<h1>Hello ${name}</h1>`;
- * ```
- * 
- * @param strings - Template string parts
- * @param values - Interpolated values
- * @returns Rendered HTML string
- */
-export function html(
-  strings: TemplateStringsArray,
-  ...values: any[]
-): string;
-
-/**
- * Render options
- */
-export interface RenderOptions {
-  /** Escape HTML special characters */
-  escape?: boolean;
-  /** Keep falsy values as string */
-  keepFalsy?: boolean;
-  /** Custom serializer */
-  serializer?: (value: any) => string;
+export class RawHtml {
+  constructor(value: string);
+  toString(): string;
+  valueOf(): string;
 }
 
 /**
- * Safe HTML rendering with custom options
+ * HTML template tag function.
+ * Returns a RawHtml wrapper so callers can opt into trusted output.
  */
-export function renderHtml(
+export function html(
   strings: TemplateStringsArray,
-  values: any[],
-  options?: RenderOptions
-): string;
+  ...values: any[]
+): RawHtml;
 
-/**
- * Layout component props
- */
 export interface LayoutProps {
-  /** Use vertical layout (default: horizontal) */
-  vertical?: boolean;
-  /** Spacing between items (px) */
-  gap?: number;
-  /** Vertical alignment */
-  align?: 'start' | 'center' | 'end' | 'stretch';
-  /** Horizontal justification */
-  justify?: 'start' | 'center' | 'end' | 'between' | 'around';
-  /** Additional CSS classes */
-  class?: string;
-  /** Inline styles */
-  style?: Record<string, string>;
+  title?: string;
+  meta?: string;
+  stylesheet?: string | false;
+  children?: RawHtml | string;
 }
 
-/**
- * Layout component class
- */
-export class Layout {
-  constructor(props?: LayoutProps);
-  
-  /**
-   * Add child element or text
-   */
-  addChild(child: HTMLElement | string): this;
-  
-  /**
-   * Render to HTML element
-   */
-  render(): HTMLElement;
-  
-  /**
-   * Get HTML string representation
-   */
-  toString(): string;
-}
-
-/**
- * Flex layout shorthand
- */
-export function flex(
-  options?: LayoutProps
-): HTMLElement;
-
-/**
- * Grid layout shorthand
- */
-export function grid(
-  columnCount: number,
-  gap?: number
-): HTMLElement;
-
-/**
- * Create safe text node
- */
-export function text(content: string): string;
-
-/**
- * Escape HTML entities
- */
-export function escape(str: string): string;
-
-/**
- * Unescape HTML entities
- */
-export function unescape(str: string): string;
+export function Layout(props?: LayoutProps): RawHtml;
 
 export default html;

package/core/html.js

@@ -1,160 +1,84 @@
 /**
  * AfriCode HTML Template Engine
- * 
- * Provides the `html` tagged template literal for writing markup in JavaScript.
- * This is a lightweight, zero-compile template system (JSX alternative).
- * 
+ * Phase 2: Defined Rendering System
+ *
  * @module core/html
  */
 
-/**
- * RawHtml wrapper class
- * Marks HTML content as safe and prevents escaping when interpolated
- * 
- * @class RawHtml
- * @param {string} content - The raw HTML content
- */
 export class RawHtml {
-  constructor(content) {
-    this.content = content;
+  constructor(value) {
+    this.value = value;
+    this.__type = 'RawHtml';
+    Object.freeze(this);
   }
 
   toString() {
-    return this.content;
+    return this.value;
   }
 
   valueOf() {
-    return this.content;
+    return this.value;
   }
 }
 
-/**
- * Escape HTML special characters to prevent XSS
- * 
- * @param {any} str - Value to escape
- * @returns {string} Escaped string
- */
-function escapeHtml(str) {
-  if (typeof str !== 'string') {return str;}
-  
-  const map = {
-    '&': '&',
-    '<': '&lt;',
-    '>': '&gt;',
-    '"': '&quot;',
-    "'": '&#039;'
-  };
-  
-  return str.replace(/[&<>"']/g, char => map[char]);
+// 🔒 Escape unsafe values
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
 }
 
-/**
- * Safely interpolate a value into HTML
- * - If RawHtml: insert as raw markup
- * - If array: recursively process and join
- * - If null/undefined/false: render empty string
- * - Otherwise: escape as text
- * 
- * @param {any} value - Value to interpolate
- * @returns {string}
- */
-function interpolateValue(value) {
-  // RawHtml: insert as raw markup (safe for nested templates)
-  if (value instanceof RawHtml) {
-    return value.toString();
-  }
-  
-  // Arrays: recursively process and join
-  if (Array.isArray(value)) {
-    return value.map(v => interpolateValue(v)).join('');
-  }
-  
-  // Falsy values: render empty string
-  if (value === null || value === undefined || value === false) {
-    return '';
-  }
-  
-  // Functions: convert to string (for component functions, better to call them first)
-  if (typeof value === 'function') {
-    return escapeHtml(String(value));
-  }
-  
-  // Everything else: escape as text
-  return escapeHtml(String(value));
-}
+// 🧠 Main rendering function
+export const html = (strings, ...values) => {
+  let result = "";
 
-/**
- * Tagged template literal for HTML
- * Safely handles nested templates, arrays, and text escaping.
- * 
- * Returns a RawHtml wrapper so nested templates aren't double-escaped.
- * 
- * @param {TemplateStringsArray} strings 
- * @param  {...any} values 
- * @returns {RawHtml}
- * 
- * @example
- * // Nested templates (no escaping of markup)
- * const button = html`<af-button>Click</af-button>`;
- * const page = html`<div>${button}</div>`;
- * // Output: <div><af-button>Click</af-button></div>
- * 
- * @example
- * // Plain text (escaped for safety)
- * const user = html`<p>${userInput}</p>`;
- * // If userInput = "<script>alert('xss')</script>"
- * // Output: <p>&lt;script&gt;alert('xss')&lt;/script&gt;</p>
- * 
- * @example
- * // Arrays of templates
- * const items = [html`<li>Item 1</li>`, html`<li>Item 2</li>`];
- * const list = html`<ul>${items}</ul>`;
- * // Output: <ul><li>Item 1</li><li>Item 2</li></ul>
- */
-export function html(strings, ...values) {
-    let result = '';
+  for (let i = 0; i < strings.length; i++) {
+    result += strings[i];
 
-    for (let i = 0; i < values.length; i++) {
-        result += strings[i];
-        result += interpolateValue(values[i]);
+    if (i < values.length) {
+      result += interpolateValue(values[i]);
     }
+  }
 
-    result += strings[strings.length - 1];
-    
-    // Return as RawHtml so nested html() calls aren't escaped
-    return new RawHtml(result);
-}
+  return new RawHtml(result);
+};
 
-/**
- * Standard Root Layout
- * Similar to Next.js layout.js concept
- * 
- * @param {Object} options
- * @param {string} options.title - Page title
- * @param {string} options.meta - Meta tags
- * @param {RawHtml|string} options.children - Page content
- * @returns {RawHtml}
- */
-export function Layout({ title = 'AfriCode App', meta = '', children }) {
-    return html`<!DOCTYPE html>
+export function Layout({ title = 'AfriCode App', meta = '', stylesheet = '/styles/africanity.css', children } = {}) {
+  return html`<!DOCTYPE html>
 <html lang="en">
 <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>${title}</title>
-    ${meta}
-    <link rel="stylesheet" href="/styles/africanity.css">
-    <script type="module" src="/core/sdk.js"></script>
-    <script type="module">
-        import { init } from '/core/sdk.js';
-        init();
-    </script>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+  ${meta}
+  ${stylesheet ? html`<link rel="stylesheet" href="${stylesheet}">` : ''}
+  <script type="module" src="/core/sdk.js"></script>
 </head>
 <body>
-    ${children}
+  ${children}
 </body>
 </html>`;
 }
 
+function interpolateValue(value) {
+  if (value instanceof RawHtml) {
+    return value.toString();
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(interpolateValue).join('');
+  }
 
-export default { html, Layout, RawHtml };
+  if (value === null || value === undefined || value === false) {
+    return '';
+  }
+
+  if (value === true) {
+    return 'true';
+  }
+
+  return escapeHtml(value);
+}

package/core/lipa-namba-journey.js

@@ -12,6 +12,7 @@
 
 import { z } from 'zod';
 import { EventEmitter } from 'events';
+import { frameworkLog } from './logging.js';
 
 export class LipaNambaJourney extends EventEmitter {
     constructor(config = {}) {
@@ -26,6 +27,8 @@ export class LipaNambaJourney extends EventEmitter {
             ...config
         };
 
+        this.sessions = new Map();
+
         // BoT Regulatory Limits (as of 2026)
         this.regulatoryLimits = {
             merchant: {
@@ -92,7 +95,8 @@ export class LipaNambaJourney extends EventEmitter {
             // Step 4: Payment Confirmation
             const confirmation = await this.confirmPayment(
                 initiation.paymentRequestId,
-                confirmationData
+                identification.customerId,
+                confirmationData.code
             );
             if (!confirmation.ok) {
                 throw new Error(`Confirmation failed: ${confirmation.error}`);
@@ -120,7 +124,7 @@ export class LipaNambaJourney extends EventEmitter {
         const schema = z.object({
             merchantId: z.string().min(1),
             customerPhone: z.string().regex(/^255\d{9}$/), // Tanzanian format
-            amount: z.number().positive().max(this.regulatoryLimits.merchant.perTransaction),
+            amount: z.number().positive().max(this.regulatoryLimits.merchant.daily),
             currency: z.string().default('TZS'),
             description: z.string().min(1).max(100),
             reference: z.string().optional(),
@@ -168,61 +172,15 @@ export class LipaNambaJourney extends EventEmitter {
         return {
             ok: true,
             paymentRequestId,
+            redirectUrl: `/pay/${paymentRequestId}`,
             sessionData,
             nextStep: 'IDENTIFY_CUSTOMER',
             expiresIn: this.regulatoryLimits.sessionTimeout / 1000
         };
     }
-        const schema = z.object({
-            merchantId: z.string().min(1),
-            customerPhone: z.string().regex(/^255\d{9}$/), // Tanzanian format
-            amount: z.number().positive(),
-            description: z.string().min(1),
-            reference: z.string().optional(),
-            callbackUrl: z.string().url().optional()
-        });
-
-        const validated = schema.parse(request);
 
-        // Check merchant limits
-        const merchantStatus = await this._checkMerchantLimits(
-            validated.merchantId,
-            validated.amount
-        );
-
-        if (!merchantStatus.ok) {
-            return {
-                ok: false,
-                error: merchantStatus.error,
-                code: 'MERCHANT_LIMIT_EXCEEDED'
-            };
-        }
-
-        // Generate payment request ID
-        const paymentRequestId = this._generatePaymentId();
-
-        // Store payment request
-        const paymentRequest = {
-            id: paymentRequestId,
-            merchantId: validated.merchantId,
-            customerPhone: validated.customerPhone,
-            amount: validated.amount,
-            description: validated.description,
-            reference: validated.reference || paymentRequestId,
-            status: 'INITIATED',
-            createdAt: new Date(),
-            expiresAt: new Date(Date.now() + 30 * 60 * 1000), // 30 min expiry
-            callbackUrl: validated.callbackUrl
-        };
-
-        await this._storePaymentRequest(paymentRequest);
-
-        return {
-            ok: true,
-            paymentRequestId,
-            redirectUrl: `https://lipa.example.com/pay/${paymentRequestId}`,
-            expiresIn: 30 * 60 // seconds
-        };
+    async initiatePayment(request) {
+        return this.initiateMerchantPayment(request);
     }
 
     /**
@@ -277,11 +235,22 @@ export class LipaNambaJourney extends EventEmitter {
         return {
             ok: true,
             customerId: nidaResult.nin,
-            customerName: nidaResult.customerName,
+            customerName: `${nidaResult.firstName} ${nidaResult.lastName}`,
+            customerData: {
+                nin: nidaResult.nin,
+                firstName: nidaResult.firstName,
+                lastName: nidaResult.lastName,
+                customerName: `${nidaResult.firstName} ${nidaResult.lastName}`
+            },
             nextStep: 'CONFIRM'
         };
     }
 
+    async verifyCustomerIdentity(paymentRequestId, customerIdentity) {
+        const identity = customerIdentity || {};
+        return this.identifyCustomer(paymentRequestId, identity.nin, identity.pin);
+    }
+
     /**
      * Step 3: AML Screening
      * Check customer against FIU suspicious persons list
@@ -413,7 +382,7 @@ export class LipaNambaJourney extends EventEmitter {
             };
 
         } catch (error) {
-            console.error('[Lipa Namba] Processing error:', error);
+            frameworkLog('error', '[Lipa Namba] Processing error:', error);
             return {
                 ok: false,
                 error: error.message,
@@ -489,12 +458,12 @@ export class LipaNambaJourney extends EventEmitter {
     async _checkMerchantLimits(merchantId, amount) {
         // Check daily limit
         const dailyTotal = await this._getMerchantDailyTotal(merchantId);
-        if (dailyTotal + amount > this.merchantLimits.daily) {
+        if (dailyTotal + amount > this.regulatoryLimits.merchant.daily) {
             return { ok: false, error: 'DAILY_LIMIT_EXCEEDED' };
         }
 
         // Check per-transaction limit
-        if (amount > this.merchantLimits.perTransaction) {
+        if (amount > this.regulatoryLimits.merchant.perTransaction) {
             return { ok: false, error: 'TRANSACTION_LIMIT_EXCEEDED' };
         }
 
@@ -503,11 +472,11 @@ export class LipaNambaJourney extends EventEmitter {
 
     async _checkCustomerLimits(customerId, amount) {
         const dailyTotal = await this._getCustomerDailyTotal(customerId);
-        if (dailyTotal + amount > this.customerLimits.daily) {
+        if (dailyTotal + amount > this.regulatoryLimits.customer.daily) {
             return { ok: false, error: 'DAILY_LIMIT_EXCEEDED' };
         }
 
-        if (amount > this.customerLimits.perTransaction) {
+        if (amount > this.regulatoryLimits.customer.perTransaction) {
             return { ok: false, error: 'TRANSACTION_LIMIT_EXCEEDED' };
         }
 
@@ -518,6 +487,42 @@ export class LipaNambaJourney extends EventEmitter {
         return `LN_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
     }
 
+    _generateSecurePaymentId() {
+        return this._generatePaymentId();
+    }
+
+    async _verifyMerchantCompliance(merchantId) {
+        if (!merchantId) {
+            return { ok: false, error: 'MERCHANT_NOT_FOUND' };
+        }
+
+        return { ok: true };
+    }
+
+    _handlePaymentInitiated(sessionData) {
+        return sessionData;
+    }
+
+    _handleCustomerIdentified(data) {
+        return data;
+    }
+
+    _handleAMLScreened(data) {
+        return data;
+    }
+
+    _handlePaymentConfirmed(data) {
+        return data;
+    }
+
+    _handlePaymentCompleted(data) {
+        return data;
+    }
+
+    _handlePaymentFailed(data) {
+        return data;
+    }
+
     async _verifyNIDA(nin, pin) {
         // Implementation calls NIDA CIG
         // For now, return mock
@@ -531,16 +536,22 @@ export class LipaNambaJourney extends EventEmitter {
     }
 
     async _storePaymentRequest(request) {
-        // Store in database
+        this.sessions.set(request.id, { ...request });
+    }
+
+    async _storePaymentSession(sessionData) {
+        this.sessions.set(sessionData.id, { ...sessionData });
     }
 
     async _getPaymentRequest(id) {
-        // Retrieve from database
-        return null;
+        return this.sessions.get(id) || null;
     }
 
     async _updatePaymentRequest(id, updates) {
-        // Update in database
+        const current = this.sessions.get(id);
+        if (current) {
+            this.sessions.set(id, { ...current, ...updates });
+        }
     }
 
     async _getMerchantDailyTotal(merchantId) {

package/core/logging.js

@@ -0,0 +1,14 @@
+const isTestEnvironment = () => Boolean(globalThis.__AFRICODE_TEST__ || globalThis.__AFRICODE_SILENT_LOGS__);
+
+export function frameworkLog(level, ...args) {
+  if (isTestEnvironment()) {
+    return;
+  }
+
+  const logger = console[level] || console.log;
+  logger.call(console, ...args);
+}
+
+export function isFrameworkLoggingMuted() {
+  return isTestEnvironment();
+}

package/core/middleware.js

@@ -0,0 +1,82 @@
+/**
+ * AfriCode Middleware System
+ * Core request interception pipeline
+ *
+ * @module core/middleware
+ */
+
+import { frameworkLog } from './logging.js';
+
+export class MiddlewareManager {
+  constructor() {
+    this.middlewares = [];
+  }
+
+  use(fn) {
+    if (typeof fn !== 'function') {
+      throw new Error('Middleware must be a function');
+    }
+
+    this.middlewares.push(fn);
+    return this;
+  }
+
+  async run(context) {
+    for (const mw of this.middlewares) {
+      const result = await mw(context);
+
+      if (result instanceof Response) {
+        return result;
+      }
+
+      // middleware can short-circuit request
+      if (result?.response) {
+        return result.response;
+      }
+
+      // allow mutation of context
+      if (result?.context) {
+        Object.assign(context, result.context);
+      }
+    }
+
+    return null;
+  }
+}
+
+/**
+ * Logging middleware - logs all requests
+ */
+export function loggerMiddleware() {
+  return async (ctx) => {
+    frameworkLog('log', `[AfriCode] ${ctx.req.method} ${ctx.pathname}`);
+    return {};
+  };
+}
+
+/**
+ * Opt-in auth guard middleware for protected routes.
+ */
+export function authMiddleware(options = {}) {
+  return async (ctx) => {
+    const {
+      protectedPaths = [],
+      authorize = () => false,
+      unauthorizedResponse = () => new Response('Unauthorized', { status: 401 })
+    } = options;
+
+    const isProtected = protectedPaths.some((path) => ctx.pathname.startsWith(path));
+
+    if (isProtected) {
+      const isAllowed = await authorize(ctx);
+
+      if (!isAllowed) {
+        return {
+          response: unauthorizedResponse(ctx)
+        };
+      }
+    }
+
+    return {};
+  };
+}