@africode/core 5.0.8 → 5.0.9

package/templates/starter-fintech/src/pages/api/auth.js

@@ -0,0 +1,45 @@
+function json(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+
+function isEmail(value) {
+  return typeof value === 'string' && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+
+export async function POST(request) {
+  const body = await request.json().catch(() => ({}));
+
+  if (!isEmail(body.email) || typeof body.password !== 'string' || body.password.length < 8) {
+    return json({
+      ok: false,
+      code: 'INVALID_CREDENTIALS',
+      error: 'Provide a valid email and a password with at least 8 characters.'
+    }, 400);
+  }
+
+  return json({
+    ok: true,
+    user: {
+      id: 'usr_demo_001',
+      email: body.email,
+      role: 'customer',
+      kycStatus: 'verified'
+    },
+    session: {
+      type: 'httpOnly-cookie',
+      sameSite: 'Strict',
+      expiresIn: 3600
+    }
+  });
+}
+
+export function GET() {
+  return json({
+    ok: true,
+    authenticated: false,
+    session: null
+  });
+}

package/templates/starter-fintech/src/pages/api/transfer.js

@@ -0,0 +1,65 @@
+function json(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+
+function normalizeAmount(value) {
+  const amount = Number(value);
+  return Number.isFinite(amount) ? amount : 0;
+}
+
+function validateTransfer(body) {
+  const amount = normalizeAmount(body.amount);
+
+  if (!body.recipient || typeof body.recipient !== 'string') {
+    return { ok: false, code: 'RECIPIENT_REQUIRED', error: 'Recipient is required.' };
+  }
+
+  if (amount <= 0) {
+    return { ok: false, code: 'AMOUNT_REQUIRED', error: 'Transfer amount must be greater than zero.' };
+  }
+
+  return { ok: true, amount };
+}
+
+export async function POST(request) {
+  const body = await request.json().catch(() => ({}));
+  const validation = validateTransfer(body);
+
+  if (!validation.ok) {
+    return json(validation, 400);
+  }
+
+  const dailyLimit = Number(process.env.AML_DAILY_LIMIT_TZS || 50000000);
+
+  if (validation.amount > dailyLimit) {
+    return json({
+      ok: false,
+      code: 'AML_LIMIT_EXCEEDED',
+      error: 'Transfer requires enhanced review before processing.',
+      compliance: {
+        checked: true,
+        dailyLimit,
+        decision: 'blocked'
+      }
+    }, 403);
+  }
+
+  return json({
+    ok: true,
+    transfer: {
+      id: `trf_${Date.now()}`,
+      recipient: body.recipient,
+      amount: validation.amount,
+      currency: body.currency || 'TZS',
+      status: 'pending_settlement'
+    },
+    compliance: {
+      checked: true,
+      decision: 'approved',
+      provider: process.env.PAYMENT_PROVIDER || 'sandbox'
+    }
+  }, 202);
+}

package/templates/starter-fintech/src/pages/api/wallet.js

@@ -0,0 +1,39 @@
+function json(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+
+export function GET() {
+  return json({
+    ok: true,
+    wallet: {
+      id: 'wal_demo_tzs',
+      currency: 'TZS',
+      availableBalance: 1250000,
+      ledgerBalance: 1285000,
+      dailyLimit: Number(process.env.AML_DAILY_LIMIT_TZS || 50000000)
+    },
+    transactions: [
+      {
+        id: 'txn_001',
+        type: 'credit',
+        amount: 500000,
+        currency: 'TZS',
+        status: 'settled',
+        counterparty: 'Merchant payout',
+        createdAt: '2026-07-07T08:00:00.000Z'
+      },
+      {
+        id: 'txn_002',
+        type: 'debit',
+        amount: 35000,
+        currency: 'TZS',
+        status: 'screened',
+        counterparty: 'Utility payment',
+        createdAt: '2026-07-07T09:15:00.000Z'
+      }
+    ]
+  });
+}

package/templates/starter-fintech/src/pages/api/webhooks/payment.js

@@ -0,0 +1,32 @@
+function json(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json' }
+  });
+}
+
+function getSignature(request) {
+  return request.headers.get('x-africode-signature') || request.headers.get('x-webhook-signature');
+}
+
+export async function POST(request) {
+  const signature = getSignature(request);
+  const expected = process.env.WEBHOOK_SIGNING_SECRET || 'whsec_mock_africode_fintech';
+
+  if (signature !== expected) {
+    return json({
+      ok: false,
+      code: 'INVALID_SIGNATURE',
+      error: 'Webhook signature could not be verified.'
+    }, 401);
+  }
+
+  const event = await request.json().catch(() => ({}));
+
+  return json({
+    ok: true,
+    received: true,
+    eventType: event.type || 'payment.sandbox',
+    transactionId: event.transactionId || null
+  });
+}

package/templates/starter-fintech/src/pages/index.html

@@ -0,0 +1,169 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>AfriCode Fintech Starter</title>
+  <script type="importmap">
+  {
+    "imports": {
+      "africode": "/node_modules/@africode/core/core/sdk-browser.js",
+      "africode/components": "/node_modules/@africode/core/components/index.js"
+    }
+  }
+  </script>
+  <link rel="stylesheet" href="/node_modules/@africode/core/styles/africanity.css" />
+  <link rel="stylesheet" href="/styles/main.css" />
+  <script type="module" src="/node_modules/@africode/core/core/sdk-browser.js"></script>
+</head>
+<body>
+  <main class="app-shell">
+    <section class="topbar">
+      <div class="brand">
+        <span class="eyebrow">AfriCode Fintech Starter</span>
+        <h1>Secure wallet operations</h1>
+      </div>
+      <div class="actions">
+        <button class="button" id="theme-toggle" type="button">Toggle theme</button>
+        <button class="button primary" id="auth-demo" type="button">Run auth check</button>
+      </div>
+    </section>
+
+    <section class="grid">
+      <div>
+        <div class="metrics">
+          <article class="metric">
+            <span class="label">Available balance</span>
+            <strong class="value" id="available-balance">Loading</strong>
+            <span class="status good" id="wallet-status">Fetching wallet</span>
+          </article>
+          <article class="metric">
+            <span class="label">Ledger balance</span>
+            <strong class="value" id="ledger-balance">Loading</strong>
+            <span class="status">Sandbox ledger</span>
+          </article>
+          <article class="metric">
+            <span class="label">Daily limit</span>
+            <strong class="value" id="daily-limit">Loading</strong>
+            <span class="status warn">AML guarded</span>
+          </article>
+        </div>
+
+        <article class="ledger">
+          <h2>Transaction ledger</h2>
+          <div class="ledger-list" id="ledger-list"></div>
+        </article>
+      </div>
+
+      <aside class="form-panel">
+        <section class="panel">
+          <h2>Transfer simulation</h2>
+          <form class="form-grid" id="transfer-form">
+            <label>
+              Recipient
+              <input name="recipient" value="merchant_demo" autocomplete="off" />
+            </label>
+            <label>
+              Amount
+              <input name="amount" type="number" min="1" value="25000" />
+            </label>
+            <button class="button primary" type="submit">Submit transfer</button>
+          </form>
+        </section>
+
+        <section class="panel">
+          <h2>Webhook verification</h2>
+          <button class="button" id="webhook-demo" type="button">Simulate payment webhook</button>
+        </section>
+
+        <div class="notice" id="notice">Ready to call the scaffolded API routes.</div>
+      </aside>
+    </section>
+  </main>
+
+  <script type="module">
+    const formatTZS = (value) => 'TZS ' + Number(value || 0).toLocaleString('en-US');
+    const notice = document.querySelector('#notice');
+
+    function setNotice(message, type = '') {
+      notice.className = type ? 'notice ' + type : 'notice';
+      notice.textContent = message;
+    }
+
+    async function loadWallet() {
+      const response = await fetch('/api/wallet');
+      const data = await response.json();
+
+      document.querySelector('#available-balance').textContent = formatTZS(data.wallet.availableBalance);
+      document.querySelector('#ledger-balance').textContent = formatTZS(data.wallet.ledgerBalance);
+      document.querySelector('#daily-limit').textContent = formatTZS(data.wallet.dailyLimit);
+      document.querySelector('#wallet-status').textContent = 'Wallet ready';
+      const ledgerList = document.querySelector('#ledger-list');
+      ledgerList.replaceChildren(...data.transactions.map((tx) => {
+        const row = document.createElement('div');
+        const details = document.createElement('div');
+        const counterparty = document.createElement('strong');
+        const status = document.createElement('div');
+        const amount = document.createElement('span');
+
+        row.className = 'ledger-row';
+        status.className = 'status';
+        amount.className = 'amount';
+        counterparty.textContent = tx.counterparty;
+        status.textContent = tx.status;
+        amount.textContent = formatTZS(tx.amount);
+
+        details.append(counterparty, status);
+        row.append(details, amount);
+        return row;
+      }));
+    }
+
+    document.querySelector('#theme-toggle').addEventListener('click', () => {
+      const root = document.documentElement;
+      root.dataset.theme = root.dataset.theme === 'dark' ? 'light' : 'dark';
+    });
+
+    document.querySelector('#auth-demo').addEventListener('click', async () => {
+      const response = await fetch('/api/auth', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email: 'demo@africode.dev', password: 'sandbox-pass' })
+      });
+      const data = await response.json();
+      setNotice(data.ok ? 'Authenticated demo user with ' + data.user.kycStatus + ' KYC.' : data.error, data.ok ? 'success' : 'error');
+    });
+
+    document.querySelector('#transfer-form').addEventListener('submit', async (event) => {
+      event.preventDefault();
+      const form = new FormData(event.currentTarget);
+      const response = await fetch('/api/transfer', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          recipient: form.get('recipient'),
+          amount: Number(form.get('amount')),
+          currency: 'TZS'
+        })
+      });
+      const data = await response.json();
+      setNotice(data.ok ? 'Transfer ' + data.transfer.id + ' is ' + data.transfer.status + '.' : data.error, data.ok ? 'success' : 'error');
+    });
+
+    document.querySelector('#webhook-demo').addEventListener('click', async () => {
+      const response = await fetch('/api/webhooks/payment', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-africode-signature': 'whsec_mock_africode_fintech'
+        },
+        body: JSON.stringify({ type: 'payment.succeeded', transactionId: 'txn_demo' })
+      });
+      const data = await response.json();
+      setNotice(data.ok ? 'Webhook accepted for ' + data.transactionId + '.' : data.error, data.ok ? 'success' : 'error');
+    });
+
+    loadWallet().catch(() => setNotice('Wallet API is unavailable.', 'error'));
+  </script>
+</body>
+</html>

