@africode/core 5.0.10 → 5.0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (222) hide show
  1. package/AGENTS.md +585 -585
  2. package/AGENT_INSTRUCTIONS.md +595 -595
  3. package/COMPONENT_SCHEMA.json +1826 -1800
  4. package/LICENSE +623 -623
  5. package/README.md +476 -476
  6. package/bin/africode.js +73 -73
  7. package/bin/cli.ts +82 -82
  8. package/bin/create-africode.js +220 -220
  9. package/bin/scaffold.ts +218 -218
  10. package/components/accordion.js +183 -183
  11. package/components/alert.js +131 -131
  12. package/components/auth-form.js +154 -154
  13. package/components/auth.js +172 -172
  14. package/components/avatar.js +117 -117
  15. package/components/badge.js +104 -104
  16. package/components/base.d.ts +139 -139
  17. package/components/base.js +234 -234
  18. package/components/breadcrumb.js +76 -72
  19. package/components/button.js +164 -164
  20. package/components/card.js +144 -137
  21. package/components/carousel.js +32 -32
  22. package/components/cart-drawer.js +28 -28
  23. package/components/code-block.js +20 -20
  24. package/components/contact-form.js +25 -25
  25. package/components/cookie-consent.js +23 -23
  26. package/components/cta-banner.js +38 -38
  27. package/components/cultural-card.js +243 -243
  28. package/components/dashboard-activity-list.js +103 -103
  29. package/components/dashboard-card.js +85 -85
  30. package/components/dashboard-metric.js +81 -81
  31. package/components/dashboard-shell.js +85 -85
  32. package/components/dashboard-topbar.js +84 -84
  33. package/components/divider.js +83 -83
  34. package/components/dropdown.js +171 -171
  35. package/components/error-boundary.js +155 -155
  36. package/components/faq-accordion.js +23 -23
  37. package/components/feature-grid.js +85 -85
  38. package/components/file-uploader.js +22 -22
  39. package/components/filter-bar.js +19 -19
  40. package/components/footer.js +113 -113
  41. package/components/form.js +131 -131
  42. package/components/gallery.js +22 -22
  43. package/components/hero.js +140 -138
  44. package/components/icon.js +36 -36
  45. package/components/index.js +128 -128
  46. package/components/input.js +252 -256
  47. package/components/kanga-card.js +185 -185
  48. package/components/kyc-upload.js +173 -173
  49. package/components/language-switcher.js +108 -108
  50. package/components/loader.js +80 -80
  51. package/components/modal.js +262 -262
  52. package/components/motion.js +84 -84
  53. package/components/nav-drawer.js +216 -216
  54. package/components/navbar.js +243 -236
  55. package/components/newsletter-signup.js +24 -24
  56. package/components/pagination.js +31 -31
  57. package/components/pattern-showcase.js +225 -225
  58. package/components/pricing-card.js +100 -100
  59. package/components/product-card.js +41 -41
  60. package/components/progress.js +132 -134
  61. package/components/react.js +111 -111
  62. package/components/search-box.js +24 -24
  63. package/components/section.js +54 -54
  64. package/components/select.js +321 -322
  65. package/components/sidebar.js +180 -180
  66. package/components/simple-chart.js +22 -22
  67. package/components/skeleton.js +85 -85
  68. package/components/stepper.js +28 -28
  69. package/components/table.js +181 -181
  70. package/components/tabs.js +202 -202
  71. package/components/team-grid.js +23 -23
  72. package/components/testimonial.js +94 -94
  73. package/components/theme-toggle.js +82 -82
  74. package/components/toast.js +139 -139
  75. package/components/tooltip.js +167 -167
  76. package/components/transaction-ledger.js +138 -138
  77. package/components/ui-avatar.js +79 -79
  78. package/components/ui-badge.js +61 -61
  79. package/components/ui-button.js +149 -149
  80. package/components/ui-card.js +74 -75
  81. package/components/ui-chip.js +87 -87
  82. package/components/ui-input.js +110 -110
  83. package/components/ui-popover.js +84 -84
  84. package/components/ui-progress-ring.js +60 -60
  85. package/components/ui-select.js +85 -85
  86. package/components/ui-stat.js +75 -75
  87. package/components/ui-switch.js +85 -85
  88. package/components/ui-table.js +69 -69
  89. package/components/ui-tabs.js +99 -99
  90. package/components/ui-tag.js +64 -64
  91. package/components/ui-textarea.js +84 -84
  92. package/components/ui-tooltip.js +66 -66
  93. package/components/video-player.js +22 -22
  94. package/components/wallet-balance.js +114 -114
  95. package/core/a2ui-schema-manager.js +351 -351
  96. package/core/a2ui.js +696 -696
  97. package/core/actions.js +27 -27
  98. package/core/bun-runtime.js +398 -397
  99. package/core/cli/commands/add.js +23 -23
  100. package/core/cli/commands/audit.js +58 -58
  101. package/core/cli/commands/build.js +193 -193
  102. package/core/cli/commands/create-plugin.js +241 -241
  103. package/core/cli/commands/dev.js +252 -285
  104. package/core/cli/commands/lint.js +23 -23
  105. package/core/cli/commands/test.js +33 -34
  106. package/core/cli/migrator.js +71 -71
  107. package/core/cli/ui.js +56 -56
  108. package/core/compliance.js +823 -823
  109. package/core/config.js +265 -265
  110. package/core/db-advanced.js +478 -481
  111. package/core/db.js +282 -284
  112. package/core/enhanced-hmr.js +406 -406
  113. package/core/errors.js +222 -222
  114. package/core/file-router.js +52 -50
  115. package/core/hmr-client.js +203 -204
  116. package/core/hmr.js +205 -197
  117. package/core/html.d.ts +30 -30
  118. package/core/html.js +84 -84
  119. package/core/hydration.js +52 -52
  120. package/core/lipa-namba-journey.js +548 -605
  121. package/core/logging.js +14 -14
  122. package/core/middleware.js +145 -145
  123. package/core/motion.js +106 -106
  124. package/core/nida-cig-middleware.js +417 -460
  125. package/core/patterns.d.ts +124 -124
  126. package/core/patterns.js +947 -1001
  127. package/core/plugins/index.js +345 -345
  128. package/core/request-analytics.js +253 -253
  129. package/core/request-identity.js +93 -93
  130. package/core/router.js +386 -386
  131. package/core/sdk-browser.js +140 -140
  132. package/core/sdk-client.js +61 -61
  133. package/core/sdk.d.ts +133 -133
  134. package/core/sdk.js +148 -148
  135. package/core/seo.js +76 -76
  136. package/core/server/auth-endpoints.js +339 -339
  137. package/core/server/auth.js +180 -180
  138. package/core/server/csrf.js +200 -206
  139. package/core/server/db.js +39 -39
  140. package/core/server/middleware.js +324 -324
  141. package/core/server/rate-limit.js +238 -238
  142. package/core/server/render.js +67 -69
  143. package/core/server/router.js +102 -120
  144. package/core/session-store.js +68 -68
  145. package/core/shim.js +28 -28
  146. package/core/state.d.ts +86 -86
  147. package/core/state.js +276 -276
  148. package/core/store.d.ts +122 -122
  149. package/core/store.js +61 -61
  150. package/core/validation.d.ts +232 -232
  151. package/core/validation.js +602 -602
  152. package/core/websocket.js +656 -641
  153. package/dist/africode.js +233 -230
  154. package/dist/africode.js.map +83 -83
  155. package/dist/build-info.json +3 -3
  156. package/dist/components.js +195 -192
  157. package/dist/components.js.map +73 -73
  158. package/dist/styles/africanity.css +321 -321
  159. package/dist/styles/typography.css +140 -140
  160. package/docs/IDE-Guide.md +50 -50
  161. package/package.json +113 -113
  162. package/scripts/generate-component-schema.js +82 -79
  163. package/styles/africanity.css +321 -321
  164. package/styles/typography.css +140 -140
  165. package/templates/starter/.env.example +15 -15
  166. package/templates/starter/africode.config.js +40 -40
  167. package/templates/starter/package.json +13 -13
  168. package/templates/starter/src/index.js +18 -18
  169. package/templates/starter/src/pages/index.html +55 -55
  170. package/templates/starter/src/pages/index.js +17 -17
  171. package/templates/starter/src/styles/main.css +3 -3
  172. package/templates/starter-3d/.env.example +7 -7
  173. package/templates/starter-3d/africode.config.js +29 -29
  174. package/templates/starter-3d/components/af-model-viewer.js +125 -125
  175. package/templates/starter-3d/package.json +14 -14
  176. package/templates/starter-3d/src/pages/index.html +55 -55
  177. package/templates/starter-3d/src/pages/index.js +50 -50
  178. package/templates/starter-3d/src/styles/main.css +3 -3
  179. package/templates/starter-dashboard/.env.example +21 -21
  180. package/templates/starter-dashboard/africode.config.js +20 -20
  181. package/templates/starter-dashboard/package.json +14 -14
  182. package/templates/starter-dashboard/src/index.js +17 -17
  183. package/templates/starter-dashboard/src/pages/api/analytics.js +24 -24
  184. package/templates/starter-dashboard/src/pages/index.html +118 -118
  185. package/templates/starter-dashboard/src/pages/index.js +110 -110
  186. package/templates/starter-dashboard/src/styles/main.css +172 -172
  187. package/templates/starter-fintech/.env.example +28 -28
  188. package/templates/starter-fintech/africode.config.js +20 -20
  189. package/templates/starter-fintech/package.json +15 -15
  190. package/templates/starter-fintech/src/index.js +17 -17
  191. package/templates/starter-fintech/src/pages/api/auth.js +45 -45
  192. package/templates/starter-fintech/src/pages/api/dashboard.js +19 -0
  193. package/templates/starter-fintech/src/pages/api/transfer.js +65 -65
  194. package/templates/starter-fintech/src/pages/api/wallet.js +39 -39
  195. package/templates/starter-fintech/src/pages/api/webhooks/payment.js +32 -32
  196. package/templates/starter-fintech/src/pages/index.html +169 -169
  197. package/templates/starter-fintech/src/pages/index.js +161 -161
  198. package/templates/starter-fintech/src/styles/main.css +246 -246
  199. package/templates/starter-react/.env.example +15 -15
  200. package/templates/starter-react/africode.config.js +40 -40
  201. package/templates/starter-react/package.json +15 -15
  202. package/templates/starter-react/src/pages/index.html +55 -55
  203. package/templates/starter-react/src/pages/index.js +68 -68
  204. package/templates/starter-react/src/styles/main.css +3 -3
  205. package/templates/starter-tailwind/.env.example +15 -15
  206. package/templates/starter-tailwind/africode.config.js +40 -40
  207. package/templates/starter-tailwind/package.json +19 -19
  208. package/templates/starter-tailwind/src/pages/index.html +55 -55
  209. package/templates/starter-tailwind/src/pages/index.js +67 -67
  210. package/templates/starter-tailwind/src/styles/main.css +3 -3
  211. package/templates/starter-tailwind/src/styles/tailwind.css +1 -1
  212. package/templates/starter-tailwind/src/tailwind-loader.js +30 -30
  213. package/templates/starter-tailwind/tailwind.config.cjs +18 -18
  214. package/templates/starter-website/.env.example +18 -18
  215. package/templates/starter-website/africode.config.js +20 -20
  216. package/templates/starter-website/package.json +14 -14
  217. package/templates/starter-website/src/index.js +17 -17
  218. package/templates/starter-website/src/pages/index.html +124 -124
  219. package/templates/starter-website/src/pages/index.js +116 -116
  220. package/templates/starter-website/src/styles/main.css +195 -195
  221. package/bin/africode.js.1758507140 +0 -343
  222. package/core/heartbeat.js +0 -64
