@nodestackapp/server 0.0.0-stage → 2.0.0

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 (361) hide show
  1. package/LICENSE +36 -0
  2. package/README.md +182 -3
  3. package/bin/nodebase.js +4 -0
  4. package/bin/nodestack.js +21 -0
  5. package/dist/NodeBase.d.ts +2 -0
  6. package/dist/NodeBase.d.ts.map +1 -0
  7. package/dist/NodeBase.js +8 -0
  8. package/dist/NodeBase.js.map +1 -0
  9. package/dist/NodeStack.d.ts +111 -0
  10. package/dist/NodeStack.d.ts.map +1 -0
  11. package/dist/NodeStack.js +316 -0
  12. package/dist/NodeStack.js.map +1 -0
  13. package/dist/admin/AdminUIBundler.d.ts +8 -0
  14. package/dist/admin/AdminUIBundler.d.ts.map +1 -0
  15. package/dist/admin/AdminUIBundler.js +104 -0
  16. package/dist/admin/AdminUIBundler.js.map +1 -0
  17. package/dist/admin/AdminUIService.d.ts +30 -0
  18. package/dist/admin/AdminUIService.d.ts.map +1 -0
  19. package/dist/admin/AdminUIService.js +210 -0
  20. package/dist/admin/AdminUIService.js.map +1 -0
  21. package/dist/admin/DocsService.d.ts +29 -0
  22. package/dist/admin/DocsService.d.ts.map +1 -0
  23. package/dist/admin/DocsService.js +564 -0
  24. package/dist/admin/DocsService.js.map +1 -0
  25. package/dist/admin/ui/css/analytics.css +382 -0
  26. package/dist/admin/ui/css/main.css +2189 -0
  27. package/dist/admin/ui/css/rules.css +292 -0
  28. package/dist/admin/ui/css/webhooks.css +360 -0
  29. package/dist/admin/ui/favicon.svg +17 -0
  30. package/dist/admin/ui/icon.svg +17 -0
  31. package/dist/admin/ui/index.html +15168 -0
  32. package/dist/admin/ui/js/analytics.js +673 -0
  33. package/dist/admin/ui/js/api.js +369 -0
  34. package/dist/admin/ui/js/app.js +254 -0
  35. package/dist/admin/ui/js/apps.js +454 -0
  36. package/dist/admin/ui/js/collections.js +435 -0
  37. package/dist/admin/ui/js/command-palette.js +631 -0
  38. package/dist/admin/ui/js/demo.js +661 -0
  39. package/dist/admin/ui/js/modals.js +2379 -0
  40. package/dist/admin/ui/js/plugin-tester.js +559 -0
  41. package/dist/admin/ui/js/plugins.js +778 -0
  42. package/dist/admin/ui/js/records.js +1270 -0
  43. package/dist/admin/ui/js/rules.js +775 -0
  44. package/dist/admin/ui/js/schema.js +290 -0
  45. package/dist/admin/ui/js/state.js +140 -0
  46. package/dist/admin/ui/js/theme.js +120 -0
  47. package/dist/admin/ui/js/views.js +632 -0
  48. package/dist/admin/ui/js/webhooks.js +1104 -0
  49. package/dist/analytics/AnalyticsService.d.ts +62 -0
  50. package/dist/analytics/AnalyticsService.d.ts.map +1 -0
  51. package/dist/analytics/AnalyticsService.js +196 -0
  52. package/dist/analytics/AnalyticsService.js.map +1 -0
  53. package/dist/apps/AppManager.d.ts +28 -0
  54. package/dist/apps/AppManager.d.ts.map +1 -0
  55. package/dist/apps/AppManager.js +211 -0
  56. package/dist/apps/AppManager.js.map +1 -0
  57. package/dist/apps/AppRegistry.d.ts +27 -0
  58. package/dist/apps/AppRegistry.d.ts.map +1 -0
  59. package/dist/apps/AppRegistry.js +220 -0
  60. package/dist/apps/AppRegistry.js.map +1 -0
  61. package/dist/apps/AppScope.d.ts +57 -0
  62. package/dist/apps/AppScope.d.ts.map +1 -0
  63. package/dist/apps/AppScope.js +299 -0
  64. package/dist/apps/AppScope.js.map +1 -0
  65. package/dist/apps/index.d.ts +5 -0
  66. package/dist/apps/index.d.ts.map +1 -0
  67. package/dist/apps/index.js +21 -0
  68. package/dist/apps/index.js.map +1 -0
  69. package/dist/apps/models/App.d.ts +29 -0
  70. package/dist/apps/models/App.d.ts.map +1 -0
  71. package/dist/apps/models/App.js +3 -0
  72. package/dist/apps/models/App.js.map +1 -0
  73. package/dist/audit/AuditLogService.d.ts +68 -0
  74. package/dist/audit/AuditLogService.d.ts.map +1 -0
  75. package/dist/audit/AuditLogService.js +243 -0
  76. package/dist/audit/AuditLogService.js.map +1 -0
  77. package/dist/auth/AuthService.d.ts +35 -0
  78. package/dist/auth/AuthService.d.ts.map +1 -0
  79. package/dist/auth/AuthService.js +303 -0
  80. package/dist/auth/AuthService.js.map +1 -0
  81. package/dist/cli/cli.d.ts +3 -0
  82. package/dist/cli/cli.d.ts.map +1 -0
  83. package/dist/cli/cli.js +541 -0
  84. package/dist/cli/cli.js.map +1 -0
  85. package/dist/core/config/ConfigService.d.ts +42 -0
  86. package/dist/core/config/ConfigService.d.ts.map +1 -0
  87. package/dist/core/config/ConfigService.js +142 -0
  88. package/dist/core/config/ConfigService.js.map +1 -0
  89. package/dist/core/config/EnvLoader.d.ts +7 -0
  90. package/dist/core/config/EnvLoader.d.ts.map +1 -0
  91. package/dist/core/config/EnvLoader.js +84 -0
  92. package/dist/core/config/EnvLoader.js.map +1 -0
  93. package/dist/core/container/Container.d.ts +34 -0
  94. package/dist/core/container/Container.d.ts.map +1 -0
  95. package/dist/core/container/Container.js +98 -0
  96. package/dist/core/container/Container.js.map +1 -0
  97. package/dist/core/container/Tokens.d.ts +42 -0
  98. package/dist/core/container/Tokens.d.ts.map +1 -0
  99. package/dist/core/container/Tokens.js +42 -0
  100. package/dist/core/container/Tokens.js.map +1 -0
  101. package/dist/core/errors/AppError.d.ts +24 -0
  102. package/dist/core/errors/AppError.d.ts.map +1 -0
  103. package/dist/core/errors/AppError.js +52 -0
  104. package/dist/core/errors/AppError.js.map +1 -0
  105. package/dist/core/events/EventBus.d.ts +45 -0
  106. package/dist/core/events/EventBus.d.ts.map +1 -0
  107. package/dist/core/events/EventBus.js +360 -0
  108. package/dist/core/events/EventBus.js.map +1 -0
  109. package/dist/core/events/types.d.ts +35 -0
  110. package/dist/core/events/types.d.ts.map +1 -0
  111. package/dist/core/events/types.js +3 -0
  112. package/dist/core/events/types.js.map +1 -0
  113. package/dist/core/maintenance/MaintenanceGate.d.ts +65 -0
  114. package/dist/core/maintenance/MaintenanceGate.d.ts.map +1 -0
  115. package/dist/core/maintenance/MaintenanceGate.js +162 -0
  116. package/dist/core/maintenance/MaintenanceGate.js.map +1 -0
  117. package/dist/core/plugins/PluginManager.d.ts +150 -0
  118. package/dist/core/plugins/PluginManager.d.ts.map +1 -0
  119. package/dist/core/plugins/PluginManager.js +1592 -0
  120. package/dist/core/plugins/PluginManager.js.map +1 -0
  121. package/dist/core/plugins/types.d.ts +170 -0
  122. package/dist/core/plugins/types.d.ts.map +1 -0
  123. package/dist/core/plugins/types.js +3 -0
  124. package/dist/core/plugins/types.js.map +1 -0
  125. package/dist/database/DatabaseService.d.ts +27 -0
  126. package/dist/database/DatabaseService.d.ts.map +1 -0
  127. package/dist/database/DatabaseService.js +97 -0
  128. package/dist/database/DatabaseService.js.map +1 -0
  129. package/dist/database/drivers/IDatabaseDriver.d.ts +17 -0
  130. package/dist/database/drivers/IDatabaseDriver.d.ts.map +1 -0
  131. package/dist/database/drivers/IDatabaseDriver.js +3 -0
  132. package/dist/database/drivers/IDatabaseDriver.js.map +1 -0
  133. package/dist/database/drivers/NodeSqliteDriver.d.ts +16 -0
  134. package/dist/database/drivers/NodeSqliteDriver.d.ts.map +1 -0
  135. package/dist/database/drivers/NodeSqliteDriver.js +115 -0
  136. package/dist/database/drivers/NodeSqliteDriver.js.map +1 -0
  137. package/dist/database/migrations/SystemMigrations.d.ts +5 -0
  138. package/dist/database/migrations/SystemMigrations.d.ts.map +1 -0
  139. package/dist/database/migrations/SystemMigrations.js +164 -0
  140. package/dist/database/migrations/SystemMigrations.js.map +1 -0
  141. package/dist/demo/DemoService.d.ts +27 -0
  142. package/dist/demo/DemoService.d.ts.map +1 -0
  143. package/dist/demo/DemoService.js +22 -0
  144. package/dist/demo/DemoService.js.map +1 -0
  145. package/dist/files/FileStorageService.d.ts +35 -0
  146. package/dist/files/FileStorageService.d.ts.map +1 -0
  147. package/dist/files/FileStorageService.js +126 -0
  148. package/dist/files/FileStorageService.js.map +1 -0
  149. package/dist/http/HttpServer.d.ts +63 -0
  150. package/dist/http/HttpServer.d.ts.map +1 -0
  151. package/dist/http/HttpServer.js +513 -0
  152. package/dist/http/HttpServer.js.map +1 -0
  153. package/dist/http/controllers/AnalyticsController.d.ts +9 -0
  154. package/dist/http/controllers/AnalyticsController.d.ts.map +1 -0
  155. package/dist/http/controllers/AnalyticsController.js +18 -0
  156. package/dist/http/controllers/AnalyticsController.js.map +1 -0
  157. package/dist/http/controllers/AppController.d.ts +29 -0
  158. package/dist/http/controllers/AppController.d.ts.map +1 -0
  159. package/dist/http/controllers/AppController.js +36 -0
  160. package/dist/http/controllers/AppController.js.map +1 -0
  161. package/dist/http/controllers/AuditLogController.d.ts +26 -0
  162. package/dist/http/controllers/AuditLogController.d.ts.map +1 -0
  163. package/dist/http/controllers/AuditLogController.js +32 -0
  164. package/dist/http/controllers/AuditLogController.js.map +1 -0
  165. package/dist/http/controllers/AuthController.d.ts +18 -0
  166. package/dist/http/controllers/AuthController.d.ts.map +1 -0
  167. package/dist/http/controllers/AuthController.js +84 -0
  168. package/dist/http/controllers/AuthController.js.map +1 -0
  169. package/dist/http/controllers/BaseController.d.ts +7 -0
  170. package/dist/http/controllers/BaseController.d.ts.map +1 -0
  171. package/dist/http/controllers/BaseController.js +20 -0
  172. package/dist/http/controllers/BaseController.js.map +1 -0
  173. package/dist/http/controllers/CollectionController.d.ts +44 -0
  174. package/dist/http/controllers/CollectionController.d.ts.map +1 -0
  175. package/dist/http/controllers/CollectionController.js +89 -0
  176. package/dist/http/controllers/CollectionController.js.map +1 -0
  177. package/dist/http/controllers/DemoController.d.ts +34 -0
  178. package/dist/http/controllers/DemoController.d.ts.map +1 -0
  179. package/dist/http/controllers/DemoController.js +56 -0
  180. package/dist/http/controllers/DemoController.js.map +1 -0
  181. package/dist/http/controllers/FileController.d.ts +29 -0
  182. package/dist/http/controllers/FileController.d.ts.map +1 -0
  183. package/dist/http/controllers/FileController.js +172 -0
  184. package/dist/http/controllers/FileController.js.map +1 -0
  185. package/dist/http/controllers/HealthController.d.ts +10 -0
  186. package/dist/http/controllers/HealthController.d.ts.map +1 -0
  187. package/dist/http/controllers/HealthController.js +28 -0
  188. package/dist/http/controllers/HealthController.js.map +1 -0
  189. package/dist/http/controllers/LogController.d.ts +15 -0
  190. package/dist/http/controllers/LogController.d.ts.map +1 -0
  191. package/dist/http/controllers/LogController.js +25 -0
  192. package/dist/http/controllers/LogController.js.map +1 -0
  193. package/dist/http/controllers/RealtimeController.d.ts +13 -0
  194. package/dist/http/controllers/RealtimeController.d.ts.map +1 -0
  195. package/dist/http/controllers/RealtimeController.js +54 -0
  196. package/dist/http/controllers/RealtimeController.js.map +1 -0
  197. package/dist/http/controllers/RecordController.d.ts +74 -0
  198. package/dist/http/controllers/RecordController.d.ts.map +1 -0
  199. package/dist/http/controllers/RecordController.js +202 -0
  200. package/dist/http/controllers/RecordController.js.map +1 -0
  201. package/dist/http/controllers/SnapshotController.d.ts +58 -0
  202. package/dist/http/controllers/SnapshotController.d.ts.map +1 -0
  203. package/dist/http/controllers/SnapshotController.js +79 -0
  204. package/dist/http/controllers/SnapshotController.js.map +1 -0
  205. package/dist/http/controllers/TemplateController.d.ts +29 -0
  206. package/dist/http/controllers/TemplateController.d.ts.map +1 -0
  207. package/dist/http/controllers/TemplateController.js +63 -0
  208. package/dist/http/controllers/TemplateController.js.map +1 -0
  209. package/dist/http/controllers/WebhookController.d.ts +78 -0
  210. package/dist/http/controllers/WebhookController.d.ts.map +1 -0
  211. package/dist/http/controllers/WebhookController.js +113 -0
  212. package/dist/http/controllers/WebhookController.js.map +1 -0
  213. package/dist/http/middleware/AppResolutionMiddleware.d.ts +8 -0
  214. package/dist/http/middleware/AppResolutionMiddleware.d.ts.map +1 -0
  215. package/dist/http/middleware/AppResolutionMiddleware.js +98 -0
  216. package/dist/http/middleware/AppResolutionMiddleware.js.map +1 -0
  217. package/dist/http/middleware/AuthMiddleware.d.ts +17 -0
  218. package/dist/http/middleware/AuthMiddleware.d.ts.map +1 -0
  219. package/dist/http/middleware/AuthMiddleware.js +97 -0
  220. package/dist/http/middleware/AuthMiddleware.js.map +1 -0
  221. package/dist/http/middleware/ChaosMiddleware.d.ts +130 -0
  222. package/dist/http/middleware/ChaosMiddleware.d.ts.map +1 -0
  223. package/dist/http/middleware/ChaosMiddleware.js +434 -0
  224. package/dist/http/middleware/ChaosMiddleware.js.map +1 -0
  225. package/dist/index.d.ts +55 -0
  226. package/dist/index.d.ts.map +1 -0
  227. package/dist/index.js +147 -0
  228. package/dist/index.js.map +1 -0
  229. package/dist/logger/LogService.d.ts +31 -0
  230. package/dist/logger/LogService.d.ts.map +1 -0
  231. package/dist/logger/LogService.js +104 -0
  232. package/dist/logger/LogService.js.map +1 -0
  233. package/dist/plugins/algolia.d.ts +76 -0
  234. package/dist/plugins/algolia.d.ts.map +1 -0
  235. package/dist/plugins/algolia.js +532 -0
  236. package/dist/plugins/algolia.js.map +1 -0
  237. package/dist/plugins/index.d.ts +6 -0
  238. package/dist/plugins/index.d.ts.map +1 -0
  239. package/dist/plugins/index.js +22 -0
  240. package/dist/plugins/index.js.map +1 -0
  241. package/dist/plugins/resend.d.ts +42 -0
  242. package/dist/plugins/resend.d.ts.map +1 -0
  243. package/dist/plugins/resend.js +335 -0
  244. package/dist/plugins/resend.js.map +1 -0
  245. package/dist/plugins/s3.d.ts +35 -0
  246. package/dist/plugins/s3.d.ts.map +1 -0
  247. package/dist/plugins/s3.js +425 -0
  248. package/dist/plugins/s3.js.map +1 -0
  249. package/dist/plugins/stripe.d.ts +45 -0
  250. package/dist/plugins/stripe.d.ts.map +1 -0
  251. package/dist/plugins/stripe.js +470 -0
  252. package/dist/plugins/stripe.js.map +1 -0
  253. package/dist/plugins/webhooks.d.ts +35 -0
  254. package/dist/plugins/webhooks.d.ts.map +1 -0
  255. package/dist/plugins/webhooks.js +415 -0
  256. package/dist/plugins/webhooks.js.map +1 -0
  257. package/dist/realtime/RealtimeService.d.ts +26 -0
  258. package/dist/realtime/RealtimeService.d.ts.map +1 -0
  259. package/dist/realtime/RealtimeService.js +165 -0
  260. package/dist/realtime/RealtimeService.js.map +1 -0
  261. package/dist/records/CsvHelper.d.ts +27 -0
  262. package/dist/records/CsvHelper.d.ts.map +1 -0
  263. package/dist/records/CsvHelper.js +195 -0
  264. package/dist/records/CsvHelper.js.map +1 -0
  265. package/dist/records/FakerEngine.d.ts +73 -0
  266. package/dist/records/FakerEngine.d.ts.map +1 -0
  267. package/dist/records/FakerEngine.js +644 -0
  268. package/dist/records/FakerEngine.js.map +1 -0
  269. package/dist/records/FilterCodec.d.ts +22 -0
  270. package/dist/records/FilterCodec.d.ts.map +1 -0
  271. package/dist/records/FilterCodec.js +57 -0
  272. package/dist/records/FilterCodec.js.map +1 -0
  273. package/dist/records/FtsService.d.ts +63 -0
  274. package/dist/records/FtsService.d.ts.map +1 -0
  275. package/dist/records/FtsService.js +310 -0
  276. package/dist/records/FtsService.js.map +1 -0
  277. package/dist/records/MockDataService.d.ts +31 -0
  278. package/dist/records/MockDataService.d.ts.map +1 -0
  279. package/dist/records/MockDataService.js +222 -0
  280. package/dist/records/MockDataService.js.map +1 -0
  281. package/dist/records/QueryFilterParser.d.ts +35 -0
  282. package/dist/records/QueryFilterParser.d.ts.map +1 -0
  283. package/dist/records/QueryFilterParser.js +263 -0
  284. package/dist/records/QueryFilterParser.js.map +1 -0
  285. package/dist/records/RecordService.d.ts +77 -0
  286. package/dist/records/RecordService.d.ts.map +1 -0
  287. package/dist/records/RecordService.js +704 -0
  288. package/dist/records/RecordService.js.map +1 -0
  289. package/dist/rules/RuleBuilder.d.ts +72 -0
  290. package/dist/rules/RuleBuilder.d.ts.map +1 -0
  291. package/dist/rules/RuleBuilder.js +383 -0
  292. package/dist/rules/RuleBuilder.js.map +1 -0
  293. package/dist/rules/RuleEngine.d.ts +42 -0
  294. package/dist/rules/RuleEngine.d.ts.map +1 -0
  295. package/dist/rules/RuleEngine.js +347 -0
  296. package/dist/rules/RuleEngine.js.map +1 -0
  297. package/dist/schema/OpenApiGenerator.d.ts +32 -0
  298. package/dist/schema/OpenApiGenerator.d.ts.map +1 -0
  299. package/dist/schema/OpenApiGenerator.js +1836 -0
  300. package/dist/schema/OpenApiGenerator.js.map +1 -0
  301. package/dist/schema/SchemaInferenceService.d.ts +82 -0
  302. package/dist/schema/SchemaInferenceService.d.ts.map +1 -0
  303. package/dist/schema/SchemaInferenceService.js +622 -0
  304. package/dist/schema/SchemaInferenceService.js.map +1 -0
  305. package/dist/schema/SchemaService.d.ts +33 -0
  306. package/dist/schema/SchemaService.d.ts.map +1 -0
  307. package/dist/schema/SchemaService.js +338 -0
  308. package/dist/schema/SchemaService.js.map +1 -0
  309. package/dist/schema/TypeGenerator.d.ts +19 -0
  310. package/dist/schema/TypeGenerator.d.ts.map +1 -0
  311. package/dist/schema/TypeGenerator.js +173 -0
  312. package/dist/schema/TypeGenerator.js.map +1 -0
  313. package/dist/schema/models/Collection.d.ts +44 -0
  314. package/dist/schema/models/Collection.d.ts.map +1 -0
  315. package/dist/schema/models/Collection.js +3 -0
  316. package/dist/schema/models/Collection.js.map +1 -0
  317. package/dist/schema/models/Field.d.ts +25 -0
  318. package/dist/schema/models/Field.d.ts.map +1 -0
  319. package/dist/schema/models/Field.js +3 -0
  320. package/dist/schema/models/Field.js.map +1 -0
  321. package/dist/snapshots/SnapshotService.d.ts +75 -0
  322. package/dist/snapshots/SnapshotService.d.ts.map +1 -0
  323. package/dist/snapshots/SnapshotService.js +775 -0
  324. package/dist/snapshots/SnapshotService.js.map +1 -0
  325. package/dist/snapshots/types.d.ts +63 -0
  326. package/dist/snapshots/types.d.ts.map +1 -0
  327. package/dist/snapshots/types.js +5 -0
  328. package/dist/snapshots/types.js.map +1 -0
  329. package/dist/templates/TemplateImageGenerator.d.ts +43 -0
  330. package/dist/templates/TemplateImageGenerator.d.ts.map +1 -0
  331. package/dist/templates/TemplateImageGenerator.js +350 -0
  332. package/dist/templates/TemplateImageGenerator.js.map +1 -0
  333. package/dist/templates/TemplateService.d.ts +31 -0
  334. package/dist/templates/TemplateService.d.ts.map +1 -0
  335. package/dist/templates/TemplateService.js +209 -0
  336. package/dist/templates/TemplateService.js.map +1 -0
  337. package/dist/templates/definitions/blog.d.ts +3 -0
  338. package/dist/templates/definitions/blog.d.ts.map +1 -0
  339. package/dist/templates/definitions/blog.js +386 -0
  340. package/dist/templates/definitions/blog.js.map +1 -0
  341. package/dist/templates/definitions/crm.d.ts +3 -0
  342. package/dist/templates/definitions/crm.d.ts.map +1 -0
  343. package/dist/templates/definitions/crm.js +456 -0
  344. package/dist/templates/definitions/crm.js.map +1 -0
  345. package/dist/templates/definitions/ecommerce.d.ts +3 -0
  346. package/dist/templates/definitions/ecommerce.d.ts.map +1 -0
  347. package/dist/templates/definitions/ecommerce.js +781 -0
  348. package/dist/templates/definitions/ecommerce.js.map +1 -0
  349. package/dist/templates/definitions/index.d.ts +7 -0
  350. package/dist/templates/definitions/index.d.ts.map +1 -0
  351. package/dist/templates/definitions/index.js +15 -0
  352. package/dist/templates/definitions/index.js.map +1 -0
  353. package/dist/templates/types.d.ts +65 -0
  354. package/dist/templates/types.d.ts.map +1 -0
  355. package/dist/templates/types.js +3 -0
  356. package/dist/templates/types.js.map +1 -0
  357. package/dist/webhooks/WebhookService.d.ts +149 -0
  358. package/dist/webhooks/WebhookService.d.ts.map +1 -0
  359. package/dist/webhooks/WebhookService.js +781 -0
  360. package/dist/webhooks/WebhookService.js.map +1 -0
  361. package/package.json +88 -6