package/templates/starter-fintech/src/pages/index.js

@@ -0,0 +1,161 @@
+import { html, Layout } from '@africode/core';
+
+export function loader() {
+  return { title: 'AfriCode Fintech Starter' };
+}
+
+export default function HomePage({ data }) {
+  return Layout({
+    title: data?.title || 'AfriCode Fintech Starter',
+    children: html`
+      <main class="app-shell">
+        <section class="topbar">
+          <div class="brand">
+            <span class="eyebrow">AfriCode Fintech Starter</span>
+            <h1>Secure wallet operations</h1>
+          </div>
+          <div class="actions">
+            <button class="button" id="theme-toggle" type="button">Toggle theme</button>
+            <button class="button primary" id="auth-demo" type="button">Run auth check</button>
+          </div>
+        </section>
+
+        <section class="grid">
+          <div>
+            <div class="metrics">
+              <article class="metric">
+                <span class="label">Available balance</span>
+                <strong class="value" id="available-balance">Loading</strong>
+                <span class="status good" id="wallet-status">Fetching wallet</span>
+              </article>
+              <article class="metric">
+                <span class="label">Ledger balance</span>
+                <strong class="value" id="ledger-balance">Loading</strong>
+                <span class="status">Sandbox ledger</span>
+              </article>
+              <article class="metric">
+                <span class="label">Daily limit</span>
+                <strong class="value" id="daily-limit">Loading</strong>
+                <span class="status warn">AML guarded</span>
+              </article>
+            </div>
+
+            <article class="ledger">
+              <h2>Transaction ledger</h2>
+              <div class="ledger-list" id="ledger-list"></div>
+            </article>
+          </div>
+
+          <aside class="form-panel">
+            <section class="panel">
+              <h2>Transfer simulation</h2>
+              <form class="form-grid" id="transfer-form">
+                <label>
+                  Recipient
+                  <input name="recipient" value="merchant_demo" autocomplete="off" />
+                </label>
+                <label>
+                  Amount
+                  <input name="amount" type="number" min="1" value="25000" />
+                </label>
+                <button class="button primary" type="submit">Submit transfer</button>
+              </form>
+            </section>
+
+            <section class="panel">
+              <h2>Webhook verification</h2>
+              <button class="button" id="webhook-demo" type="button">Simulate payment webhook</button>
+            </section>
+
+            <div class="notice" id="notice">Ready to call the scaffolded API routes.</div>
+          </aside>
+        </section>
+      </main>
+
+      <script type="module">
+        const formatTZS = (value) => 'TZS ' + Number(value || 0).toLocaleString('en-US');
+        const notice = document.querySelector('#notice');
+
+        function setNotice(message, type = '') {
+          notice.className = type ? 'notice ' + type : 'notice';
+          notice.textContent = message;
+        }
+
+        async function loadWallet() {
+          const response = await fetch('/api/wallet');
+          const data = await response.json();
+
+          document.querySelector('#available-balance').textContent = formatTZS(data.wallet.availableBalance);
+          document.querySelector('#ledger-balance').textContent = formatTZS(data.wallet.ledgerBalance);
+          document.querySelector('#daily-limit').textContent = formatTZS(data.wallet.dailyLimit);
+          document.querySelector('#wallet-status').textContent = 'Wallet ready';
+          const ledgerList = document.querySelector('#ledger-list');
+          ledgerList.replaceChildren(...data.transactions.map((tx) => {
+            const row = document.createElement('div');
+            const details = document.createElement('div');
+            const counterparty = document.createElement('strong');
+            const status = document.createElement('div');
+            const amount = document.createElement('span');
+
+            row.className = 'ledger-row';
+            status.className = 'status';
+            amount.className = 'amount';
+            counterparty.textContent = tx.counterparty;
+            status.textContent = tx.status;
+            amount.textContent = formatTZS(tx.amount);
+
+            details.append(counterparty, status);
+            row.append(details, amount);
+            return row;
+          }));
+        }
+
+        document.querySelector('#theme-toggle').addEventListener('click', () => {
+          const root = document.documentElement;
+          root.dataset.theme = root.dataset.theme === 'dark' ? 'light' : 'dark';
+        });
+
+        document.querySelector('#auth-demo').addEventListener('click', async () => {
+          const response = await fetch('/api/auth', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ email: 'demo@africode.dev', password: 'sandbox-pass' })
+          });
+          const data = await response.json();
+          setNotice(data.ok ? 'Authenticated demo user with ' + data.user.kycStatus + ' KYC.' : data.error, data.ok ? 'success' : 'error');
+        });
+
+        document.querySelector('#transfer-form').addEventListener('submit', async (event) => {
+          event.preventDefault();
+          const form = new FormData(event.currentTarget);
+          const response = await fetch('/api/transfer', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+              recipient: form.get('recipient'),
+              amount: Number(form.get('amount')),
+              currency: 'TZS'
+            })
+          });
+          const data = await response.json();
+          setNotice(data.ok ? 'Transfer ' + data.transfer.id + ' is ' + data.transfer.status + '.' : data.error, data.ok ? 'success' : 'error');
+        });
+
+        document.querySelector('#webhook-demo').addEventListener('click', async () => {
+          const response = await fetch('/api/webhooks/payment', {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'x-africode-signature': 'whsec_mock_africode_fintech'
+            },
+            body: JSON.stringify({ type: 'payment.succeeded', transactionId: 'txn_demo' })
+          });
+          const data = await response.json();
+          setNotice(data.ok ? 'Webhook accepted for ' + data.transactionId + '.' : data.error, data.ok ? 'success' : 'error');
+        });
+
+        loadWallet().catch(() => setNotice('Wallet API is unavailable.', 'error'));
+      </script>
+    `
+  });
+}