@@ -1,605 +1,548 @@
1
- /**
2
- * Lipa Namba Journey - Framework-Native Primitive
3
- * Bank of Tanzania (BoT) Compliant Payment Flows
4
- *
5
- * Implements complete merchant payment lifecycle:
6
- * - Lipa Namba (Pay by Phone Number)
7
- * - Lipa kwa Simu (Pay by SIM)
8
- * - Merchant KYC/AML compliance
9
- * - Real-time transaction processing
10
- * - Automated regulatory reporting
11
- */
12
-
13
- import { z } from 'zod';
14
- import { EventEmitter } from 'events';
15
- import { frameworkLog } from './logging.js';
16
-
17
- export class LipaNambaJourney extends EventEmitter {
18
- constructor(config = {}) {
19
- super();
20
-
21
- this.config = {
22
- tipsEndpoint: config.tipsEndpoint || 'https://api.tips.go.tz',
23
- nidaMiddleware: config.nidaMiddleware,
24
- amlEngine: config.amlEngine,
25
- database: config.database,
26
- redis: config.redis, // For session management
27
- ...config
28
- };
29
-
30
- this.sessions = new Map();
31
-
32
- // BoT Regulatory Limits (as of 2026)
33
- this.regulatoryLimits = {
34
- merchant: {
35
- daily: 100_000_000, // 100M TZS
36
- perTransaction: 25_000_000, // 25M TZS
37
- monthlyVolume: 1_000_000_000 // 1B TZS
38
- },
39
- customer: {
40
- daily: 50_000_000, // 50M TZS
41
- perTransaction: 10_000_000, // 10M TZS
42
- monthlyVolume: 500_000_000 // 500M TZS
43
- },
44
- sessionTimeout: 30 * 60 * 1000, // 30 minutes
45
- otpTimeout: 5 * 60 * 1000 // 5 minutes
46
- };
47
-
48
- this._initializeEventHandlers();
49
- }
50
-
51
- /**
52
- * Initialize event handlers for journey lifecycle
53
- */
54
- _initializeEventHandlers() {
55
- this.on('payment:initiated', this._handlePaymentInitiated.bind(this));
56
- this.on('customer:identified', this._handleCustomerIdentified.bind(this));
57
- this.on('aml:screened', this._handleAMLScreened.bind(this));
58
- this.on('payment:confirmed', this._handlePaymentConfirmed.bind(this));
59
- this.on('payment:completed', this._handlePaymentCompleted.bind(this));
60
- this.on('payment:failed', this._handlePaymentFailed.bind(this));
61
- }
62
-
63
- /**
64
- * Execute complete Lipa Namba journey end-to-end
65
- * Framework-native primitive for seamless integration
66
- */
67
- async executeFullJourney(merchantRequest, customerIdentity, confirmationData) {
68
- try {
69
- this.emit('journey:started', { merchantRequest });
70
-
71
- // Step 1: Merchant Payment Initiation
72
- const initiation = await this.initiateMerchantPayment(merchantRequest);
73
- if (!initiation.ok) {
74
- throw new Error(`Initiation failed: ${initiation.error}`);
75
- }
76
-
77
- // Step 2: Customer Identity Verification
78
- const identification = await this.verifyCustomerIdentity(
79
- initiation.paymentRequestId,
80
- customerIdentity
81
- );
82
- if (!identification.ok) {
83
- throw new Error(`Identification failed: ${identification.error}`);
84
- }
85
-
86
- // Step 3: AML/FIU Screening
87
- const amlScreening = await this.performAMLScreening(
88
- initiation.paymentRequestId,
89
- identification.customerData
90
- );
91
- if (!amlScreening.ok) {
92
- throw new Error(`AML screening failed: ${amlScreening.error}`);
93
- }
94
-
95
- // Step 4: Payment Confirmation
96
- const confirmation = await this.confirmPayment(
97
- initiation.paymentRequestId,
98
- identification.customerId,
99
- confirmationData.code
100
- );
101
- if (!confirmation.ok) {
102
- throw new Error(`Confirmation failed: ${confirmation.error}`);
103
- }
104
-
105
- // Step 5: TIPS Transaction Processing
106
- const completion = await this.processTIPSTransaction(
107
- initiation.paymentRequestId,
108
- confirmation.transactionData
109
- );
110
-
111
- this.emit('journey:completed', { completion });
112
- return completion;
113
-
114
- } catch (error) {
115
- this.emit('journey:failed', { error: error.message });
116
- throw error;
117
- }
118
- }
119
-
120
- /**
121
- * Step 1: Merchant Payment Initiation with BoT Compliance
122
- */
123
- async initiateMerchantPayment(request) {
124
- const schema = z.object({
125
- merchantId: z.string().min(1),
126
- customerPhone: z.string().regex(/^255\d{9}$/), // Tanzanian format
127
- amount: z.number().positive().max(this.regulatoryLimits.merchant.daily),
128
- currency: z.string().default('TZS'),
129
- description: z.string().min(1).max(100),
130
- reference: z.string().optional(),
131
- callbackUrl: z.string().url().optional(),
132
- metadata: z.object({}).optional()
133
- });
134
-
135
- const validated = schema.parse(request);
136
-
137
- // Deduplicate by reference when provided: return existing session if found
138
- if (validated.reference) {
139
- for (const session of this.sessions.values()) {
140
- if (session.reference === validated.reference) {
141
- return {
142
- ok: true,
143
- paymentRequestId: session.id,
144
- sessionData: session,
145
- message: 'DUPLICATE_REFERENCE',
146
- nextStep: session.status === 'INITIATED' ? 'IDENTIFY_CUSTOMER' : undefined,
147
- expiresIn: Math.max(0, Math.floor((new Date(session.expiresAt) - Date.now()) / 1000))
148
- };
149
- }
150
- }
151
- }
152
-
153
- // Verify merchant is registered and compliant
154
- const merchantStatus = await this._verifyMerchantCompliance(validated.merchantId);
155
- if (!merchantStatus.ok) {
156
- return { ok: false, error: merchantStatus.error };
157
- }
158
-
159
- // Check merchant transaction limits
160
- const limitCheck = await this._checkMerchantLimits(validated.merchantId, validated.amount);
161
- if (!limitCheck.ok) {
162
- return { ok: false, error: limitCheck.error };
163
- }
164
-
165
- // Generate secure payment request ID
166
- const paymentRequestId = this._generateSecurePaymentId();
167
-
168
- // Create payment session in Redis
169
- const sessionData = {
170
- id: paymentRequestId,
171
- merchantId: validated.merchantId,
172
- customerPhone: validated.customerPhone,
173
- amount: validated.amount,
174
- currency: validated.currency,
175
- description: validated.description,
176
- reference: validated.reference || paymentRequestId,
177
- status: 'INITIATED',
178
- createdAt: new Date(),
179
- expiresAt: new Date(Date.now() + this.regulatoryLimits.sessionTimeout),
180
- callbackUrl: validated.callbackUrl,
181
- metadata: validated.metadata || {}
182
- };
183
-
184
- await this._storePaymentSession(sessionData);
185
-
186
- this.emit('payment:initiated', sessionData);
187
-
188
- return {
189
- ok: true,
190
- paymentRequestId,
191
- redirectUrl: `/pay/${paymentRequestId}`,
192
- sessionData,
193
- nextStep: 'IDENTIFY_CUSTOMER',
194
- expiresIn: this.regulatoryLimits.sessionTimeout / 1000
195
- };
196
- }
197
-
198
- async initiatePayment(request) {
199
- return this.initiateMerchantPayment(request);
200
- }
201
-
202
- /**
203
- * Step 2: Customer Identification (via Prompt)
204
- * Customer enters PIN to identify with NIDA
205
- */
206
- async identifyCustomer(paymentRequestId, nin, pin) {
207
- // Get payment request
208
- const paymentRequest = await this._getPaymentRequest(paymentRequestId);
209
-
210
- if (!paymentRequest) {
211
- return { ok: false, error: 'PAYMENT_REQUEST_NOT_FOUND' };
212
- }
213
-
214
- if (paymentRequest.status !== 'INITIATED') {
215
- return { ok: false, error: 'INVALID_PAYMENT_STATUS' };
216
- }
217
-
218
- if (new Date() > paymentRequest.expiresAt) {
219
- return { ok: false, error: 'PAYMENT_EXPIRED' };
220
- }
221
-
222
- // Verify NIN with NIDA CIG
223
- const nidaResult = await this._verifyNIDA(nin, pin);
224
-
225
- if (!nidaResult.verified) {
226
- return { ok: false, error: 'NIDA_VERIFICATION_FAILED' };
227
- }
228
-
229
- // Check customer limits
230
- const customerStatus = await this._checkCustomerLimits(
231
- nidaResult.nin,
232
- paymentRequest.amount
233
- );
234
-
235
- if (!customerStatus.ok) {
236
- return {
237
- ok: false,
238
- error: customerStatus.error,
239
- code: 'CUSTOMER_LIMIT_EXCEEDED'
240
- };
241
- }
242
-
243
- // Update payment request with customer
244
- await this._updatePaymentRequest(paymentRequestId, {
245
- status: 'IDENTIFIED',
246
- customerId: nidaResult.nin,
247
- customerName: `${nidaResult.firstName} ${nidaResult.lastName}`,
248
- identifiedAt: new Date()
249
- });
250
-
251
- return {
252
- ok: true,
253
- customerId: nidaResult.nin,
254
- customerName: `${nidaResult.firstName} ${nidaResult.lastName}`,
255
- customerData: {
256
- nin: nidaResult.nin,
257
- firstName: nidaResult.firstName,
258
- lastName: nidaResult.lastName,
259
- customerName: `${nidaResult.firstName} ${nidaResult.lastName}`
260
- },
261
- nextStep: 'CONFIRM'
262
- };
263
- }
264
-
265
- async verifyCustomerIdentity(paymentRequestId, customerIdentity) {
266
- const identity = customerIdentity || {};
267
- return this.identifyCustomer(paymentRequestId, identity.nin, identity.pin);
268
- }
269
-
270
- /**
271
- * Step 3: AML Screening
272
- * Check customer against FIU suspicious persons list
273
- */
274
- async performAMLScreening(paymentRequestId, customerId) {
275
- // Check FIU list
276
- const isBlocked = await this._checkFIUList(customerId);
277
-
278
- if (isBlocked) {
279
- await this._updatePaymentRequest(paymentRequestId, {
280
- status: 'BLOCKED',
281
- blockReason: 'AML_SCREENING_FAILED'
282
- });
283
-
284
- return {
285
- ok: false,
286
- error: 'AML_SCREENING_FAILED',
287
- blocked: true
288
- };
289
- }
290
-
291
- // Queue for transaction monitoring
292
- await this._queueForMonitoring(paymentRequestId, customerId);
293
-
294
- return { ok: true };
295
- }
296
-
297
- /**
298
- * Step 4: Confirmation
299
- * Customer confirms payment details
300
- */
301
- async confirmPayment(paymentRequestId, customerId, confirmationCode) {
302
- const paymentRequest = await this._getPaymentRequest(paymentRequestId);
303
-
304
- if (!paymentRequest) {
305
- return { ok: false, error: 'PAYMENT_REQUEST_NOT_FOUND' };
306
- }
307
-
308
- if (paymentRequest.status !== 'IDENTIFIED') {
309
- return { ok: false, error: 'INVALID_PAYMENT_STATUS' };
310
- }
311
-
312
- if (paymentRequest.customerId !== customerId) {
313
- return { ok: false, error: 'CUSTOMER_MISMATCH' };
314
- }
315
-
316
- // Verify confirmation code (could be OTP)
317
- // const isValidCode = await this._verifyConfirmationCode(customerId, confirmationCode);
318
- // if (!isValidCode) {
319
- // return { ok: false, error: 'INVALID_CONFIRMATION_CODE' };
320
- // }
321
-
322
- // Update payment request status
323
- await this._updatePaymentRequest(paymentRequestId, {
324
- status: 'CONFIRMED',
325
- confirmedAt: new Date()
326
- });
327
-
328
- return {
329
- ok: true,
330
- nextStep: 'PROCESS'
331
- };
332
- }
333
-
334
- /**
335
- * Step 5: Process Payment via TIPS
336
- * Submit to Tanzania Instant Payment System
337
- */
338
- async processPayment(paymentRequestId, customerId) {
339
- const paymentRequest = await this._getPaymentRequest(paymentRequestId);
340
-
341
- if (!paymentRequest) {
342
- return { ok: false, error: 'PAYMENT_REQUEST_NOT_FOUND' };
343
- }
344
-
345
- if (paymentRequest.status !== 'CONFIRMED') {
346
- return { ok: false, error: 'PAYMENT_NOT_CONFIRMED' };
347
- }
348
-
349
- try {
350
- // Initiate TIPS transaction
351
- const tipsResult = await this._submitToTIPS({
352
- customerId,
353
- merchantId: paymentRequest.merchantId,
354
- amount: paymentRequest.amount,
355
- reference: paymentRequest.reference,
356
- description: paymentRequest.description
357
- });
358
-
359
- if (!tipsResult.ok) {
360
- await this._updatePaymentRequest(paymentRequestId, {
361
- status: 'FAILED',
362
- failureReason: tipsResult.error
363
- });
364
-
365
- return {
366
- ok: false,
367
- error: 'TIPS_TRANSACTION_FAILED'
368
- };
369
- }
370
-
371
- // Update payment request
372
- await this._updatePaymentRequest(paymentRequestId, {
373
- status: 'COMPLETED',
374
- transactionId: tipsResult.transactionId,
375
- completedAt: new Date()
376
- });
377
-
378
- // Log for AML/FIU reporting
379
- await this._logAMLTransaction(paymentRequestId, tipsResult.transactionId);
380
-
381
- // Call merchant callback if configured
382
- if (paymentRequest.callbackUrl) {
383
- await this._notifyMerchant(paymentRequest.callbackUrl, {
384
- paymentRequestId,
385
- transactionId: tipsResult.transactionId,
386
- status: 'COMPLETED',
387
- amount: paymentRequest.amount,
388
- timestamp: new Date().toISOString()
389
- });
390
- }
391
-
392
- return {
393
- ok: true,
394
- transactionId: tipsResult.transactionId,
395
- status: 'COMPLETED',
396
- amount: paymentRequest.amount,
397
- reference: paymentRequest.reference
398
- };
399
-
400
- } catch (error) {
401
- frameworkLog('error', '[Lipa Namba] Processing error:', error);
402
- return {
403
- ok: false,
404
- error: error.message,
405
- code: 'PROCESSING_ERROR'
406
- };
407
- }
408
- }
409
-
410
- /**
411
- * Full journey orchestrator
412
- */
413
- async executeFullJourney(request, credentials, confirmation) {
414
- const steps = [];
415
-
416
- try {
417
- // Step 1: Initiate
418
- const init = await this.initiatePayment(request);
419
- if (!init.ok) return { ok: false, error: init.error || 'INITIATION_FAILED', completedSteps: steps };
420
- steps.push({ step: 'INITIATE', ok: true });
421
-
422
- // Step 2: Identify
423
- const identify = await this.identifyCustomer(
424
- init.paymentRequestId,
425
- credentials.nin,
426
- credentials.pin
427
- );
428
- if (!identify.ok) return { ok: false, error: identify.error || 'IDENTIFICATION_FAILED', completedSteps: steps };
429
- steps.push({ step: 'IDENTIFY', ok: true });
430
-
431
- // Step 3: AML Screen
432
- const aml = await this.performAMLScreening(
433
- init.paymentRequestId,
434
- identify.customerId
435
- );
436
- if (!aml.ok) return { ok: false, error: aml.error || 'AML_SCREEN_FAILED', completedSteps: steps };
437
- steps.push({ step: 'AML_SCREEN', ok: true });
438
-
439
- // Step 4: Confirm
440
- const confirm = await this.confirmPayment(
441
- init.paymentRequestId,
442
- identify.customerId,
443
- confirmation.code
444
- );
445
- if (!confirm.ok) return { ok: false, error: confirm.error || 'CONFIRMATION_FAILED', completedSteps: steps };
446
- steps.push({ step: 'CONFIRM', ok: true });
447
-
448
- // Step 5: Process
449
- const process = await this.processPayment(
450
- init.paymentRequestId,
451
- identify.customerId
452
- );
453
- if (!process.ok) return { ok: false, error: process.error || 'PROCESSING_FAILED', completedSteps: steps };
454
- steps.push({ step: 'PROCESS', ok: true });
455
-
456
- return {
457
- ok: true,
458
- transactionId: process.transactionId,
459
- status: 'COMPLETED',
460
- steps
461
- };
462
-
463
- } catch (error) {
464
- return {
465
- ok: false,
466
- error: error.message,
467
- completedSteps: steps
468
- };
469
- }
470
- }
471
-
472
- // ==================== Private Helpers ====================
473
-
474
- async _checkMerchantLimits(merchantId, amount) {
475
- // Check daily limit
476
- const dailyTotal = await this._getMerchantDailyTotal(merchantId);
477
- if (dailyTotal + amount > this.regulatoryLimits.merchant.daily) {
478
- return { ok: false, error: 'DAILY_LIMIT_EXCEEDED' };
479
- }
480
-
481
- // Check per-transaction limit
482
- if (amount > this.regulatoryLimits.merchant.perTransaction) {
483
- return { ok: false, error: 'TRANSACTION_LIMIT_EXCEEDED' };
484
- }
485
-
486
- return { ok: true };
487
- }
488
-
489
- async _checkCustomerLimits(customerId, amount) {
490
- const dailyTotal = await this._getCustomerDailyTotal(customerId);
491
- if (dailyTotal + amount > this.regulatoryLimits.customer.daily) {
492
- return { ok: false, error: 'DAILY_LIMIT_EXCEEDED' };
493
- }
494
-
495
- if (amount > this.regulatoryLimits.customer.perTransaction) {
496
- return { ok: false, error: 'TRANSACTION_LIMIT_EXCEEDED' };
497
- }
498
-
499
- return { ok: true };
500
- }
501
-
502
- _generatePaymentId() {
503
- return `LN_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
504
- }
505
-
506
- _generateSecurePaymentId() {
507
- return this._generatePaymentId();
508
- }
509
-
510
- async _verifyMerchantCompliance(merchantId) {
511
- if (!merchantId) {
512
- return { ok: false, error: 'MERCHANT_NOT_FOUND' };
513
- }
514
-
515
- return { ok: true };
516
- }
517
-
518
- _handlePaymentInitiated(sessionData) {
519
- return sessionData;
520
- }
521
-
522
- _handleCustomerIdentified(data) {
523
- return data;
524
- }
525
-
526
- _handleAMLScreened(data) {
527
- return data;
528
- }
529
-
530
- _handlePaymentConfirmed(data) {
531
- return data;
532
- }
533
-
534
- _handlePaymentCompleted(data) {
535
- return data;
536
- }
537
-
538
- _handlePaymentFailed(data) {
539
- return data;
540
- }
541
-
542
- async _verifyNIDA(nin, pin) {
543
- // Implementation calls NIDA CIG
544
- // For now, provide a deterministic mock: valid NIN is 20 digits
545
- const ninPattern = /^[0-9]{20}$/;
546
- if (!nin || !ninPattern.test(nin)) {
547
- return { verified: false, nin };
548
- }
549
-
550
- // Simulate successful lookup
551
- return { verified: true, nin, firstName: 'John', lastName: 'Doe' };
552
- }
553
-
554
- async _checkFIUList(customerId) {
555
- // Query FIU database
556
- // For now, return false (not flagged)
557
- return false;
558
- }
559
-
560
- async _storePaymentRequest(request) {
561
- this.sessions.set(request.id, { ...request });
562
- }
563
-
564
- async _storePaymentSession(sessionData) {
565
- this.sessions.set(sessionData.id, { ...sessionData });
566
- }
567
-
568
- async _getPaymentRequest(id) {
569
- return this.sessions.get(id) || null;
570
- }
571
-
572
- async _updatePaymentRequest(id, updates) {
573
- const current = this.sessions.get(id);
574
- if (current) {
575
- this.sessions.set(id, { ...current, ...updates });
576
- }
577
- }
578
-
579
- async _getMerchantDailyTotal(merchantId) {
580
- return 0;
581
- }
582
-
583
- async _getCustomerDailyTotal(customerId) {
584
- return 0;
585
- }
586
-
587
- async _queueForMonitoring(paymentRequestId, customerId) {
588
- // Queue for AML transaction monitoring
589
- }
590
-
591
- async _submitToTIPS(txData) {
592
- // Submit to TIPS
593
- return { ok: true, transactionId: 'TIPS_' + Date.now() };
594
- }
595
-
596
- async _logAMLTransaction(paymentRequestId, transactionId) {
597
- // Log for FIU reporting
598
- }
599
-
600
- async _notifyMerchant(callbackUrl, data) {
601
- // POST callback to merchant
602
- }
603
- }
604
-
605
- export default LipaNambaJourney;
1
+ /**
2
+ * Lipa Namba Journey - Framework-Native Primitive
3
+ * Bank of Tanzania (BoT) Compliant Payment Flows
4
+ *
5
+ * Implements complete merchant payment lifecycle:
6
+ * - Lipa Namba (Pay by Phone Number)
7
+ * - Lipa kwa Simu (Pay by SIM)
8
+ * - Merchant KYC/AML compliance
9
+ * - Real-time transaction processing
10
+ * - Automated regulatory reporting
11
+ */
12
+
13
+ import { z } from 'zod';
14
+ import { EventEmitter } from 'events';
15
+ import { frameworkLog } from './logging.js';
16
+
17
+ export class LipaNambaJourney extends EventEmitter {
18
+ constructor(config = {}) {
19
+ super();
20
+
21
+ this.config = {
22
+ tipsEndpoint: config.tipsEndpoint || 'https://api.tips.go.tz',
23
+ nidaMiddleware: config.nidaMiddleware,
24
+ amlEngine: config.amlEngine,
25
+ database: config.database,
26
+ redis: config.redis, // For session management
27
+ ...config
28
+ };
29
+
30
+ this.sessions = new Map();
31
+
32
+ // BoT Regulatory Limits (as of 2026)
33
+ this.regulatoryLimits = {
34
+ merchant: {
35
+ daily: 100_000_000, // 100M TZS
36
+ perTransaction: 25_000_000, // 25M TZS
37
+ monthlyVolume: 1_000_000_000 // 1B TZS
38
+ },
39
+ customer: {
40
+ daily: 50_000_000, // 50M TZS
41
+ perTransaction: 10_000_000, // 10M TZS
42
+ monthlyVolume: 500_000_000 // 500M TZS
43
+ },
44
+ sessionTimeout: 30 * 60 * 1000, // 30 minutes
45
+ otpTimeout: 5 * 60 * 1000 // 5 minutes
46
+ };
47
+
48
+ this._initializeEventHandlers();
49
+ }
50
+
51
+ /**
52
+ * Initialize event handlers for journey lifecycle
53
+ */
54
+ _initializeEventHandlers() {
55
+ this.on('payment:initiated', this._handlePaymentInitiated.bind(this));
56
+ this.on('customer:identified', this._handleCustomerIdentified.bind(this));
57
+ this.on('aml:screened', this._handleAMLScreened.bind(this));
58
+ this.on('payment:confirmed', this._handlePaymentConfirmed.bind(this));
59
+ this.on('payment:completed', this._handlePaymentCompleted.bind(this));
60
+ this.on('payment:failed', this._handlePaymentFailed.bind(this));
61
+ }
62
+
63
+ /**
64
+ * Step 1: Merchant Payment Initiation with BoT Compliance
65
+ */
66
+ async initiateMerchantPayment(request) {
67
+ const schema = z.object({
68
+ merchantId: z.string().min(1),
69
+ customerPhone: z.string().regex(/^255\d{9}$/), // Tanzanian format
70
+ amount: z.number().positive().max(this.regulatoryLimits.merchant.daily),
71
+ currency: z.string().default('TZS'),
72
+ description: z.string().min(1).max(100),
73
+ reference: z.string().optional(),
74
+ callbackUrl: z.string().url().optional(),
75
+ metadata: z.object({}).optional()
76
+ });
77
+
78
+ const validated = schema.parse(request);
79
+
80
+ // Deduplicate by reference when provided: return existing session if found
81
+ if (validated.reference) {
82
+ for (const session of this.sessions.values()) {
83
+ if (session.reference === validated.reference) {
84
+ return {
85
+ ok: true,
86
+ paymentRequestId: session.id,
87
+ sessionData: session,
88
+ message: 'DUPLICATE_REFERENCE',
89
+ nextStep: session.status === 'INITIATED' ? 'IDENTIFY_CUSTOMER' : undefined,
90
+ expiresIn: Math.max(0, Math.floor((new Date(session.expiresAt) - Date.now()) / 1000))
91
+ };
92
+ }
93
+ }
94
+ }
95
+
96
+ // Verify merchant is registered and compliant
97
+ const merchantStatus = await this._verifyMerchantCompliance(validated.merchantId);
98
+ if (!merchantStatus.ok) {
99
+ return { ok: false, error: merchantStatus.error };
100
+ }
101
+
102
+ // Check merchant transaction limits
103
+ const limitCheck = await this._checkMerchantLimits(validated.merchantId, validated.amount);
104
+ if (!limitCheck.ok) {
105
+ return { ok: false, error: limitCheck.error };
106
+ }
107
+
108
+ // Generate secure payment request ID
109
+ const paymentRequestId = this._generateSecurePaymentId();
110
+
111
+ // Create payment session in Redis
112
+ const sessionData = {
113
+ id: paymentRequestId,
114
+ merchantId: validated.merchantId,
115
+ customerPhone: validated.customerPhone,
116
+ amount: validated.amount,
117
+ currency: validated.currency,
118
+ description: validated.description,
119
+ reference: validated.reference || paymentRequestId,
120
+ status: 'INITIATED',
121
+ createdAt: new Date(),
122
+ expiresAt: new Date(Date.now() + this.regulatoryLimits.sessionTimeout),
123
+ callbackUrl: validated.callbackUrl,
124
+ metadata: validated.metadata || {}
125
+ };
126
+
127
+ await this._storePaymentSession(sessionData);
128
+
129
+ this.emit('payment:initiated', sessionData);
130
+
131
+ return {
132
+ ok: true,
133
+ paymentRequestId,
134
+ redirectUrl: `/pay/${paymentRequestId}`,
135
+ sessionData,
136
+ nextStep: 'IDENTIFY_CUSTOMER',
137
+ expiresIn: this.regulatoryLimits.sessionTimeout / 1000
138
+ };
139
+ }
140
+
141
+ async initiatePayment(request) {
142
+ return this.initiateMerchantPayment(request);
143
+ }
144
+
145
+ /**
146
+ * Step 2: Customer Identification (via Prompt)
147
+ * Customer enters PIN to identify with NIDA
148
+ */
149
+ async identifyCustomer(paymentRequestId, nin, pin) {
150
+ // Get payment request
151
+ const paymentRequest = await this._getPaymentRequest(paymentRequestId);
152
+
153
+ if (!paymentRequest) {
154
+ return { ok: false, error: 'PAYMENT_REQUEST_NOT_FOUND' };
155
+ }
156
+
157
+ if (paymentRequest.status !== 'INITIATED') {
158
+ return { ok: false, error: 'INVALID_PAYMENT_STATUS' };
159
+ }
160
+
161
+ if (new Date() > paymentRequest.expiresAt) {
162
+ return { ok: false, error: 'PAYMENT_EXPIRED' };
163
+ }
164
+
165
+ // Verify NIN with NIDA CIG
166
+ const nidaResult = await this._verifyNIDA(nin, pin);
167
+
168
+ if (!nidaResult.verified) {
169
+ return { ok: false, error: 'NIDA_VERIFICATION_FAILED' };
170
+ }
171
+
172
+ // Check customer limits
173
+ const customerStatus = await this._checkCustomerLimits(
174
+ nidaResult.nin,
175
+ paymentRequest.amount
176
+ );
177
+
178
+ if (!customerStatus.ok) {
179
+ return {
180
+ ok: false,
181
+ error: customerStatus.error,
182
+ code: 'CUSTOMER_LIMIT_EXCEEDED'
183
+ };
184
+ }
185
+
186
+ // Update payment request with customer
187
+ await this._updatePaymentRequest(paymentRequestId, {
188
+ status: 'IDENTIFIED',
189
+ customerId: nidaResult.nin,
190
+ customerName: `${nidaResult.firstName} ${nidaResult.lastName}`,
191
+ identifiedAt: new Date()
192
+ });
193
+
194
+ return {
195
+ ok: true,
196
+ customerId: nidaResult.nin,
197
+ customerName: `${nidaResult.firstName} ${nidaResult.lastName}`,
198
+ customerData: {
199
+ nin: nidaResult.nin,
200
+ firstName: nidaResult.firstName,
201
+ lastName: nidaResult.lastName,
202
+ customerName: `${nidaResult.firstName} ${nidaResult.lastName}`
203
+ },
204
+ nextStep: 'CONFIRM'
205
+ };
206
+ }
207
+
208
+ async verifyCustomerIdentity(paymentRequestId, customerIdentity) {
209
+ const identity = customerIdentity || {};
210
+ return this.identifyCustomer(paymentRequestId, identity.nin, identity.pin);
211
+ }
212
+
213
+ /**
214
+ * Step 3: AML Screening
215
+ * Check customer against FIU suspicious persons list
216
+ */
217
+ async performAMLScreening(paymentRequestId, customerId) {
218
+ // Check FIU list
219
+ const isBlocked = await this._checkFIUList(customerId);
220
+
221
+ if (isBlocked) {
222
+ await this._updatePaymentRequest(paymentRequestId, {
223
+ status: 'BLOCKED',
224
+ blockReason: 'AML_SCREENING_FAILED'
225
+ });
226
+
227
+ return {
228
+ ok: false,
229
+ error: 'AML_SCREENING_FAILED',
230
+ blocked: true
231
+ };
232
+ }
233
+
234
+ // Queue for transaction monitoring
235
+ await this._queueForMonitoring(paymentRequestId, customerId);
236
+
237
+ return { ok: true };
238
+ }
239
+
240
+ /**
241
+ * Step 4: Confirmation
242
+ * Customer confirms payment details
243
+ */
244
+ async confirmPayment(paymentRequestId, customerId, _confirmationCode) {
245
+ const paymentRequest = await this._getPaymentRequest(paymentRequestId);
246
+
247
+ if (!paymentRequest) {
248
+ return { ok: false, error: 'PAYMENT_REQUEST_NOT_FOUND' };
249
+ }
250
+
251
+ if (paymentRequest.status !== 'IDENTIFIED') {
252
+ return { ok: false, error: 'INVALID_PAYMENT_STATUS' };
253
+ }
254
+
255
+ if (paymentRequest.customerId !== customerId) {
256
+ return { ok: false, error: 'CUSTOMER_MISMATCH' };
257
+ }
258
+
259
+ // Verify confirmation code (could be OTP)
260
+ // const isValidCode = await this._verifyConfirmationCode(customerId, confirmationCode);
261
+ // if (!isValidCode) {
262
+ // return { ok: false, error: 'INVALID_CONFIRMATION_CODE' };
263
+ // }
264
+
265
+ // Update payment request status
266
+ await this._updatePaymentRequest(paymentRequestId, {
267
+ status: 'CONFIRMED',
268
+ confirmedAt: new Date()
269
+ });
270
+
271
+ return {
272
+ ok: true,
273
+ nextStep: 'PROCESS'
274
+ };
275
+ }
276
+
277
+ /**
278
+ * Step 5: Process Payment via TIPS
279
+ * Submit to Tanzania Instant Payment System
280
+ */
281
+ async processPayment(paymentRequestId, customerId) {
282
+ const paymentRequest = await this._getPaymentRequest(paymentRequestId);
283
+
284
+ if (!paymentRequest) {
285
+ return { ok: false, error: 'PAYMENT_REQUEST_NOT_FOUND' };
286
+ }
287
+
288
+ if (paymentRequest.status !== 'CONFIRMED') {
289
+ return { ok: false, error: 'PAYMENT_NOT_CONFIRMED' };
290
+ }
291
+
292
+ try {
293
+ // Initiate TIPS transaction
294
+ const tipsResult = await this._submitToTIPS({
295
+ customerId,
296
+ merchantId: paymentRequest.merchantId,
297
+ amount: paymentRequest.amount,
298
+ reference: paymentRequest.reference,
299
+ description: paymentRequest.description
300
+ });
301
+
302
+ if (!tipsResult.ok) {
303
+ await this._updatePaymentRequest(paymentRequestId, {
304
+ status: 'FAILED',
305
+ failureReason: tipsResult.error
306
+ });
307
+
308
+ return {
309
+ ok: false,
310
+ error: 'TIPS_TRANSACTION_FAILED'
311
+ };
312
+ }
313
+
314
+ // Update payment request
315
+ await this._updatePaymentRequest(paymentRequestId, {
316
+ status: 'COMPLETED',
317
+ transactionId: tipsResult.transactionId,
318
+ completedAt: new Date()
319
+ });
320
+
321
+ // Log for AML/FIU reporting
322
+ await this._logAMLTransaction(paymentRequestId, tipsResult.transactionId);
323
+
324
+ // Call merchant callback if configured
325
+ if (paymentRequest.callbackUrl) {
326
+ await this._notifyMerchant(paymentRequest.callbackUrl, {
327
+ paymentRequestId,
328
+ transactionId: tipsResult.transactionId,
329
+ status: 'COMPLETED',
330
+ amount: paymentRequest.amount,
331
+ timestamp: new Date().toISOString()
332
+ });
333
+ }
334
+
335
+ return {
336
+ ok: true,
337
+ transactionId: tipsResult.transactionId,
338
+ status: 'COMPLETED',
339
+ amount: paymentRequest.amount,
340
+ reference: paymentRequest.reference
341
+ };
342
+
343
+ } catch (error) {
344
+ frameworkLog('error', '[Lipa Namba] Processing error:', error);
345
+ return {
346
+ ok: false,
347
+ error: error.message,
348
+ code: 'PROCESSING_ERROR'
349
+ };
350
+ }
351
+ }
352
+
353
+ /**
354
+ * Full journey orchestrator
355
+ */
356
+ async executeFullJourney(request, credentials, confirmation) {
357
+ const steps = [];
358
+
359
+ try {
360
+ // Step 1: Initiate
361
+ const init = await this.initiatePayment(request);
362
+ if (!init.ok) {return { ok: false, error: init.error || 'INITIATION_FAILED', completedSteps: steps };}
363
+ steps.push({ step: 'INITIATE', ok: true });
364
+
365
+ // Step 2: Identify
366
+ const identify = await this.identifyCustomer(
367
+ init.paymentRequestId,
368
+ credentials.nin,
369
+ credentials.pin
370
+ );
371
+ if (!identify.ok) {return { ok: false, error: identify.error || 'IDENTIFICATION_FAILED', completedSteps: steps };}
372
+ steps.push({ step: 'IDENTIFY', ok: true });
373
+
374
+ // Step 3: AML Screen
375
+ const aml = await this.performAMLScreening(
376
+ init.paymentRequestId,
377
+ identify.customerId
378
+ );
379
+ if (!aml.ok) {return { ok: false, error: aml.error || 'AML_SCREEN_FAILED', completedSteps: steps };}
380
+ steps.push({ step: 'AML_SCREEN', ok: true });
381
+
382
+ // Step 4: Confirm
383
+ const confirm = await this.confirmPayment(
384
+ init.paymentRequestId,
385
+ identify.customerId,
386
+ confirmation.code
387
+ );
388
+ if (!confirm.ok) {return { ok: false, error: confirm.error || 'CONFIRMATION_FAILED', completedSteps: steps };}
389
+ steps.push({ step: 'CONFIRM', ok: true });
390
+
391
+ // Step 5: Process
392
+ const process = await this.processPayment(
393
+ init.paymentRequestId,
394
+ identify.customerId
395
+ );
396
+ if (!process.ok) {return { ok: false, error: process.error || 'PROCESSING_FAILED', completedSteps: steps };}
397
+ steps.push({ step: 'PROCESS', ok: true });
398
+
399
+ return {
400
+ ok: true,
401
+ transactionId: process.transactionId,
402
+ status: 'COMPLETED',
403
+ steps
404
+ };
405
+
406
+ } catch (error) {
407
+ return {
408
+ ok: false,
409
+ error: error.message,
410
+ completedSteps: steps
411
+ };
412
+ }
413
+ }
414
+
415
+ // ==================== Private Helpers ====================
416
+
417
+ async _checkMerchantLimits(merchantId, amount) {
418
+ // Check daily limit
419
+ const dailyTotal = await this._getMerchantDailyTotal(merchantId);
420
+ if (dailyTotal + amount > this.regulatoryLimits.merchant.daily) {
421
+ return { ok: false, error: 'DAILY_LIMIT_EXCEEDED' };
422
+ }
423
+
424
+ // Check per-transaction limit
425
+ if (amount > this.regulatoryLimits.merchant.perTransaction) {
426
+ return { ok: false, error: 'TRANSACTION_LIMIT_EXCEEDED' };
427
+ }
428
+
429
+ return { ok: true };
430
+ }
431
+
432
+ async _checkCustomerLimits(customerId, amount) {
433
+ const dailyTotal = await this._getCustomerDailyTotal(customerId);
434
+ if (dailyTotal + amount > this.regulatoryLimits.customer.daily) {
435
+ return { ok: false, error: 'DAILY_LIMIT_EXCEEDED' };
436
+ }
437
+
438
+ if (amount > this.regulatoryLimits.customer.perTransaction) {
439
+ return { ok: false, error: 'TRANSACTION_LIMIT_EXCEEDED' };
440
+ }
441
+
442
+ return { ok: true };
443
+ }
444
+
445
+ _generatePaymentId() {
446
+ return `LN_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
447
+ }
448
+
449
+ _generateSecurePaymentId() {
450
+ return this._generatePaymentId();
451
+ }
452
+
453
+ async _verifyMerchantCompliance(merchantId) {
454
+ if (!merchantId) {
455
+ return { ok: false, error: 'MERCHANT_NOT_FOUND' };
456
+ }
457
+
458
+ return { ok: true };
459
+ }
460
+
461
+ _handlePaymentInitiated(sessionData) {
462
+ return sessionData;
463
+ }
464
+
465
+ _handleCustomerIdentified(data) {
466
+ return data;
467
+ }
468
+
469
+ _handleAMLScreened(data) {
470
+ return data;
471
+ }
472
+
473
+ _handlePaymentConfirmed(data) {
474
+ return data;
475
+ }
476
+
477
+ _handlePaymentCompleted(data) {
478
+ return data;
479
+ }
480
+
481
+ _handlePaymentFailed(data) {
482
+ return data;
483
+ }
484
+
485
+ async _verifyNIDA(nin, _pin) {
486
+ // Implementation calls NIDA CIG
487
+ // For now, provide a deterministic mock: valid NIN is 20 digits
488
+ const ninPattern = /^[0-9]{20}$/;
489
+ if (!nin || !ninPattern.test(nin)) {
490
+ return { verified: false, nin };
491
+ }
492
+
493
+ // Simulate successful lookup
494
+ return { verified: true, nin, firstName: 'John', lastName: 'Doe' };
495
+ }
496
+
497
+ async _checkFIUList(_customerId) {
498
+ // Query FIU database
499
+ // For now, return false (not flagged)
500
+ return false;
501
+ }
502
+
503
+ async _storePaymentRequest(request) {
504
+ this.sessions.set(request.id, { ...request });
505
+ }
506
+
507
+ async _storePaymentSession(sessionData) {
508
+ this.sessions.set(sessionData.id, { ...sessionData });
509
+ }
510
+
511
+ async _getPaymentRequest(id) {
512
+ return this.sessions.get(id) || null;
513
+ }
514
+
515
+ async _updatePaymentRequest(id, updates) {
516
+ const current = this.sessions.get(id);
517
+ if (current) {
518
+ this.sessions.set(id, { ...current, ...updates });
519
+ }
520
+ }
521
+
522
+ async _getMerchantDailyTotal(_merchantId) {
523
+ return 0;
524
+ }
525
+
526
+ async _getCustomerDailyTotal(_customerId) {
527
+ return 0;
528
+ }
529
+
530
+ async _queueForMonitoring(_paymentRequestId, _customerId) {
531
+ // Queue for AML transaction monitoring
532
+ }
533
+
534
+ async _submitToTIPS(_txData) {
535
+ // Submit to TIPS
536
+ return { ok: true, transactionId: 'TIPS_' + Date.now() };
537
+ }
538
+
539
+ async _logAMLTransaction(_paymentRequestId, _transactionId) {
540
+ // Log for FIU reporting
541
+ }
542
+
543
+ async _notifyMerchant(_callbackUrl, _data) {
544
+ // POST callback to merchant
545
+ }
546
+ }
547
+
548
+ export default LipaNambaJourney;