@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
package/core/config.js CHANGED
@@ -1,265 +1,265 @@
1
- /**
2
- * AfriCode Framework Configuration
3
- *
4
- * Centralized configuration for the entire framework.
5
- * Provides createFramework() as the entry point for apps.
6
- *
7
- * Design:
8
- * - Single config object controls all framework behavior
9
- * - Defaults are strict and secure
10
- * - Every opt-in behavior is explicit
11
- * - Observability hooks are first-class
12
- *
13
- * @module core/config
14
- */
15
-
16
- import { frameworkLog } from './logging.js';
17
-
18
- /**
19
- * @typedef {Object} AfriCodeConfig
20
- *
21
- * @property {Object} [validation] - Validation configuration
22
- * @property {boolean} [validation.trimStrings=false] - Trim whitespace from string inputs
23
- * @property {boolean} [validation.emptyAsNullDefault=false] - Convert "" → null for nullable fields (NOT recommended)
24
- *
25
- * @property {Object} [security] - Security configuration
26
- * @property {Object} [security.csrf] - CSRF configuration
27
- * @property {boolean} [security.csrf.enabled=true] - Enable CSRF protection
28
- * @property {string[]} [security.csrf.excludePaths=[]] - Paths to exclude from CSRF
29
- * @property {string} [security.csrf.sameSite='Strict'] - SameSite cookie policy
30
- * @property {boolean} [security.csrf.secure=false] - Require HTTPS for cookies
31
- * @property {Object} [security.rateLimit] - Rate limit configuration
32
- * @property {boolean} [security.rateLimit.enabled=true] - Enable rate limiting
33
- * @property {number} [security.rateLimit.windowMs=60000] - Window in milliseconds
34
- * @property {number} [security.rateLimit.maxRequests=60] - Max requests per window
35
- * @property {string[]} [security.rateLimit.excludePaths=[]] - Paths to exclude
36
- *
37
- * @property {Object} [hooks] - Observability hooks
38
- * @property {Function} [hooks.onValidationError] - Called on validation failure
39
- * @property {Function} [hooks.onSecurityViolation] - Called on CSRF/security failure
40
- * @property {Function} [hooks.onRateLimit] - Called when rate limit is hit
41
- * @property {Function} [hooks.onDatabaseError] - Called on database error
42
- * @property {Function} [hooks.onRequest] - Called on every incoming request
43
- */
44
-
45
- /**
46
- * Default configuration values.
47
- * Strict by default. Secure by default.
48
- */
49
- const DEFAULT_CONFIG = {
50
- validation: {
51
- trimStrings: false,
52
- emptyAsNullDefault: false
53
- },
54
- security: {
55
- csrf: {
56
- enabled: true,
57
- excludePaths: [],
58
- sameSite: 'Strict',
59
- secure: false
60
- },
61
- rateLimit: {
62
- enabled: true,
63
- windowMs: 60 * 1000,
64
- maxRequests: 60,
65
- excludePaths: []
66
- }
67
- },
68
- hooks: {
69
- onValidationError: null,
70
- onSecurityViolation: null,
71
- onRateLimit: null,
72
- onDatabaseError: null,
73
- onRequest: null
74
- }
75
- };
76
-
77
- /** @type {AfriCodeConfig} */
78
- let _config = deepClone(DEFAULT_CONFIG);
79
-
80
- /** @type {boolean} */
81
- let _initialized = false;
82
-
83
- /**
84
- * Deep clone a plain object.
85
- * @param {Object} obj
86
- * @returns {Object}
87
- */
88
- function deepClone(obj) {
89
- if (obj === null || typeof obj !== 'object') {return obj;}
90
- if (Array.isArray(obj)) {return obj.map(deepClone);}
91
- const cloned = {};
92
- for (const key of Object.keys(obj)) {
93
- cloned[key] = deepClone(obj[key]);
94
- }
95
- return cloned;
96
- }
97
-
98
- /**
99
- * Deep merge source into target.
100
- * @param {Object} target
101
- * @param {Object} source
102
- * @returns {Object}
103
- */
104
- function deepMerge(target, source) {
105
- const result = { ...target };
106
- for (const key of Object.keys(source)) {
107
- if (
108
- source[key] !== null &&
109
- typeof source[key] === 'object' &&
110
- !Array.isArray(source[key]) &&
111
- typeof target[key] === 'object' &&
112
- !Array.isArray(target[key])
113
- ) {
114
- result[key] = deepMerge(target[key] || {}, source[key]);
115
- } else {
116
- result[key] = source[key];
117
- }
118
- }
119
- return result;
120
- }
121
-
122
- /**
123
- * Initialize the AfriCode framework with configuration.
124
- *
125
- * This is the single entry point for framework configuration.
126
- * Call once at app startup. All systems read from this config.
127
- *
128
- * @param {Partial<AfriCodeConfig>} [userConfig={}] - User overrides
129
- * @returns {AfriCodeConfig} The resolved configuration
130
- *
131
- * @example
132
- * import { createFramework } from 'africode/core/config';
133
- *
134
- * createFramework({
135
- * validation: {
136
- * trimStrings: true
137
- * },
138
- * security: {
139
- * csrf: { enabled: true, secure: true },
140
- * rateLimit: { maxRequests: 100 }
141
- * },
142
- * hooks: {
143
- * onValidationError: (error) => logger.warn('Validation:', error),
144
- * onSecurityViolation: (error) => logger.error('Security:', error),
145
- * onRateLimit: (key) => metrics.increment('rate_limit_hit')
146
- * }
147
- * });
148
- */
149
- export function createFramework(userConfig = {}) {
150
- _config = deepMerge(DEFAULT_CONFIG, userConfig);
151
- _initialized = true;
152
- return getConfig();
153
- }
154
-
155
- /**
156
- * Get the current framework configuration.
157
- * Returns a frozen copy to prevent accidental mutation.
158
- *
159
- * @returns {AfriCodeConfig}
160
- */
161
- export function getConfig() {
162
- return Object.freeze(deepClone(_config));
163
- }
164
-
165
- /**
166
- * Check if the framework has been initialized.
167
- * @returns {boolean}
168
- */
169
- export function isInitialized() {
170
- return _initialized;
171
- }
172
-
173
- /**
174
- * Reset configuration to defaults.
175
- * Primarily for testing.
176
- */
177
- export function resetConfig() {
178
- _config = deepClone(DEFAULT_CONFIG);
179
- _initialized = false;
180
- }
181
-
182
- // ─────────────────────────────────────────────────────────────
183
- // Observability Hooks — fire-and-forget event emitters
184
- //
185
- // These are framework-level hooks for monitoring and logging.
186
- // They never throw — errors in hooks are caught and logged.
187
- // ─────────────────────────────────────────────────────────────
188
-
189
- /**
190
- * Emit a validation error event.
191
- * @param {import('./errors.js').ValidationError} error
192
- */
193
- export function emitValidationError(error) {
194
- const hook = _config.hooks?.onValidationError;
195
- if (typeof hook === 'function') {
196
- try { hook(error); } catch (e) {
197
- frameworkLog('error', '[AfriCode] Hook error in onValidationError:', e);
198
- }
199
- }
200
- }
201
-
202
- /**
203
- * Emit a security violation event.
204
- * @param {import('./errors.js').SecurityError} error
205
- */
206
- export function emitSecurityViolation(error) {
207
- const hook = _config.hooks?.onSecurityViolation;
208
- if (typeof hook === 'function') {
209
- try { hook(error); } catch (e) {
210
- frameworkLog('error', '[AfriCode] Hook error in onSecurityViolation:', e);
211
- }
212
- }
213
- }
214
-
215
- /**
216
- * Emit a rate limit event.
217
- * @param {string} key - The client identifier that was rate limited
218
- * @param {Request} [request] - The request that triggered the limit
219
- */
220
- export function emitRateLimit(key, request = null) {
221
- const hook = _config.hooks?.onRateLimit;
222
- if (typeof hook === 'function') {
223
- try { hook(key, request); } catch (e) {
224
- frameworkLog('error', '[AfriCode] Hook error in onRateLimit:', e);
225
- }
226
- }
227
- }
228
-
229
- /**
230
- * Emit a database error event.
231
- * @param {import('./errors.js').DatabaseError} error
232
- */
233
- export function emitDatabaseError(error) {
234
- const hook = _config.hooks?.onDatabaseError;
235
- if (typeof hook === 'function') {
236
- try { hook(error); } catch (e) {
237
- frameworkLog('error', '[AfriCode] Hook error in onDatabaseError:', e);
238
- }
239
- }
240
- }
241
-
242
- /**
243
- * Emit a request event.
244
- * @param {Request} request
245
- */
246
- export function emitRequest(request) {
247
- const hook = _config.hooks?.onRequest;
248
- if (typeof hook === 'function') {
249
- try { hook(request); } catch (e) {
250
- frameworkLog('error', '[AfriCode] Hook error in onRequest:', e);
251
- }
252
- }
253
- }
254
-
255
- export default {
256
- createFramework,
257
- getConfig,
258
- isInitialized,
259
- resetConfig,
260
- emitValidationError,
261
- emitSecurityViolation,
262
- emitRateLimit,
263
- emitDatabaseError,
264
- emitRequest
265
- };
1
+ /**
2
+ * AfriCode Framework Configuration
3
+ *
4
+ * Centralized configuration for the entire framework.
5
+ * Provides createFramework() as the entry point for apps.
6
+ *
7
+ * Design:
8
+ * - Single config object controls all framework behavior
9
+ * - Defaults are strict and secure
10
+ * - Every opt-in behavior is explicit
11
+ * - Observability hooks are first-class
12
+ *
13
+ * @module core/config
14
+ */
15
+
16
+ import { frameworkLog } from './logging.js';
17
+
18
+ /**
19
+ * @typedef {Object} AfriCodeConfig
20
+ *
21
+ * @property {Object} [validation] - Validation configuration
22
+ * @property {boolean} [validation.trimStrings=false] - Trim whitespace from string inputs
23
+ * @property {boolean} [validation.emptyAsNullDefault=false] - Convert "" → null for nullable fields (NOT recommended)
24
+ *
25
+ * @property {Object} [security] - Security configuration
26
+ * @property {Object} [security.csrf] - CSRF configuration
27
+ * @property {boolean} [security.csrf.enabled=true] - Enable CSRF protection
28
+ * @property {string[]} [security.csrf.excludePaths=[]] - Paths to exclude from CSRF
29
+ * @property {string} [security.csrf.sameSite='Strict'] - SameSite cookie policy
30
+ * @property {boolean} [security.csrf.secure=false] - Require HTTPS for cookies
31
+ * @property {Object} [security.rateLimit] - Rate limit configuration
32
+ * @property {boolean} [security.rateLimit.enabled=true] - Enable rate limiting
33
+ * @property {number} [security.rateLimit.windowMs=60000] - Window in milliseconds
34
+ * @property {number} [security.rateLimit.maxRequests=60] - Max requests per window
35
+ * @property {string[]} [security.rateLimit.excludePaths=[]] - Paths to exclude
36
+ *
37
+ * @property {Object} [hooks] - Observability hooks
38
+ * @property {Function} [hooks.onValidationError] - Called on validation failure
39
+ * @property {Function} [hooks.onSecurityViolation] - Called on CSRF/security failure
40
+ * @property {Function} [hooks.onRateLimit] - Called when rate limit is hit
41
+ * @property {Function} [hooks.onDatabaseError] - Called on database error
42
+ * @property {Function} [hooks.onRequest] - Called on every incoming request
43
+ */
44
+
45
+ /**
46
+ * Default configuration values.
47
+ * Strict by default. Secure by default.
48
+ */
49
+ const DEFAULT_CONFIG = {
50
+ validation: {
51
+ trimStrings: false,
52
+ emptyAsNullDefault: false
53
+ },
54
+ security: {
55
+ csrf: {
56
+ enabled: true,
57
+ excludePaths: [],
58
+ sameSite: 'Strict',
59
+ secure: false
60
+ },
61
+ rateLimit: {
62
+ enabled: true,
63
+ windowMs: 60 * 1000,
64
+ maxRequests: 60,
65
+ excludePaths: []
66
+ }
67
+ },
68
+ hooks: {
69
+ onValidationError: null,
70
+ onSecurityViolation: null,
71
+ onRateLimit: null,
72
+ onDatabaseError: null,
73
+ onRequest: null
74
+ }
75
+ };
76
+
77
+ /** @type {AfriCodeConfig} */
78
+ let _config = deepClone(DEFAULT_CONFIG);
79
+
80
+ /** @type {boolean} */
81
+ let _initialized = false;
82
+
83
+ /**
84
+ * Deep clone a plain object.
85
+ * @param {Object} obj
86
+ * @returns {Object}
87
+ */
88
+ function deepClone(obj) {
89
+ if (obj === null || typeof obj !== 'object') {return obj;}
90
+ if (Array.isArray(obj)) {return obj.map(deepClone);}
91
+ const cloned = {};
92
+ for (const key of Object.keys(obj)) {
93
+ cloned[key] = deepClone(obj[key]);
94
+ }
95
+ return cloned;
96
+ }
97
+
98
+ /**
99
+ * Deep merge source into target.
100
+ * @param {Object} target
101
+ * @param {Object} source
102
+ * @returns {Object}
103
+ */
104
+ function deepMerge(target, source) {
105
+ const result = { ...target };
106
+ for (const key of Object.keys(source)) {
107
+ if (
108
+ source[key] !== null &&
109
+ typeof source[key] === 'object' &&
110
+ !Array.isArray(source[key]) &&
111
+ typeof target[key] === 'object' &&
112
+ !Array.isArray(target[key])
113
+ ) {
114
+ result[key] = deepMerge(target[key] || {}, source[key]);
115
+ } else {
116
+ result[key] = source[key];
117
+ }
118
+ }
119
+ return result;
120
+ }
121
+
122
+ /**
123
+ * Initialize the AfriCode framework with configuration.
124
+ *
125
+ * This is the single entry point for framework configuration.
126
+ * Call once at app startup. All systems read from this config.
127
+ *
128
+ * @param {Partial<AfriCodeConfig>} [userConfig={}] - User overrides
129
+ * @returns {AfriCodeConfig} The resolved configuration
130
+ *
131
+ * @example
132
+ * import { createFramework } from 'africode/core/config';
133
+ *
134
+ * createFramework({
135
+ * validation: {
136
+ * trimStrings: true
137
+ * },
138
+ * security: {
139
+ * csrf: { enabled: true, secure: true },
140
+ * rateLimit: { maxRequests: 100 }
141
+ * },
142
+ * hooks: {
143
+ * onValidationError: (error) => logger.warn('Validation:', error),
144
+ * onSecurityViolation: (error) => logger.error('Security:', error),
145
+ * onRateLimit: (key) => metrics.increment('rate_limit_hit')
146
+ * }
147
+ * });
148
+ */
149
+ export function createFramework(userConfig = {}) {
150
+ _config = deepMerge(DEFAULT_CONFIG, userConfig);
151
+ _initialized = true;
152
+ return getConfig();
153
+ }
154
+
155
+ /**
156
+ * Get the current framework configuration.
157
+ * Returns a frozen copy to prevent accidental mutation.
158
+ *
159
+ * @returns {AfriCodeConfig}
160
+ */
161
+ export function getConfig() {
162
+ return Object.freeze(deepClone(_config));
163
+ }
164
+
165
+ /**
166
+ * Check if the framework has been initialized.
167
+ * @returns {boolean}
168
+ */
169
+ export function isInitialized() {
170
+ return _initialized;
171
+ }
172
+
173
+ /**
174
+ * Reset configuration to defaults.
175
+ * Primarily for testing.
176
+ */
177
+ export function resetConfig() {
178
+ _config = deepClone(DEFAULT_CONFIG);
179
+ _initialized = false;
180
+ }
181
+
182
+ // ─────────────────────────────────────────────────────────────
183
+ // Observability Hooks — fire-and-forget event emitters
184
+ //
185
+ // These are framework-level hooks for monitoring and logging.
186
+ // They never throw — errors in hooks are caught and logged.
187
+ // ─────────────────────────────────────────────────────────────
188
+
189
+ /**
190
+ * Emit a validation error event.
191
+ * @param {import('./errors.js').ValidationError} error
192
+ */
193
+ export function emitValidationError(error) {
194
+ const hook = _config.hooks?.onValidationError;
195
+ if (typeof hook === 'function') {
196
+ try { hook(error); } catch (e) {
197
+ frameworkLog('error', '[AfriCode] Hook error in onValidationError:', e);
198
+ }
199
+ }
200
+ }
201
+
202
+ /**
203
+ * Emit a security violation event.
204
+ * @param {import('./errors.js').SecurityError} error
205
+ */
206
+ export function emitSecurityViolation(error) {
207
+ const hook = _config.hooks?.onSecurityViolation;
208
+ if (typeof hook === 'function') {
209
+ try { hook(error); } catch (e) {
210
+ frameworkLog('error', '[AfriCode] Hook error in onSecurityViolation:', e);
211
+ }
212
+ }
213
+ }
214
+
215
+ /**
216
+ * Emit a rate limit event.
217
+ * @param {string} key - The client identifier that was rate limited
218
+ * @param {Request} [request] - The request that triggered the limit
219
+ */
220
+ export function emitRateLimit(key, request = null) {
221
+ const hook = _config.hooks?.onRateLimit;
222
+ if (typeof hook === 'function') {
223
+ try { hook(key, request); } catch (e) {
224
+ frameworkLog('error', '[AfriCode] Hook error in onRateLimit:', e);
225
+ }
226
+ }
227
+ }
228
+
229
+ /**
230
+ * Emit a database error event.
231
+ * @param {import('./errors.js').DatabaseError} error
232
+ */
233
+ export function emitDatabaseError(error) {
234
+ const hook = _config.hooks?.onDatabaseError;
235
+ if (typeof hook === 'function') {
236
+ try { hook(error); } catch (e) {
237
+ frameworkLog('error', '[AfriCode] Hook error in onDatabaseError:', e);
238
+ }
239
+ }
240
+ }
241
+
242
+ /**
243
+ * Emit a request event.
244
+ * @param {Request} request
245
+ */
246
+ export function emitRequest(request) {
247
+ const hook = _config.hooks?.onRequest;
248
+ if (typeof hook === 'function') {
249
+ try { hook(request); } catch (e) {
250
+ frameworkLog('error', '[AfriCode] Hook error in onRequest:', e);
251
+ }
252
+ }
253
+ }
254
+
255
+ export default {
256
+ createFramework,
257
+ getConfig,
258
+ isInitialized,
259
+ resetConfig,
260
+ emitValidationError,
261
+ emitSecurityViolation,
262
+ emitRateLimit,
263
+ emitDatabaseError,
264
+ emitRequest
265
+ };