@@ -0,0 +1,1836 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.OpenApiGenerator = void 0;
4
+ class OpenApiGenerator {
5
+ schemaService;
6
+ defaultOptions;
7
+ constructor(schemaService, defaultOptions = {}) {
8
+ this.schemaService = schemaService;
9
+ this.defaultOptions = defaultOptions;
10
+ }
11
+ /**
12
+ * Generates the OpenAPI 3.0 specification object from the current collections schema.
13
+ */
14
+ generate(options) {
15
+ const collections = this.schemaService.getAllCollections();
16
+ return OpenApiGenerator.generateFromCollections(collections, {
17
+ ...this.defaultOptions,
18
+ ...options,
19
+ });
20
+ }
21
+ /**
22
+ * Generates formatted OpenAPI JSON string.
23
+ */
24
+ generateJson(pretty = true, options) {
25
+ const spec = this.generate(options);
26
+ return JSON.stringify(spec, null, pretty ? 2 : undefined);
27
+ }
28
+ /**
29
+ * Pure static generator that transforms a list of CollectionModel into
30
+ * a compliant OpenAPI 3.0.3 specification object.
31
+ */
32
+ static generateFromCollections(collections, options = {}) {
33
+ const title = options.title || 'NodeStack API';
34
+ const version = options.version || '2.0.0';
35
+ const description = options.description ||
36
+ 'Interactive OpenAPI 3.0 specification for NodeStack backend. Dynamically generated from collection schemas.';
37
+ const serverUrl = options.serverUrl || '/';
38
+ const isScoped = Boolean(options.appSlug && options.appSlug !== 'default');
39
+ const apiPrefix = isScoped ? `/api/apps/${options.appSlug}` : '/api';
40
+ // Filter out internal system tables (prefixed with '_' or system: true, excluding public auth 'users')
41
+ const publicCollections = collections.filter((col) => !col.name?.startsWith('_') && !(col.system && col.name !== 'users'));
42
+ const tags = [];
43
+ const paths = {};
44
+ const schemas = {};
45
+ // 1. Common Shared Schemas
46
+ schemas.ErrorResponse = {
47
+ type: 'object',
48
+ properties: {
49
+ statusCode: { type: 'integer', example: 400 },
50
+ message: { type: 'string', example: 'Validation error or invalid request' },
51
+ data: { type: 'object', additionalProperties: true },
52
+ },
53
+ required: ['statusCode', 'message'],
54
+ };
55
+ schemas.AdminModel = {
56
+ type: 'object',
57
+ properties: {
58
+ id: { type: 'string', readOnly: true, example: 'admin_123' },
59
+ email: { type: 'string', format: 'email', example: 'admin@nodestack.io' },
60
+ avatar: { type: 'string', nullable: true },
61
+ created: { type: 'string', format: 'date-time', readOnly: true },
62
+ updated: { type: 'string', format: 'date-time', readOnly: true },
63
+ },
64
+ required: ['id', 'email'],
65
+ };
66
+ schemas.AdminAuthResponse = {
67
+ type: 'object',
68
+ properties: {
69
+ token: { type: 'string', description: 'JWT authentication token' },
70
+ admin: { $ref: '#/components/schemas/AdminModel' },
71
+ },
72
+ required: ['token', 'admin'],
73
+ };
74
+ schemas.AuthWithPasswordRequest = {
75
+ type: 'object',
76
+ properties: {
77
+ identity: { type: 'string', description: 'Email address or username', example: 'user@example.com' },
78
+ password: { type: 'string', format: 'password', example: 'supersecret123' },
79
+ },
80
+ required: ['identity', 'password'],
81
+ };
82
+ schemas.CreateInitialAdminRequest = {
83
+ type: 'object',
84
+ properties: {
85
+ email: { type: 'string', format: 'email', example: 'admin@example.com' },
86
+ password: { type: 'string', format: 'password', example: 'supersecret123' },
87
+ },
88
+ required: ['email', 'password'],
89
+ };
90
+ schemas.HealthResponse = {
91
+ type: 'object',
92
+ properties: {
93
+ status: { type: 'string', example: 'ok' },
94
+ version: { type: 'string', example: '2.0.0' },
95
+ appName: { type: 'string', example: 'NodeStack' },
96
+ uptime: { type: 'number', example: 123.45 },
97
+ memory: { type: 'object', additionalProperties: true },
98
+ },
99
+ required: ['status', 'version', 'appName'],
100
+ };
101
+ schemas.SettingsResponse = {
102
+ type: 'object',
103
+ properties: {
104
+ appName: { type: 'string', example: 'NodeStack' },
105
+ version: { type: 'string', example: '2.0.0' },
106
+ },
107
+ required: ['appName', 'version'],
108
+ };
109
+ schemas.LogEntry = {
110
+ type: 'object',
111
+ properties: {
112
+ id: { type: 'string' },
113
+ created: { type: 'string', format: 'date-time' },
114
+ method: { type: 'string', example: 'GET' },
115
+ url: { type: 'string', example: '/api/health' },
116
+ status: { type: 'integer', example: 200 },
117
+ duration: { type: 'number', example: 1.25 },
118
+ ip: { type: 'string', example: '127.0.0.1' },
119
+ authId: { type: 'string', nullable: true },
120
+ authCollection: { type: 'string', nullable: true },
121
+ userAgent: { type: 'string', nullable: true },
122
+ },
123
+ };
124
+ schemas.LogListResult = {
125
+ type: 'object',
126
+ properties: {
127
+ page: { type: 'integer', example: 1 },
128
+ perPage: { type: 'integer', example: 50 },
129
+ totalItems: { type: 'integer', example: 100 },
130
+ totalPages: { type: 'integer', example: 2 },
131
+ items: {
132
+ type: 'array',
133
+ items: { $ref: '#/components/schemas/LogEntry' },
134
+ },
135
+ },
136
+ required: ['page', 'perPage', 'totalItems', 'totalPages', 'items'],
137
+ };
138
+ schemas.HourlyDataPoint = {
139
+ type: 'object',
140
+ properties: {
141
+ timestamp: { type: 'string', format: 'date-time' },
142
+ hourKey: { type: 'string', example: '2026-09-23T07' },
143
+ label: { type: 'string', example: '07:00' },
144
+ totalRequests: { type: 'integer', example: 120 },
145
+ errorRequests: { type: 'integer', example: 2 },
146
+ successRequests: { type: 'integer', example: 118 },
147
+ errorRate: { type: 'number', example: 1.67 },
148
+ avgDuration: { type: 'number', example: 4.2 },
149
+ },
150
+ required: ['timestamp', 'hourKey', 'label', 'totalRequests', 'errorRequests', 'successRequests', 'errorRate', 'avgDuration'],
151
+ };
152
+ schemas.AnalyticsMetricsResponse = {
153
+ type: 'object',
154
+ properties: {
155
+ database: {
156
+ type: 'object',
157
+ properties: {
158
+ sizeBytes: { type: 'integer', example: 124500 },
159
+ sizeFormatted: { type: 'string', example: '121.58 KB' },
160
+ walSizeBytes: { type: 'integer', example: 0 },
161
+ totalRecords: { type: 'integer', example: 450 },
162
+ collectionsBreakdown: {
163
+ type: 'array',
164
+ items: {
165
+ type: 'object',
166
+ properties: {
167
+ collection: { type: 'string' },
168
+ type: { type: 'string' },
169
+ count: { type: 'integer' },
170
+ },
171
+ },
172
+ },
173
+ },
174
+ },
175
+ realtime: {
176
+ type: 'object',
177
+ properties: {
178
+ connectedClients: { type: 'integer', example: 3 },
179
+ },
180
+ },
181
+ traffic24h: {
182
+ type: 'object',
183
+ properties: {
184
+ totalRequests: { type: 'integer', example: 1540 },
185
+ totalErrors: { type: 'integer', example: 12 },
186
+ overallErrorRate: { type: 'number', example: 0.78 },
187
+ avgDuration: { type: 'number', example: 3.5 },
188
+ peakHourRequests: { type: 'integer', example: 240 },
189
+ series: {
190
+ type: 'array',
191
+ items: { $ref: '#/components/schemas/HourlyDataPoint' },
192
+ },
193
+ },
194
+ },
195
+ system: {
196
+ type: 'object',
197
+ properties: {
198
+ uptime: { type: 'number' },
199
+ memoryUsage: { type: 'object' },
200
+ },
201
+ },
202
+ },
203
+ };
204
+ schemas.CollectionField = {
205
+ type: 'object',
206
+ properties: {
207
+ id: { type: 'string' },
208
+ name: { type: 'string' },
209
+ type: {
210
+ type: 'string',
211
+ enum: ['text', 'number', 'bool', 'email', 'url', 'date', 'select', 'json', 'file', 'relation'],
212
+ },
213
+ required: { type: 'boolean' },
214
+ unique: { type: 'boolean' },
215
+ defaultValue: {},
216
+ options: { type: 'object', additionalProperties: true },
217
+ },
218
+ required: ['name', 'type'],
219
+ };
220
+ schemas.CollectionModel = {
221
+ type: 'object',
222
+ properties: {
223
+ id: { type: 'string', readOnly: true },
224
+ name: { type: 'string' },
225
+ type: { type: 'string', enum: ['base', 'auth', 'view'] },
226
+ system: { type: 'boolean' },
227
+ schema: {
228
+ type: 'array',
229
+ items: { $ref: '#/components/schemas/CollectionField' },
230
+ },
231
+ indexes: { type: 'array', items: { type: 'string' } },
232
+ listRule: { type: 'string', nullable: true },
233
+ viewRule: { type: 'string', nullable: true },
234
+ createRule: { type: 'string', nullable: true },
235
+ updateRule: { type: 'string', nullable: true },
236
+ deleteRule: { type: 'string', nullable: true },
237
+ options: { type: 'object' },
238
+ created: { type: 'string', format: 'date-time', readOnly: true },
239
+ updated: { type: 'string', format: 'date-time', readOnly: true },
240
+ },
241
+ required: ['name', 'type', 'schema'],
242
+ };
243
+ schemas.CollectionListResult = {
244
+ type: 'object',
245
+ properties: {
246
+ items: {
247
+ type: 'array',
248
+ items: { $ref: '#/components/schemas/CollectionModel' },
249
+ },
250
+ totalItems: { type: 'integer' },
251
+ },
252
+ required: ['items', 'totalItems'],
253
+ };
254
+ schemas.WebhookModel = {
255
+ type: 'object',
256
+ properties: {
257
+ id: { type: 'string', readOnly: true },
258
+ name: { type: 'string' },
259
+ url: { type: 'string', format: 'uri' },
260
+ collection: { type: 'string', description: 'Collection name or *' },
261
+ event: { type: 'string', description: 'Event e.g. created, updated, deleted, or *' },
262
+ action: { type: 'string' },
263
+ method: { type: 'string', enum: ['POST', 'PUT', 'PATCH', 'DELETE', 'GET', 'HEAD'] },
264
+ headers: { type: 'object', additionalProperties: { type: 'string' } },
265
+ secret: { type: 'string', nullable: true, description: 'HMAC-SHA256 signature secret for X-NodeStack-Signature' },
266
+ enabled: { type: 'boolean' },
267
+ created: { type: 'string', format: 'date-time', readOnly: true },
268
+ updated: { type: 'string', format: 'date-time', readOnly: true },
269
+ },
270
+ required: ['id', 'name', 'url', 'collection', 'event'],
271
+ };
272
+ schemas.WebhookCreateRequest = {
273
+ type: 'object',
274
+ properties: {
275
+ name: { type: 'string' },
276
+ url: { type: 'string', format: 'uri' },
277
+ collection: { type: 'string', default: '*' },
278
+ event: { type: 'string', default: 'created' },
279
+ action: { type: 'string' },
280
+ method: { type: 'string', default: 'POST', enum: ['POST', 'PUT', 'PATCH', 'DELETE', 'GET', 'HEAD'] },
281
+ headers: { type: 'object', additionalProperties: { type: 'string' } },
282
+ secret: { type: 'string', nullable: true },
283
+ enabled: { type: 'boolean', default: true },
284
+ },
285
+ required: ['name', 'url'],
286
+ };
287
+ schemas.WebhookUpdateRequest = {
288
+ type: 'object',
289
+ properties: {
290
+ name: { type: 'string' },
291
+ url: { type: 'string', format: 'uri' },
292
+ collection: { type: 'string' },
293
+ event: { type: 'string' },
294
+ action: { type: 'string' },
295
+ method: { type: 'string', enum: ['POST', 'PUT', 'PATCH', 'DELETE', 'GET', 'HEAD'] },
296
+ headers: { type: 'object', additionalProperties: { type: 'string' } },
297
+ secret: { type: 'string', nullable: true },
298
+ enabled: { type: 'boolean' },
299
+ },
300
+ };
301
+ schemas.WebhookDeliveryModel = {
302
+ type: 'object',
303
+ properties: {
304
+ id: { type: 'string', readOnly: true },
305
+ webhookId: { type: 'string' },
306
+ webhookName: { type: 'string' },
307
+ event: { type: 'string' },
308
+ collection: { type: 'string' },
309
+ url: { type: 'string', format: 'uri' },
310
+ status: { type: 'string', enum: ['success', 'failed'] },
311
+ responseStatus: { type: 'integer', description: 'HTTP response status code returned by target endpoint' },
312
+ durationMs: { type: 'integer', description: 'Delivery duration in milliseconds' },
313
+ attempt: { type: 'integer' },
314
+ requestHeaders: { type: 'object', additionalProperties: true },
315
+ requestPayload: { type: 'object', additionalProperties: true },
316
+ responseHeaders: { type: 'object', additionalProperties: true, nullable: true },
317
+ responseBody: { type: 'string', nullable: true },
318
+ error: { type: 'string', nullable: true },
319
+ created: { type: 'string', format: 'date-time', readOnly: true },
320
+ },
321
+ required: ['id', 'webhookId', 'status', 'responseStatus', 'durationMs', 'created'],
322
+ };
323
+ schemas.WebhookDeliveryListResult = {
324
+ type: 'object',
325
+ properties: {
326
+ items: {
327
+ type: 'array',
328
+ items: { $ref: '#/components/schemas/WebhookDeliveryModel' },
329
+ },
330
+ totalItems: { type: 'integer' },
331
+ totalPages: { type: 'integer' },
332
+ page: { type: 'integer' },
333
+ perPage: { type: 'integer' },
334
+ },
335
+ required: ['items', 'totalItems', 'totalPages', 'page', 'perPage'],
336
+ };
337
+ schemas.WebhookStatsResponse = {
338
+ type: 'object',
339
+ properties: {
340
+ totalWebhooks: { type: 'integer' },
341
+ activeWebhooks: { type: 'integer' },
342
+ totalDeliveries: { type: 'integer' },
343
+ successDeliveries: { type: 'integer' },
344
+ failedDeliveries: { type: 'integer' },
345
+ successRate: { type: 'string' },
346
+ },
347
+ required: ['totalWebhooks', 'activeWebhooks', 'totalDeliveries', 'successDeliveries', 'failedDeliveries', 'successRate'],
348
+ };
349
+ schemas.WebhookTestRequest = {
350
+ type: 'object',
351
+ properties: {
352
+ payload: { type: 'object', additionalProperties: true, description: 'Optional sample payload to dispatch' },
353
+ },
354
+ };
355
+ // 2. Collection-Specific Schemas & Paths
356
+ for (const col of publicCollections) {
357
+ const pascal = this.toPascalCase(col.name);
358
+ const recordSchemaName = `${pascal}Record`;
359
+ const createSchemaName = `${pascal}Create`;
360
+ const updateSchemaName = `${pascal}Update`;
361
+ const listSchemaName = `${pascal}ListResult`;
362
+ const authResponseSchemaName = `${pascal}AuthResponse`;
363
+ tags.push({
364
+ name: col.name,
365
+ description: `Operations for the '${col.name}' collection (${col.type} type)`,
366
+ });
367
+ // --- Build Record Properties ---
368
+ const recordProps = {
369
+ id: { type: 'string', readOnly: true, example: `r_${Math.random().toString(36).slice(2, 8)}` },
370
+ created: { type: 'string', format: 'date-time', readOnly: true },
371
+ updated: { type: 'string', format: 'date-time', readOnly: true },
372
+ };
373
+ const createProps = {};
374
+ const updateProps = {};
375
+ const multipartCreateProps = {};
376
+ const createRequired = [];
377
+ let hasFileFields = false;
378
+ if (col.type === 'auth') {
379
+ recordProps.email = { type: 'string', format: 'email', example: 'user@example.com' };
380
+ recordProps.emailVisibility = { type: 'boolean', default: false };
381
+ recordProps.verified = { type: 'boolean', readOnly: true, default: false };
382
+ createProps.email = { type: 'string', format: 'email', example: 'user@example.com' };
383
+ createProps.password = { type: 'string', format: 'password', writeOnly: true, minLength: 8 };
384
+ createProps.passwordConfirm = { type: 'string', format: 'password', writeOnly: true };
385
+ createRequired.push('email', 'password');
386
+ updateProps.email = { type: 'string', format: 'email' };
387
+ updateProps.password = { type: 'string', format: 'password', writeOnly: true, minLength: 8 };
388
+ updateProps.passwordConfirm = { type: 'string', format: 'password', writeOnly: true };
389
+ updateProps.emailVisibility = { type: 'boolean' };
390
+ }
391
+ const systemFieldsToSkip = new Set(['id', 'created', 'updated']);
392
+ if (col.type === 'auth') {
393
+ systemFieldsToSkip.add('email');
394
+ systemFieldsToSkip.add('emailVisibility');
395
+ systemFieldsToSkip.add('verified');
396
+ systemFieldsToSkip.add('passwordHash');
397
+ systemFieldsToSkip.add('tokenKey');
398
+ }
399
+ for (const field of col.schema) {
400
+ if (systemFieldsToSkip.has(field.name))
401
+ continue;
402
+ const openApiField = this.mapFieldToOpenApi(field);
403
+ recordProps[field.name] = openApiField;
404
+ createProps[field.name] = openApiField;
405
+ updateProps[field.name] = openApiField;
406
+ if (field.type === 'file') {
407
+ hasFileFields = true;
408
+ const isMulti = Boolean(field.options?.maxSelect && field.options.maxSelect > 1);
409
+ multipartCreateProps[field.name] = isMulti
410
+ ? { type: 'array', items: { type: 'string', format: 'binary' } }
411
+ : { type: 'string', format: 'binary' };
412
+ }
413
+ else {
414
+ multipartCreateProps[field.name] = openApiField;
415
+ }
416
+ if (field.required) {
417
+ createRequired.push(field.name);
418
+ }
419
+ }
420
+ // Record schema includes optional expand property
421
+ recordProps.expand = {
422
+ type: 'object',
423
+ additionalProperties: true,
424
+ description: 'Expanded relations if requested via the ?expand query parameter',
425
+ };
426
+ schemas[recordSchemaName] = {
427
+ type: 'object',
428
+ properties: recordProps,
429
+ required: ['id', 'created', 'updated'],
430
+ };
431
+ schemas[createSchemaName] = {
432
+ type: 'object',
433
+ properties: createProps,
434
+ ...(createRequired.length > 0 ? { required: createRequired } : {}),
435
+ };
436
+ schemas[updateSchemaName] = {
437
+ type: 'object',
438
+ properties: updateProps,
439
+ };
440
+ schemas[listSchemaName] = {
441
+ type: 'object',
442
+ properties: {
443
+ page: { type: 'integer', example: 1 },
444
+ perPage: { type: 'integer', example: 30 },
445
+ totalItems: { type: 'integer', example: 1 },
446
+ totalPages: { type: 'integer', example: 1 },
447
+ items: {
448
+ type: 'array',
449
+ items: { $ref: `#/components/schemas/${recordSchemaName}` },
450
+ },
451
+ },
452
+ required: ['page', 'perPage', 'totalItems', 'totalPages', 'items'],
453
+ };
454
+ if (col.type === 'auth') {
455
+ schemas[authResponseSchemaName] = {
456
+ type: 'object',
457
+ properties: {
458
+ token: { type: 'string', description: 'JWT authentication token' },
459
+ record: { $ref: `#/components/schemas/${recordSchemaName}` },
460
+ },
461
+ required: ['token', 'record'],
462
+ };
463
+ }
464
+ // --- Paths for this collection ---
465
+ const recordsPath = `${apiPrefix}/collections/${col.name}/records`;
466
+ const recordItemPath = `${apiPrefix}/collections/${col.name}/records/{id}`;
467
+ // 1. List Records (GET)
468
+ paths[recordsPath] = paths[recordsPath] || {};
469
+ paths[recordsPath].get = {
470
+ tags: [col.name],
471
+ summary: `List ${col.name} records`,
472
+ description: `Returns a paginated list of **${col.name}** records.\n\n**Access Rule:** ${this.describeRule(col.listRule)}`,
473
+ security: [{ BearerAuth: [] }, {}],
474
+ parameters: [
475
+ {
476
+ name: 'page',
477
+ in: 'query',
478
+ schema: { type: 'integer', default: 1, minimum: 1 },
479
+ description: 'Page number',
480
+ },
481
+ {
482
+ name: 'perPage',
483
+ in: 'query',
484
+ schema: { type: 'integer', default: 30, minimum: 1, maximum: 500 },
485
+ description: 'Number of records per page',
486
+ },
487
+ {
488
+ name: 'sort',
489
+ in: 'query',
490
+ schema: { type: 'string' },
491
+ description: 'Fields to sort by. Prefix with - for descending order (e.g. `-created,title`).',
492
+ },
493
+ {
494
+ name: 'filter',
495
+ in: 'query',
496
+ schema: { type: 'string' },
497
+ description: 'Filter expression (e.g. `status = "active" && views > 10`).',
498
+ },
499
+ {
500
+ name: 'search',
501
+ in: 'query',
502
+ schema: { type: 'string' },
503
+ description: 'Full-text search query across indexed text fields with BM25 ranking (e.g. `typescript backend`).',
504
+ },
505
+ {
506
+ name: 'expand',
507
+ in: 'query',
508
+ schema: { type: 'string' },
509
+ description: 'Comma-separated relation field names to expand.',
510
+ },
511
+ {
512
+ name: 'fields',
513
+ in: 'query',
514
+ schema: { type: 'string' },
515
+ description: 'Comma-separated field names to return.',
516
+ },
517
+ {
518
+ name: 'mock_delay',
519
+ in: 'query',
520
+ schema: { type: 'string', example: '1500' },
521
+ description: 'Simulate mobile/network latency in milliseconds (e.g. 1500 or 500-1500).',
522
+ },
523
+ {
524
+ name: 'mock_error',
525
+ in: 'query',
526
+ schema: { type: 'integer', example: 500 },
527
+ description: 'Simulate an HTTP error status code (e.g. 500, 503, 404).',
528
+ },
529
+ {
530
+ name: 'mock_fail_rate',
531
+ in: 'query',
532
+ schema: { type: 'number', example: 0.2 },
533
+ description: 'Simulate random network failure probability between 0.0 and 1.0 (e.g. 0.2 for 20% drops).',
534
+ },
535
+ ],
536
+ responses: {
537
+ '200': {
538
+ description: `List of ${col.name} records`,
539
+ content: {
540
+ 'application/json': {
541
+ schema: { $ref: `#/components/schemas/${listSchemaName}` },
542
+ },
543
+ },
544
+ },
545
+ '400': {
546
+ description: 'Invalid query parameters or filter syntax',
547
+ content: {
548
+ 'application/json': {
549
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
550
+ },
551
+ },
552
+ },
553
+ '403': {
554
+ description: 'Forbidden by access rule',
555
+ content: {
556
+ 'application/json': {
557
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
558
+ },
559
+ },
560
+ },
561
+ },
562
+ };
563
+ // 2. Create Record (POST)
564
+ const postRequestContent = {
565
+ 'application/json': {
566
+ schema: { $ref: `#/components/schemas/${createSchemaName}` },
567
+ },
568
+ };
569
+ if (hasFileFields) {
570
+ postRequestContent['multipart/form-data'] = {
571
+ schema: {
572
+ type: 'object',
573
+ properties: multipartCreateProps,
574
+ ...(createRequired.length > 0 ? { required: createRequired } : {}),
575
+ },
576
+ };
577
+ }
578
+ paths[recordsPath].post = {
579
+ tags: [col.name],
580
+ summary: `Create ${col.name} record`,
581
+ description: `Creates a new record in **${col.name}**.\n\n**Access Rule:** ${this.describeRule(col.createRule)}`,
582
+ security: [{ BearerAuth: [] }, {}],
583
+ requestBody: {
584
+ required: true,
585
+ content: postRequestContent,
586
+ },
587
+ responses: {
588
+ '201': {
589
+ description: 'Record successfully created',
590
+ content: {
591
+ 'application/json': {
592
+ schema: { $ref: `#/components/schemas/${recordSchemaName}` },
593
+ },
594
+ },
595
+ },
596
+ '400': {
597
+ description: 'Validation failed or missing required fields',
598
+ content: {
599
+ 'application/json': {
600
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
601
+ },
602
+ },
603
+ },
604
+ '403': {
605
+ description: 'Forbidden by access rule',
606
+ content: {
607
+ 'application/json': {
608
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
609
+ },
610
+ },
611
+ },
612
+ },
613
+ };
614
+ // 3. Get One Record (GET)
615
+ paths[recordItemPath] = paths[recordItemPath] || {};
616
+ paths[recordItemPath].get = {
617
+ tags: [col.name],
618
+ summary: `Get ${col.name} record by ID`,
619
+ description: `Retrieves a single **${col.name}** record by its unique ID.\n\n**Access Rule:** ${this.describeRule(col.viewRule)}`,
620
+ security: [{ BearerAuth: [] }, {}],
621
+ parameters: [
622
+ {
623
+ name: 'id',
624
+ in: 'path',
625
+ required: true,
626
+ schema: { type: 'string' },
627
+ description: 'Unique record identifier',
628
+ },
629
+ {
630
+ name: 'expand',
631
+ in: 'query',
632
+ schema: { type: 'string' },
633
+ description: 'Comma-separated relation field names to expand.',
634
+ },
635
+ {
636
+ name: 'fields',
637
+ in: 'query',
638
+ schema: { type: 'string' },
639
+ description: 'Comma-separated field names to return.',
640
+ },
641
+ ],
642
+ responses: {
643
+ '200': {
644
+ description: 'Record retrieved successfully',
645
+ content: {
646
+ 'application/json': {
647
+ schema: { $ref: `#/components/schemas/${recordSchemaName}` },
648
+ },
649
+ },
650
+ },
651
+ '403': {
652
+ description: 'Forbidden by access rule',
653
+ content: {
654
+ 'application/json': {
655
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
656
+ },
657
+ },
658
+ },
659
+ '404': {
660
+ description: 'Record not found',
661
+ content: {
662
+ 'application/json': {
663
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
664
+ },
665
+ },
666
+ },
667
+ },
668
+ };
669
+ // 4. Update Record (PATCH)
670
+ const patchRequestContent = {
671
+ 'application/json': {
672
+ schema: { $ref: `#/components/schemas/${updateSchemaName}` },
673
+ },
674
+ };
675
+ if (hasFileFields) {
676
+ patchRequestContent['multipart/form-data'] = {
677
+ schema: {
678
+ type: 'object',
679
+ properties: multipartCreateProps,
680
+ },
681
+ };
682
+ }
683
+ paths[recordItemPath].patch = {
684
+ tags: [col.name],
685
+ summary: `Update ${col.name} record`,
686
+ description: `Partially updates an existing **${col.name}** record.\n\n**Access Rule:** ${this.describeRule(col.updateRule)}`,
687
+ security: [{ BearerAuth: [] }, {}],
688
+ parameters: [
689
+ {
690
+ name: 'id',
691
+ in: 'path',
692
+ required: true,
693
+ schema: { type: 'string' },
694
+ description: 'Unique record identifier',
695
+ },
696
+ ],
697
+ requestBody: {
698
+ required: true,
699
+ content: patchRequestContent,
700
+ },
701
+ responses: {
702
+ '200': {
703
+ description: 'Record updated successfully',
704
+ content: {
705
+ 'application/json': {
706
+ schema: { $ref: `#/components/schemas/${recordSchemaName}` },
707
+ },
708
+ },
709
+ },
710
+ '400': {
711
+ description: 'Validation failed',
712
+ content: {
713
+ 'application/json': {
714
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
715
+ },
716
+ },
717
+ },
718
+ '403': {
719
+ description: 'Forbidden by access rule',
720
+ content: {
721
+ 'application/json': {
722
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
723
+ },
724
+ },
725
+ },
726
+ '404': {
727
+ description: 'Record not found',
728
+ content: {
729
+ 'application/json': {
730
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
731
+ },
732
+ },
733
+ },
734
+ },
735
+ };
736
+ // 5. Delete Record (DELETE)
737
+ paths[recordItemPath].delete = {
738
+ tags: [col.name],
739
+ summary: `Delete ${col.name} record`,
740
+ description: `Deletes a single **${col.name}** record.\n\n**Access Rule:** ${this.describeRule(col.deleteRule)}`,
741
+ security: [{ BearerAuth: [] }, {}],
742
+ parameters: [
743
+ {
744
+ name: 'id',
745
+ in: 'path',
746
+ required: true,
747
+ schema: { type: 'string' },
748
+ description: 'Unique record identifier',
749
+ },
750
+ ],
751
+ responses: {
752
+ '204': {
753
+ description: 'Record successfully deleted (No Content)',
754
+ },
755
+ '403': {
756
+ description: 'Forbidden by access rule',
757
+ content: {
758
+ 'application/json': {
759
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
760
+ },
761
+ },
762
+ },
763
+ '404': {
764
+ description: 'Record not found',
765
+ content: {
766
+ 'application/json': {
767
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
768
+ },
769
+ },
770
+ },
771
+ },
772
+ };
773
+ // 6. Auth collection login route
774
+ if (col.type === 'auth') {
775
+ const authPath = `${apiPrefix}/collections/${col.name}/auth-with-password`;
776
+ paths[authPath] = paths[authPath] || {};
777
+ paths[authPath].post = {
778
+ tags: ['Auth', col.name],
779
+ summary: `Authenticate ${col.name} record with password`,
780
+ description: `Authenticates an account in the **${col.name}** collection using email/identity and password. Returns a signed JWT token.`,
781
+ requestBody: {
782
+ required: true,
783
+ content: {
784
+ 'application/json': {
785
+ schema: { $ref: '#/components/schemas/AuthWithPasswordRequest' },
786
+ },
787
+ },
788
+ },
789
+ responses: {
790
+ '200': {
791
+ description: 'Authentication successful',
792
+ content: {
793
+ 'application/json': {
794
+ schema: { $ref: `#/components/schemas/${authResponseSchemaName}` },
795
+ },
796
+ },
797
+ },
798
+ '400': {
799
+ description: 'Invalid credentials or missing fields',
800
+ content: {
801
+ 'application/json': {
802
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
803
+ },
804
+ },
805
+ },
806
+ },
807
+ };
808
+ }
809
+ }
810
+ // 3. Auth Core Endpoints
811
+ tags.push({ name: 'Auth', description: 'Admin and user authentication endpoints' });
812
+ paths['/api/admins/has-admins'] = {
813
+ get: {
814
+ tags: ['Auth'],
815
+ summary: 'Check if initial superuser exists',
816
+ description: 'Returns whether at least one superuser/admin account has been created.',
817
+ responses: {
818
+ '200': {
819
+ description: 'Check status',
820
+ content: {
821
+ 'application/json': {
822
+ schema: {
823
+ type: 'object',
824
+ properties: { hasAdmins: { type: 'boolean' } },
825
+ required: ['hasAdmins'],
826
+ },
827
+ },
828
+ },
829
+ },
830
+ },
831
+ },
832
+ };
833
+ paths['/api/admins/create-initial'] = {
834
+ post: {
835
+ tags: ['Auth'],
836
+ summary: 'Create initial superuser account',
837
+ description: 'Creates the initial superuser account. Only available if no admins exist.',
838
+ requestBody: {
839
+ required: true,
840
+ content: {
841
+ 'application/json': {
842
+ schema: { $ref: '#/components/schemas/CreateInitialAdminRequest' },
843
+ },
844
+ },
845
+ },
846
+ responses: {
847
+ '201': {
848
+ description: 'Superuser created and logged in',
849
+ content: {
850
+ 'application/json': {
851
+ schema: { $ref: '#/components/schemas/AdminAuthResponse' },
852
+ },
853
+ },
854
+ },
855
+ '400': {
856
+ description: 'Admin already initialized or validation error',
857
+ content: {
858
+ 'application/json': {
859
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
860
+ },
861
+ },
862
+ },
863
+ },
864
+ },
865
+ };
866
+ paths['/api/admins/auth-with-password'] = {
867
+ post: {
868
+ tags: ['Auth'],
869
+ summary: 'Superuser / Admin login',
870
+ description: 'Authenticates a superuser with email and password, returning a JWT token.',
871
+ requestBody: {
872
+ required: true,
873
+ content: {
874
+ 'application/json': {
875
+ schema: { $ref: '#/components/schemas/AuthWithPasswordRequest' },
876
+ },
877
+ },
878
+ },
879
+ responses: {
880
+ '200': {
881
+ description: 'Login successful',
882
+ content: {
883
+ 'application/json': {
884
+ schema: { $ref: '#/components/schemas/AdminAuthResponse' },
885
+ },
886
+ },
887
+ },
888
+ '400': {
889
+ description: 'Invalid credentials',
890
+ content: {
891
+ 'application/json': {
892
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
893
+ },
894
+ },
895
+ },
896
+ },
897
+ },
898
+ };
899
+ paths['/api/admins/me'] = {
900
+ get: {
901
+ tags: ['Auth'],
902
+ summary: 'Get current logged-in superuser',
903
+ description: 'Returns profile details for the authenticated superuser.',
904
+ security: [{ BearerAuth: [] }],
905
+ responses: {
906
+ '200': {
907
+ description: 'Current superuser details',
908
+ content: {
909
+ 'application/json': {
910
+ schema: { $ref: '#/components/schemas/AdminModel' },
911
+ },
912
+ },
913
+ },
914
+ '401': {
915
+ description: 'Unauthorized or missing superuser token',
916
+ content: {
917
+ 'application/json': {
918
+ schema: { $ref: '#/components/schemas/ErrorResponse' },
919
+ },
920
+ },
921
+ },
922
+ },
923
+ },
924
+ };
925
+ // 4. Schema Collections Management Endpoints
926
+ tags.push({ name: 'Collections', description: 'Collection schema management (Admin only)' });
927
+ paths[`${apiPrefix}/collections`] = {
928
+ get: {
929
+ tags: ['Collections'],
930
+ summary: 'List all collections',
931
+ description: 'Lists all collection schemas currently defined in NodeStack.',
932
+ security: [{ BearerAuth: [] }],
933
+ responses: {
934
+ '200': {
935
+ description: 'List of collections',
936
+ content: {
937
+ 'application/json': {
938
+ schema: { $ref: '#/components/schemas/CollectionListResult' },
939
+ },
940
+ },
941
+ },
942
+ '401': { description: 'Unauthorized' },
943
+ },
944
+ },
945
+ post: {
946
+ tags: ['Collections'],
947
+ summary: 'Create a new collection',
948
+ description: 'Creates a new collection schema and underlying SQLite table.',
949
+ security: [{ BearerAuth: [] }],
950
+ requestBody: {
951
+ required: true,
952
+ content: {
953
+ 'application/json': {
954
+ schema: { $ref: '#/components/schemas/CollectionModel' },
955
+ },
956
+ },
957
+ },
958
+ responses: {
959
+ '201': {
960
+ description: 'Collection created',
961
+ content: {
962
+ 'application/json': {
963
+ schema: { $ref: '#/components/schemas/CollectionModel' },
964
+ },
965
+ },
966
+ },
967
+ '400': { description: 'Validation failed' },
968
+ '401': { description: 'Unauthorized' },
969
+ },
970
+ },
971
+ };
972
+ paths[`${apiPrefix}/collections/infer-schema`] = {
973
+ post: {
974
+ tags: ['Collections'],
975
+ summary: 'Infer schema from JSON',
976
+ description: 'Analyzes a raw JSON object or array and automatically infers field types (text, number, bool, date, json).',
977
+ security: [{ BearerAuth: [] }],
978
+ requestBody: {
979
+ required: true,
980
+ content: {
981
+ 'application/json': {
982
+ schema: {
983
+ type: 'object',
984
+ required: ['data'],
985
+ properties: {
986
+ data: {
987
+ description: 'Raw JSON object or array of objects',
988
+ },
989
+ },
990
+ },
991
+ },
992
+ },
993
+ },
994
+ responses: {
995
+ '200': {
996
+ description: 'Inferred schema result',
997
+ content: {
998
+ 'application/json': {
999
+ schema: {
1000
+ type: 'object',
1001
+ properties: {
1002
+ suggestedName: { type: 'string' },
1003
+ fields: { type: 'array', items: { $ref: '#/components/schemas/SchemaField' } },
1004
+ recordCount: { type: 'integer' },
1005
+ sampleRecords: { type: 'array', items: { type: 'object' } },
1006
+ },
1007
+ },
1008
+ },
1009
+ },
1010
+ },
1011
+ '400': { description: 'Invalid JSON payload' },
1012
+ '401': { description: 'Unauthorized' },
1013
+ },
1014
+ },
1015
+ };
1016
+ paths[`${apiPrefix}/collections/import-json`] = {
1017
+ post: {
1018
+ tags: ['Collections'],
1019
+ summary: 'Paste JSON → Instant API',
1020
+ description: 'Infers schema, creates collection & SQLite columns, and populates records instantly in 1 second.',
1021
+ security: [{ BearerAuth: [] }],
1022
+ requestBody: {
1023
+ required: true,
1024
+ content: {
1025
+ 'application/json': {
1026
+ schema: {
1027
+ type: 'object',
1028
+ required: ['name', 'data'],
1029
+ properties: {
1030
+ name: { type: 'string', description: 'Name of the collection to create' },
1031
+ data: { description: 'Raw JSON object or array of objects to import' },
1032
+ type: { type: 'string', enum: ['base', 'auth'], default: 'base' },
1033
+ schemaOverrides: {
1034
+ type: 'array',
1035
+ items: { $ref: '#/components/schemas/SchemaField' },
1036
+ description: 'Optional schema field overrides',
1037
+ },
1038
+ },
1039
+ },
1040
+ },
1041
+ },
1042
+ },
1043
+ responses: {
1044
+ '201': {
1045
+ description: 'Collection created and records imported',
1046
+ content: {
1047
+ 'application/json': {
1048
+ schema: {
1049
+ type: 'object',
1050
+ properties: {
1051
+ success: { type: 'boolean' },
1052
+ collection: { $ref: '#/components/schemas/CollectionModel' },
1053
+ recordCount: { type: 'integer' },
1054
+ records: { type: 'array', items: { type: 'object' } },
1055
+ inferredFields: { type: 'array', items: { $ref: '#/components/schemas/SchemaField' } },
1056
+ durationMs: { type: 'number' },
1057
+ },
1058
+ },
1059
+ },
1060
+ },
1061
+ },
1062
+ '400': { description: 'Validation failed or invalid JSON' },
1063
+ '401': { description: 'Unauthorized' },
1064
+ '409': { description: 'Collection already exists' },
1065
+ },
1066
+ },
1067
+ };
1068
+ paths[`${apiPrefix}/collections/{collection}`] = {
1069
+ get: {
1070
+ tags: ['Collections'],
1071
+ summary: 'Get collection details',
1072
+ description: 'Returns schema definition for a specific collection.',
1073
+ security: [{ BearerAuth: [] }],
1074
+ parameters: [
1075
+ { name: 'collection', in: 'path', required: true, schema: { type: 'string' } },
1076
+ ],
1077
+ responses: {
1078
+ '200': {
1079
+ description: 'Collection details',
1080
+ content: {
1081
+ 'application/json': {
1082
+ schema: { $ref: '#/components/schemas/CollectionModel' },
1083
+ },
1084
+ },
1085
+ },
1086
+ '404': { description: 'Collection not found' },
1087
+ },
1088
+ },
1089
+ patch: {
1090
+ tags: ['Collections'],
1091
+ summary: 'Update collection schema',
1092
+ description: 'Updates schema fields, rules, and indexes for an existing collection.',
1093
+ security: [{ BearerAuth: [] }],
1094
+ parameters: [
1095
+ { name: 'collection', in: 'path', required: true, schema: { type: 'string' } },
1096
+ ],
1097
+ requestBody: {
1098
+ required: true,
1099
+ content: {
1100
+ 'application/json': {
1101
+ schema: { $ref: '#/components/schemas/CollectionModel' },
1102
+ },
1103
+ },
1104
+ },
1105
+ responses: {
1106
+ '200': {
1107
+ description: 'Collection updated',
1108
+ content: {
1109
+ 'application/json': {
1110
+ schema: { $ref: '#/components/schemas/CollectionModel' },
1111
+ },
1112
+ },
1113
+ },
1114
+ '400': { description: 'Invalid schema update' },
1115
+ '404': { description: 'Collection not found' },
1116
+ },
1117
+ },
1118
+ delete: {
1119
+ tags: ['Collections'],
1120
+ summary: 'Delete collection',
1121
+ description: 'Permanently deletes a collection and drops its SQLite table.',
1122
+ security: [{ BearerAuth: [] }],
1123
+ parameters: [
1124
+ { name: 'collection', in: 'path', required: true, schema: { type: 'string' } },
1125
+ ],
1126
+ responses: {
1127
+ '204': { description: 'Collection deleted' },
1128
+ '400': { description: 'Cannot delete system collection' },
1129
+ '404': { description: 'Collection not found' },
1130
+ },
1131
+ },
1132
+ };
1133
+ // 5. File Storage Endpoints
1134
+ tags.push({ name: 'Files', description: 'File serving and download endpoints' });
1135
+ paths[`${apiPrefix}/files/{collection}/{recordId}/{filename}`] = {
1136
+ get: {
1137
+ tags: ['Files'],
1138
+ summary: 'Download / view file',
1139
+ description: 'Downloads or displays a file stored in a record. Access is controlled by the collection `viewRule`.',
1140
+ parameters: [
1141
+ { name: 'collection', in: 'path', required: true, schema: { type: 'string' } },
1142
+ { name: 'recordId', in: 'path', required: true, schema: { type: 'string' } },
1143
+ { name: 'filename', in: 'path', required: true, schema: { type: 'string' } },
1144
+ {
1145
+ name: 'download',
1146
+ in: 'query',
1147
+ schema: { type: 'string', enum: ['0', '1'] },
1148
+ description: 'Set to 1 to force browser attachment download.',
1149
+ },
1150
+ ],
1151
+ responses: {
1152
+ '200': {
1153
+ description: 'File stream content',
1154
+ content: {
1155
+ '*/*': {
1156
+ schema: { type: 'string', format: 'binary' },
1157
+ },
1158
+ },
1159
+ },
1160
+ '403': { description: 'Forbidden by access rule' },
1161
+ '404': { description: 'File or record not found' },
1162
+ },
1163
+ },
1164
+ };
1165
+ // 6. Realtime Endpoints
1166
+ tags.push({ name: 'Realtime', description: 'Realtime Server-Sent Events (SSE) streaming' });
1167
+ paths[`${apiPrefix}/realtime`] = {
1168
+ get: {
1169
+ tags: ['Realtime'],
1170
+ summary: 'Connect to Realtime SSE event stream',
1171
+ description: 'Establishes a persistent Server-Sent Events (SSE) connection for real-time record updates.',
1172
+ security: [{ BearerAuth: [] }, {}],
1173
+ responses: {
1174
+ '200': {
1175
+ description: 'SSE stream connection established',
1176
+ content: {
1177
+ 'text/event-stream': {
1178
+ schema: { type: 'string' },
1179
+ },
1180
+ },
1181
+ },
1182
+ },
1183
+ },
1184
+ post: {
1185
+ tags: ['Realtime'],
1186
+ summary: 'Set client subscriptions',
1187
+ description: 'Configures collection subscriptions for an active realtime connection.',
1188
+ requestBody: {
1189
+ required: true,
1190
+ content: {
1191
+ 'application/json': {
1192
+ schema: {
1193
+ type: 'object',
1194
+ properties: {
1195
+ clientId: { type: 'string', example: 'client_xyz' },
1196
+ subscriptions: {
1197
+ type: 'array',
1198
+ items: { type: 'string' },
1199
+ example: ['posts', 'users'],
1200
+ },
1201
+ },
1202
+ required: ['clientId', 'subscriptions'],
1203
+ },
1204
+ },
1205
+ },
1206
+ },
1207
+ responses: {
1208
+ '204': { description: 'Subscriptions configured' },
1209
+ '404': { description: 'Client disconnected or not found' },
1210
+ },
1211
+ },
1212
+ };
1213
+ // 7. System Endpoints
1214
+ tags.push({ name: 'System', description: 'System health, logs, settings, and developer utilities' });
1215
+ paths['/api/health'] = {
1216
+ get: {
1217
+ tags: ['System'],
1218
+ summary: 'Health check',
1219
+ description: 'Returns server status, version, uptime, and memory usage metrics.',
1220
+ responses: {
1221
+ '200': {
1222
+ description: 'Server is healthy',
1223
+ content: {
1224
+ 'application/json': {
1225
+ schema: { $ref: '#/components/schemas/HealthResponse' },
1226
+ },
1227
+ },
1228
+ },
1229
+ },
1230
+ },
1231
+ };
1232
+ paths['/api/settings'] = {
1233
+ get: {
1234
+ tags: ['System'],
1235
+ summary: 'Application settings',
1236
+ description: 'Returns basic server configuration details.',
1237
+ responses: {
1238
+ '200': {
1239
+ description: 'Settings information',
1240
+ content: {
1241
+ 'application/json': {
1242
+ schema: { $ref: '#/components/schemas/SettingsResponse' },
1243
+ },
1244
+ },
1245
+ },
1246
+ },
1247
+ },
1248
+ };
1249
+ paths['/api/logs'] = {
1250
+ get: {
1251
+ tags: ['System'],
1252
+ summary: 'Request logs & traffic',
1253
+ description: 'Returns recent HTTP request audit logs (Admin only).',
1254
+ security: [{ BearerAuth: [] }],
1255
+ parameters: [
1256
+ { name: 'page', in: 'query', schema: { type: 'integer', default: 1 } },
1257
+ { name: 'perPage', in: 'query', schema: { type: 'integer', default: 50 } },
1258
+ ],
1259
+ responses: {
1260
+ '200': {
1261
+ description: 'Log entries',
1262
+ content: {
1263
+ 'application/json': {
1264
+ schema: { $ref: '#/components/schemas/LogListResult' },
1265
+ },
1266
+ },
1267
+ },
1268
+ '401': { description: 'Unauthorized' },
1269
+ },
1270
+ },
1271
+ delete: {
1272
+ tags: ['System'],
1273
+ summary: 'Clear request logs',
1274
+ description: 'Truncates the request audit log history table (Admin only).',
1275
+ security: [{ BearerAuth: [] }],
1276
+ responses: {
1277
+ '204': { description: 'Logs cleared successfully' },
1278
+ '401': { description: 'Unauthorized' },
1279
+ },
1280
+ },
1281
+ };
1282
+ paths['/api/metrics'] = {
1283
+ get: {
1284
+ tags: ['System'],
1285
+ summary: 'Analytics & system metrics',
1286
+ description: 'Returns active record count, database size on disk, realtime connected clients, and 24h request throughput and error rate graphs (Admin only).',
1287
+ security: [{ BearerAuth: [] }],
1288
+ responses: {
1289
+ '200': {
1290
+ description: 'Analytics metrics',
1291
+ content: {
1292
+ 'application/json': {
1293
+ schema: { $ref: '#/components/schemas/AnalyticsMetricsResponse' },
1294
+ },
1295
+ },
1296
+ },
1297
+ '403': { description: 'Forbidden (Admin only)' },
1298
+ },
1299
+ },
1300
+ };
1301
+ // 8.5 Webhooks Endpoints (Admin only)
1302
+ tags.push({ name: 'Webhooks', description: 'Outbound webhooks management, delivery tracking, and manual retry' });
1303
+ paths[`${apiPrefix}/webhooks`] = {
1304
+ get: {
1305
+ tags: ['Webhooks'],
1306
+ summary: 'List configured webhooks',
1307
+ description: 'Returns all outbound webhooks configured in NodeStack (Admin only).',
1308
+ security: [{ BearerAuth: [] }],
1309
+ parameters: [
1310
+ { name: 'collection', in: 'query', schema: { type: 'string' }, description: 'Filter by collection' },
1311
+ { name: 'event', in: 'query', schema: { type: 'string' }, description: 'Filter by event' },
1312
+ { name: 'enabled', in: 'query', schema: { type: 'boolean' }, description: 'Filter by enabled status' },
1313
+ ],
1314
+ responses: {
1315
+ '200': {
1316
+ description: 'Webhooks list',
1317
+ content: {
1318
+ 'application/json': {
1319
+ schema: {
1320
+ type: 'array',
1321
+ items: { $ref: '#/components/schemas/WebhookModel' },
1322
+ },
1323
+ },
1324
+ },
1325
+ },
1326
+ '401': {
1327
+ description: 'Unauthorized',
1328
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1329
+ },
1330
+ '403': {
1331
+ description: 'Forbidden (Admin only)',
1332
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1333
+ },
1334
+ },
1335
+ },
1336
+ post: {
1337
+ tags: ['Webhooks'],
1338
+ summary: 'Create outbound webhook',
1339
+ description: 'Registers a new outbound webhook with collection, event, endpoint URL, custom headers, and HMAC-SHA256 secret (Admin only).',
1340
+ security: [{ BearerAuth: [] }],
1341
+ requestBody: {
1342
+ required: true,
1343
+ content: {
1344
+ 'application/json': {
1345
+ schema: { $ref: '#/components/schemas/WebhookCreateRequest' },
1346
+ },
1347
+ },
1348
+ },
1349
+ responses: {
1350
+ '201': {
1351
+ description: 'Webhook created successfully',
1352
+ content: {
1353
+ 'application/json': {
1354
+ schema: { $ref: '#/components/schemas/WebhookModel' },
1355
+ },
1356
+ },
1357
+ },
1358
+ '400': {
1359
+ description: 'Invalid request',
1360
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1361
+ },
1362
+ '401': {
1363
+ description: 'Unauthorized',
1364
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1365
+ },
1366
+ '403': {
1367
+ description: 'Forbidden (Admin only)',
1368
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1369
+ },
1370
+ },
1371
+ },
1372
+ };
1373
+ paths[`${apiPrefix}/webhooks/stats`] = {
1374
+ get: {
1375
+ tags: ['Webhooks'],
1376
+ summary: 'Get webhook statistics',
1377
+ description: 'Returns aggregate webhook and delivery metrics including active count, total deliveries, and success rate (Admin only).',
1378
+ security: [{ BearerAuth: [] }],
1379
+ responses: {
1380
+ '200': {
1381
+ description: 'Webhook statistics',
1382
+ content: {
1383
+ 'application/json': {
1384
+ schema: { $ref: '#/components/schemas/WebhookStatsResponse' },
1385
+ },
1386
+ },
1387
+ },
1388
+ '401': {
1389
+ description: 'Unauthorized',
1390
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1391
+ },
1392
+ '403': {
1393
+ description: 'Forbidden (Admin only)',
1394
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1395
+ },
1396
+ },
1397
+ },
1398
+ };
1399
+ paths[`${apiPrefix}/webhooks/{id}`] = {
1400
+ get: {
1401
+ tags: ['Webhooks'],
1402
+ summary: 'Get webhook by ID',
1403
+ description: 'Fetches details of a specific configured webhook by its ID (Admin only).',
1404
+ security: [{ BearerAuth: [] }],
1405
+ parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
1406
+ responses: {
1407
+ '200': {
1408
+ description: 'Webhook configuration',
1409
+ content: {
1410
+ 'application/json': {
1411
+ schema: { $ref: '#/components/schemas/WebhookModel' },
1412
+ },
1413
+ },
1414
+ },
1415
+ '401': {
1416
+ description: 'Unauthorized',
1417
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1418
+ },
1419
+ '403': {
1420
+ description: 'Forbidden (Admin only)',
1421
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1422
+ },
1423
+ '404': {
1424
+ description: 'Webhook not found',
1425
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1426
+ },
1427
+ },
1428
+ },
1429
+ patch: {
1430
+ tags: ['Webhooks'],
1431
+ summary: 'Update webhook',
1432
+ description: 'Updates configuration of an existing webhook (Admin only).',
1433
+ security: [{ BearerAuth: [] }],
1434
+ parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
1435
+ requestBody: {
1436
+ required: true,
1437
+ content: {
1438
+ 'application/json': {
1439
+ schema: { $ref: '#/components/schemas/WebhookUpdateRequest' },
1440
+ },
1441
+ },
1442
+ },
1443
+ responses: {
1444
+ '200': {
1445
+ description: 'Webhook updated successfully',
1446
+ content: {
1447
+ 'application/json': {
1448
+ schema: { $ref: '#/components/schemas/WebhookModel' },
1449
+ },
1450
+ },
1451
+ },
1452
+ '400': {
1453
+ description: 'Invalid request',
1454
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1455
+ },
1456
+ '401': {
1457
+ description: 'Unauthorized',
1458
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1459
+ },
1460
+ '403': {
1461
+ description: 'Forbidden (Admin only)',
1462
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1463
+ },
1464
+ '404': {
1465
+ description: 'Webhook not found',
1466
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1467
+ },
1468
+ },
1469
+ },
1470
+ delete: {
1471
+ tags: ['Webhooks'],
1472
+ summary: 'Delete webhook',
1473
+ description: 'Permanently removes a webhook configuration (Admin only).',
1474
+ security: [{ BearerAuth: [] }],
1475
+ parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
1476
+ responses: {
1477
+ '204': { description: 'Webhook deleted successfully' },
1478
+ '401': {
1479
+ description: 'Unauthorized',
1480
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1481
+ },
1482
+ '403': {
1483
+ description: 'Forbidden (Admin only)',
1484
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1485
+ },
1486
+ '404': {
1487
+ description: 'Webhook not found',
1488
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1489
+ },
1490
+ },
1491
+ },
1492
+ };
1493
+ paths[`${apiPrefix}/webhooks/{id}/test`] = {
1494
+ post: {
1495
+ tags: ['Webhooks'],
1496
+ summary: 'Test webhook dispatch',
1497
+ description: 'Sends a sample test payload to the webhook endpoint and logs the response (Admin only).',
1498
+ security: [{ BearerAuth: [] }],
1499
+ parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
1500
+ requestBody: {
1501
+ required: false,
1502
+ content: {
1503
+ 'application/json': {
1504
+ schema: { $ref: '#/components/schemas/WebhookTestRequest' },
1505
+ },
1506
+ },
1507
+ },
1508
+ responses: {
1509
+ '200': {
1510
+ description: 'Test delivery result',
1511
+ content: {
1512
+ 'application/json': {
1513
+ schema: { $ref: '#/components/schemas/WebhookDeliveryModel' },
1514
+ },
1515
+ },
1516
+ },
1517
+ '401': {
1518
+ description: 'Unauthorized',
1519
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1520
+ },
1521
+ '403': {
1522
+ description: 'Forbidden (Admin only)',
1523
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1524
+ },
1525
+ '404': {
1526
+ description: 'Webhook not found',
1527
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1528
+ },
1529
+ },
1530
+ },
1531
+ };
1532
+ paths[`${apiPrefix}/webhooks/deliveries`] = {
1533
+ get: {
1534
+ tags: ['Webhooks'],
1535
+ summary: 'List webhook delivery logs',
1536
+ description: 'Returns paginated delivery logs with response codes, duration, headers, and payload (Admin only).',
1537
+ security: [{ BearerAuth: [] }],
1538
+ parameters: [
1539
+ { name: 'webhookId', in: 'query', schema: { type: 'string' }, description: 'Filter by webhook ID' },
1540
+ { name: 'collection', in: 'query', schema: { type: 'string' }, description: 'Filter by collection' },
1541
+ { name: 'status', in: 'query', schema: { type: 'string', enum: ['all', 'success', 'failed'] }, description: 'Filter by status' },
1542
+ { name: 'search', in: 'query', schema: { type: 'string' }, description: 'Search query' },
1543
+ { name: 'page', in: 'query', schema: { type: 'integer', default: 1 } },
1544
+ { name: 'perPage', in: 'query', schema: { type: 'integer', default: 25 } },
1545
+ ],
1546
+ responses: {
1547
+ '200': {
1548
+ description: 'Delivery logs',
1549
+ content: {
1550
+ 'application/json': {
1551
+ schema: { $ref: '#/components/schemas/WebhookDeliveryListResult' },
1552
+ },
1553
+ },
1554
+ },
1555
+ '401': {
1556
+ description: 'Unauthorized',
1557
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1558
+ },
1559
+ '403': {
1560
+ description: 'Forbidden (Admin only)',
1561
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1562
+ },
1563
+ },
1564
+ },
1565
+ delete: {
1566
+ tags: ['Webhooks'],
1567
+ summary: 'Clear delivery logs',
1568
+ description: 'Deletes delivery log records from the delivery history table (Admin only). Can optionally clear only logs older than a specified number of days.',
1569
+ security: [{ BearerAuth: [] }],
1570
+ parameters: [
1571
+ {
1572
+ name: 'olderThanDays',
1573
+ in: 'query',
1574
+ required: false,
1575
+ schema: { type: 'number', minimum: 0 },
1576
+ description: 'Optionally clear only delivery logs older than this number of days. If omitted, all delivery logs are cleared.',
1577
+ },
1578
+ ],
1579
+ responses: {
1580
+ '200': {
1581
+ description: 'Delivery logs cleared',
1582
+ content: {
1583
+ 'application/json': {
1584
+ schema: {
1585
+ type: 'object',
1586
+ properties: {
1587
+ success: { type: 'boolean' },
1588
+ deletedCount: { type: 'integer' },
1589
+ },
1590
+ },
1591
+ },
1592
+ },
1593
+ },
1594
+ '400': {
1595
+ description: 'Bad Request (invalid olderThanDays parameter)',
1596
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1597
+ },
1598
+ '401': {
1599
+ description: 'Unauthorized',
1600
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1601
+ },
1602
+ '403': {
1603
+ description: 'Forbidden (Admin only)',
1604
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1605
+ },
1606
+ },
1607
+ },
1608
+ };
1609
+ paths[`${apiPrefix}/webhooks/deliveries/{id}`] = {
1610
+ get: {
1611
+ tags: ['Webhooks'],
1612
+ summary: 'Get delivery log details',
1613
+ description: 'Fetches complete request and response payload data for a single delivery log (Admin only).',
1614
+ security: [{ BearerAuth: [] }],
1615
+ parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
1616
+ responses: {
1617
+ '200': {
1618
+ description: 'Delivery log details',
1619
+ content: {
1620
+ 'application/json': {
1621
+ schema: { $ref: '#/components/schemas/WebhookDeliveryModel' },
1622
+ },
1623
+ },
1624
+ },
1625
+ '401': {
1626
+ description: 'Unauthorized',
1627
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1628
+ },
1629
+ '403': {
1630
+ description: 'Forbidden (Admin only)',
1631
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1632
+ },
1633
+ '404': {
1634
+ description: 'Delivery log not found',
1635
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1636
+ },
1637
+ },
1638
+ },
1639
+ };
1640
+ paths[`${apiPrefix}/webhooks/deliveries/{id}/retry`] = {
1641
+ post: {
1642
+ tags: ['Webhooks'],
1643
+ summary: 'Retry webhook delivery',
1644
+ description: 'Manually re-dispatches a delivery attempt to the target endpoint (Admin only).',
1645
+ security: [{ BearerAuth: [] }],
1646
+ parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
1647
+ responses: {
1648
+ '200': {
1649
+ description: 'Retried delivery result',
1650
+ content: {
1651
+ 'application/json': {
1652
+ schema: { $ref: '#/components/schemas/WebhookDeliveryModel' },
1653
+ },
1654
+ },
1655
+ },
1656
+ '401': {
1657
+ description: 'Unauthorized',
1658
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1659
+ },
1660
+ '403': {
1661
+ description: 'Forbidden (Admin only)',
1662
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1663
+ },
1664
+ '404': {
1665
+ description: 'Delivery log not found',
1666
+ content: { 'application/json': { schema: { $ref: '#/components/schemas/ErrorResponse' } } },
1667
+ },
1668
+ },
1669
+ },
1670
+ };
1671
+ paths[`${apiPrefix}/types`] = {
1672
+ get: {
1673
+ tags: ['System'],
1674
+ summary: 'Get TypeScript type definitions',
1675
+ description: 'Returns TypeScript interface definitions generated from the current SQLite collection schema.',
1676
+ responses: {
1677
+ '200': {
1678
+ description: 'TypeScript definitions',
1679
+ content: {
1680
+ 'text/plain': {
1681
+ schema: { type: 'string' },
1682
+ },
1683
+ },
1684
+ },
1685
+ },
1686
+ },
1687
+ };
1688
+ paths[`${apiPrefix}/openapi.json`] = {
1689
+ get: {
1690
+ tags: ['System'],
1691
+ summary: 'OpenAPI 3.0 specification JSON',
1692
+ description: 'Returns this OpenAPI 3.0 specification in JSON format.',
1693
+ responses: {
1694
+ '200': {
1695
+ description: 'OpenAPI 3.0 specification object',
1696
+ content: {
1697
+ 'application/json': {
1698
+ schema: { type: 'object' },
1699
+ },
1700
+ },
1701
+ },
1702
+ },
1703
+ },
1704
+ };
1705
+ // Construct final OpenAPI document
1706
+ return {
1707
+ openapi: '3.0.3',
1708
+ info: {
1709
+ title,
1710
+ version,
1711
+ description,
1712
+ },
1713
+ servers: [
1714
+ {
1715
+ url: serverUrl,
1716
+ description: options.appSlug && options.appSlug !== 'default'
1717
+ ? `${options.appName || options.appSlug} Server`
1718
+ : 'NodeStack Server',
1719
+ },
1720
+ ],
1721
+ tags,
1722
+ paths,
1723
+ components: {
1724
+ securitySchemes: {
1725
+ BearerAuth: {
1726
+ type: 'http',
1727
+ scheme: 'bearer',
1728
+ bearerFormat: 'JWT',
1729
+ description: 'JWT authorization token. Provide your token obtained from `/api/admins/auth-with-password` or `/api/collections/{collection}/auth-with-password`.',
1730
+ },
1731
+ },
1732
+ schemas,
1733
+ },
1734
+ };
1735
+ }
1736
+ static mapFieldToOpenApi(field) {
1737
+ const isMulti = Boolean(field.options?.maxSelect && field.options.maxSelect > 1);
1738
+ let baseSchema = {};
1739
+ switch (field.type) {
1740
+ case 'text':
1741
+ baseSchema = { type: 'string' };
1742
+ if (field.defaultValue !== undefined && field.defaultValue !== null) {
1743
+ baseSchema.default = field.defaultValue;
1744
+ }
1745
+ break;
1746
+ case 'number':
1747
+ baseSchema = { type: 'number' };
1748
+ if (field.defaultValue !== undefined && field.defaultValue !== null) {
1749
+ baseSchema.default = Number(field.defaultValue);
1750
+ }
1751
+ if (field.options?.min !== undefined)
1752
+ baseSchema.minimum = field.options.min;
1753
+ if (field.options?.max !== undefined)
1754
+ baseSchema.maximum = field.options.max;
1755
+ break;
1756
+ case 'bool':
1757
+ baseSchema = { type: 'boolean' };
1758
+ if (field.defaultValue !== undefined && field.defaultValue !== null) {
1759
+ baseSchema.default = Boolean(field.defaultValue);
1760
+ }
1761
+ break;
1762
+ case 'email':
1763
+ baseSchema = { type: 'string', format: 'email' };
1764
+ break;
1765
+ case 'url':
1766
+ baseSchema = { type: 'string', format: 'uri' };
1767
+ break;
1768
+ case 'date':
1769
+ baseSchema = { type: 'string', format: 'date-time' };
1770
+ break;
1771
+ case 'select': {
1772
+ const values = Array.isArray(field.options?.values) ? field.options.values : [];
1773
+ if (isMulti) {
1774
+ return {
1775
+ type: 'array',
1776
+ items: { type: 'string', ...(values.length > 0 ? { enum: values } : {}) },
1777
+ };
1778
+ }
1779
+ return {
1780
+ type: 'string',
1781
+ ...(values.length > 0 ? { enum: values } : {}),
1782
+ ...(field.defaultValue !== undefined ? { default: field.defaultValue } : {}),
1783
+ };
1784
+ }
1785
+ case 'json':
1786
+ return { type: 'object', additionalProperties: true };
1787
+ case 'file':
1788
+ if (isMulti) {
1789
+ return {
1790
+ type: 'array',
1791
+ items: { type: 'string', description: 'Stored file filename' },
1792
+ };
1793
+ }
1794
+ return { type: 'string', description: 'Stored file filename' };
1795
+ case 'relation':
1796
+ if (isMulti) {
1797
+ return {
1798
+ type: 'array',
1799
+ items: { type: 'string' },
1800
+ description: `Array of target record IDs (Collection: '${field.options?.collectionId || 'unknown'}')`,
1801
+ };
1802
+ }
1803
+ return {
1804
+ type: 'string',
1805
+ description: `Target record ID (Collection: '${field.options?.collectionId || 'unknown'}')`,
1806
+ };
1807
+ default:
1808
+ baseSchema = { type: 'string' };
1809
+ }
1810
+ if (isMulti) {
1811
+ return {
1812
+ type: 'array',
1813
+ items: baseSchema,
1814
+ };
1815
+ }
1816
+ return baseSchema;
1817
+ }
1818
+ static describeRule(rule) {
1819
+ if (rule === null || rule === undefined) {
1820
+ return '`Admin only` 🔒';
1821
+ }
1822
+ if (rule === '') {
1823
+ return '`Public` 🌐 (Anyone can perform this action)';
1824
+ }
1825
+ return `\`${rule}\` 🔑 (Requires authentication satisfying rule condition)`;
1826
+ }
1827
+ static toPascalCase(str) {
1828
+ if (!str)
1829
+ return 'Item';
1830
+ const cleaned = str.replace(/[^a-zA-Z0-9]+(.)/g, (_, chr) => chr.toUpperCase());
1831
+ const result = cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
1832
+ return /^[a-zA-Z_$]/.test(result) ? result : `Col_${result}`;
1833
+ }
1834
+ }
1835
+ exports.OpenApiGenerator = OpenApiGenerator;
1836
+ //# sourceMappingURL=OpenApiGenerator.js.map