@terreno/api 57.3.0 → 57.6.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 (412) hide show
  1. package/.ai/skills/mongoose-schema-safety/SKILL.md +23 -10
  2. package/README.md +11 -5
  3. package/bunfig.toml +1 -1
  4. package/dist/actions.js +197 -368
  5. package/dist/adminModelRouter.js +88 -173
  6. package/dist/adminTypes.d.ts +7 -0
  7. package/dist/adminTypes.js +6 -1
  8. package/dist/api.d.ts +10 -0
  9. package/dist/api.js +601 -792
  10. package/dist/audit/auditApp.d.ts +30 -0
  11. package/dist/audit/auditApp.js +114 -0
  12. package/dist/audit/auditEventModel.d.ts +29 -0
  13. package/dist/audit/auditEventModel.js +101 -0
  14. package/dist/audit/cloudTasksEnqueue.d.ts +32 -0
  15. package/dist/audit/cloudTasksEnqueue.js +69 -0
  16. package/dist/audit/diff.d.ts +10 -0
  17. package/dist/audit/diff.js +140 -0
  18. package/dist/audit/processQueue.d.ts +6 -0
  19. package/dist/audit/processQueue.js +56 -0
  20. package/dist/audit/rbacSink.d.ts +2 -0
  21. package/dist/audit/rbacSink.js +41 -0
  22. package/dist/audit/record.d.ts +56 -0
  23. package/dist/audit/record.js +251 -0
  24. package/dist/auth.js +432 -681
  25. package/dist/authRecovery.js +155 -269
  26. package/dist/authTokens.js +43 -118
  27. package/dist/betterAuth.d.ts +6 -0
  28. package/dist/betterAuthApp.js +25 -26
  29. package/dist/betterAuthSetup.js +258 -413
  30. package/dist/browserLogsRoute.d.ts +6 -0
  31. package/dist/browserLogsRoute.js +97 -0
  32. package/dist/collectionRegistry.d.ts +3 -1
  33. package/dist/collectionRegistry.js +43 -33
  34. package/dist/config.js +53 -122
  35. package/dist/configurationApp.js +180 -361
  36. package/dist/configurationPlugin.js +130 -302
  37. package/dist/consentApp.js +276 -421
  38. package/dist/docLoader.js +78 -126
  39. package/dist/envConfigurationPlugin.js +25 -147
  40. package/dist/errors.js +151 -247
  41. package/dist/example.js +28 -34
  42. package/dist/expressServer.d.ts +10 -0
  43. package/dist/expressServer.js +109 -255
  44. package/dist/frameworkModelNames.d.ts +24 -0
  45. package/dist/frameworkModelNames.js +31 -0
  46. package/dist/githubAuth.js +152 -216
  47. package/dist/httpClient.js +176 -264
  48. package/dist/index.d.ts +28 -1
  49. package/dist/index.js +53 -2
  50. package/dist/logger.js +145 -278
  51. package/dist/mcp/auth.js +76 -128
  52. package/dist/mcp/createMCPRequest.js +4 -5
  53. package/dist/mcp/handlers.js +268 -480
  54. package/dist/mcp/query.d.ts +0 -13
  55. package/dist/mcp/query.js +57 -151
  56. package/dist/mcp/registry.js +17 -30
  57. package/dist/mcp/schemaGenerator.js +95 -181
  58. package/dist/mcp/server.js +28 -100
  59. package/dist/mcp/serviceTokens.js +102 -191
  60. package/dist/mcp/toolGenerator.js +78 -191
  61. package/dist/middleware.js +15 -27
  62. package/dist/migrations/fixtures/all-down/20260910120000-one.d.ts +4 -0
  63. package/dist/migrations/fixtures/all-down/20260910120000-one.js +9 -0
  64. package/dist/migrations/fixtures/all-down/20260910120001-two.d.ts +4 -0
  65. package/dist/migrations/fixtures/all-down/20260910120001-two.js +9 -0
  66. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.d.ts +3 -0
  67. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.js +7 -0
  68. package/dist/migrations/fixtures/bad-name/not-a-migration.d.ts +3 -0
  69. package/dist/migrations/fixtures/bad-name/not-a-migration.js +7 -0
  70. package/dist/migrations/fixtures/missing-up/20260910120000-noup.d.ts +2 -0
  71. package/dist/migrations/fixtures/missing-up/20260910120000-noup.js +5 -0
  72. package/dist/migrations/fixtures/valid/20260910120000-alpha.d.ts +3 -0
  73. package/dist/migrations/fixtures/valid/20260910120000-alpha.js +7 -0
  74. package/dist/migrations/fixtures/valid/20260910120001-beta.d.ts +4 -0
  75. package/dist/migrations/fixtures/valid/20260910120001-beta.js +9 -0
  76. package/dist/migrations/generate.d.ts +17 -0
  77. package/dist/migrations/generate.js +155 -0
  78. package/dist/migrations/load.d.ts +20 -0
  79. package/dist/migrations/load.js +110 -0
  80. package/dist/migrations/lock.d.ts +13 -0
  81. package/dist/migrations/lock.js +73 -0
  82. package/dist/migrations/runner.d.ts +42 -0
  83. package/dist/migrations/runner.js +249 -0
  84. package/dist/migrations/schemaCatalog.d.ts +44 -0
  85. package/dist/migrations/schemaCatalog.js +185 -0
  86. package/dist/migrations/types.d.ts +87 -0
  87. package/dist/migrations/types.js +7 -0
  88. package/dist/models/consentForm.js +6 -6
  89. package/dist/models/consentResponse.js +5 -5
  90. package/dist/models/mcpServiceToken.js +66 -156
  91. package/dist/models/notification.d.ts +2 -0
  92. package/dist/models/notification.js +62 -0
  93. package/dist/models/notificationPreference.d.ts +2 -0
  94. package/dist/models/notificationPreference.js +49 -0
  95. package/dist/models/versionConfig.js +5 -5
  96. package/dist/notifications/notificationService.d.ts +40 -0
  97. package/dist/notifications/notificationService.js +183 -0
  98. package/dist/notifications/notificationsApp.d.ts +18 -0
  99. package/dist/notifications/notificationsApp.js +156 -0
  100. package/dist/notifications/notificationsBeforeSend.d.ts +14 -0
  101. package/dist/notifications/notificationsBeforeSend.js +32 -0
  102. package/dist/notifiers/googleChatNotifier.js +36 -117
  103. package/dist/notifiers/slackNotifier.d.ts +31 -2
  104. package/dist/notifiers/slackNotifier.js +170 -119
  105. package/dist/notifiers/zoomNotifier.js +60 -111
  106. package/dist/openApi.d.ts +1 -7
  107. package/dist/openApi.js +113 -127
  108. package/dist/openApiBuilder.d.ts +14 -3
  109. package/dist/openApiBuilder.js +117 -159
  110. package/dist/openApiCompat.js +81 -148
  111. package/dist/openApiEtag.js +7 -7
  112. package/dist/openApiValidator.d.ts +13 -1
  113. package/dist/openApiValidator.js +301 -246
  114. package/dist/orgs/orgContext.d.ts +23 -0
  115. package/dist/orgs/orgContext.js +128 -0
  116. package/dist/orgs/orgPermissions.d.ts +4 -0
  117. package/dist/orgs/orgPermissions.js +38 -0
  118. package/dist/orgs/orgPlugin.d.ts +13 -0
  119. package/dist/orgs/orgPlugin.js +66 -0
  120. package/dist/orgs/organizationModel.d.ts +13 -0
  121. package/dist/orgs/organizationModel.js +200 -0
  122. package/dist/orgs/organizationSettings.d.ts +19 -0
  123. package/dist/orgs/organizationSettings.js +113 -0
  124. package/dist/orgs/orgsApp.d.ts +28 -0
  125. package/dist/orgs/orgsApp.js +416 -0
  126. package/dist/permissions.d.ts +7 -13
  127. package/dist/permissions.js +95 -211
  128. package/dist/plugins.js +125 -218
  129. package/dist/populate.js +130 -240
  130. package/dist/rateLimit/applyTrustProxy.js +1 -1
  131. package/dist/rateLimit/createStore.js +7 -8
  132. package/dist/rateLimit/memoryStore.js +22 -100
  133. package/dist/rateLimit/middleware.d.ts +0 -8
  134. package/dist/rateLimit/middleware.js +49 -101
  135. package/dist/rateLimit/mongoStore.d.ts +1 -0
  136. package/dist/rateLimit/mongoStore.js +55 -112
  137. package/dist/rateLimit/policies.d.ts +0 -4
  138. package/dist/rateLimit/policies.js +44 -80
  139. package/dist/rateLimit/redisStore.d.ts +1 -0
  140. package/dist/rateLimit/redisStore.js +40 -133
  141. package/dist/rbac/access.js +122 -253
  142. package/dist/rbac/assertAllowed.js +95 -171
  143. package/dist/rbac/auditModel.js +14 -58
  144. package/dist/rbac/backfillAdmins.js +24 -130
  145. package/dist/rbac/fieldViews.js +46 -141
  146. package/dist/rbac/membershipOrgAdminSource.d.ts +6 -0
  147. package/dist/rbac/membershipOrgAdminSource.js +51 -0
  148. package/dist/rbac/middleware.js +30 -96
  149. package/dist/rbac/modelRouterAccess.d.ts +3 -0
  150. package/dist/rbac/modelRouterAccess.js +133 -307
  151. package/dist/rbac/permissionUtils.js +40 -179
  152. package/dist/rbac/realtimeAccess.js +81 -147
  153. package/dist/rbac/resolve.d.ts +1 -1
  154. package/dist/rbac/resolve.js +154 -319
  155. package/dist/rbac/roleManager.js +318 -700
  156. package/dist/rbac/roleModel.d.ts +2 -5
  157. package/dist/rbac/roleModel.js +60 -173
  158. package/dist/rbac/routes.js +93 -196
  159. package/dist/rbac/scopes.js +39 -133
  160. package/dist/rbac/statements.d.ts +10 -1
  161. package/dist/rbac/statements.js +42 -93
  162. package/dist/rbac/types.d.ts +5 -0
  163. package/dist/rbac/userPlugin.js +3 -29
  164. package/dist/realtime/changeStreamWatcher.d.ts +10 -4
  165. package/dist/realtime/changeStreamWatcher.js +499 -764
  166. package/dist/realtime/deprecation.d.ts +1 -0
  167. package/dist/realtime/deprecation.js +9 -10
  168. package/dist/realtime/queryMatcher.js +110 -191
  169. package/dist/realtime/queryStore.js +35 -118
  170. package/dist/realtime/realtimeApp.d.ts +1 -0
  171. package/dist/realtime/realtimeApp.js +248 -401
  172. package/dist/realtime/registry.js +19 -30
  173. package/dist/realtime/sessionRevalidation.js +132 -358
  174. package/dist/realtime/socketAuth.js +89 -208
  175. package/dist/realtime/socketUser.js +10 -56
  176. package/dist/requestContext.js +93 -139
  177. package/dist/schemaMetadata.js +181 -265
  178. package/dist/scriptRunner.js +96 -266
  179. package/dist/scrubAdminFields.js +36 -108
  180. package/dist/secretProviders.js +130 -299
  181. package/dist/seedRunner.js +221 -514
  182. package/dist/sync/adminBroadcastScope.d.ts +40 -0
  183. package/dist/sync/adminBroadcastScope.js +82 -0
  184. package/dist/sync/adminWindowAccess.d.ts +13 -0
  185. package/dist/sync/adminWindowAccess.js +25 -0
  186. package/dist/sync/adminWindowMutation.d.ts +88 -0
  187. package/dist/sync/adminWindowMutation.js +176 -0
  188. package/dist/sync/executors.d.ts +9 -3
  189. package/dist/sync/executors.js +425 -598
  190. package/dist/sync/loadHarness.js +392 -689
  191. package/dist/sync/models.js +181 -341
  192. package/dist/sync/mutationHandler.d.ts +5 -2
  193. package/dist/sync/mutationHandler.js +549 -697
  194. package/dist/sync/registrationSideEffects.js +41 -95
  195. package/dist/sync/registry.js +31 -47
  196. package/dist/sync/routes.d.ts +13 -0
  197. package/dist/sync/routes.js +484 -760
  198. package/dist/sync/scripts/compactTombstones.js +83 -228
  199. package/dist/sync/serialize.js +18 -58
  200. package/dist/sync/socketHandlers.d.ts +8 -2
  201. package/dist/sync/socketHandlers.js +271 -402
  202. package/dist/sync/streams.d.ts +2 -0
  203. package/dist/sync/streams.js +54 -116
  204. package/dist/sync/syncApp.d.ts +2 -1
  205. package/dist/sync/syncApp.js +14 -16
  206. package/dist/sync/syncBatch.d.ts +5 -2
  207. package/dist/sync/syncBatch.js +63 -168
  208. package/dist/sync/syncSeqPlugin.js +430 -702
  209. package/dist/sync/types.d.ts +18 -0
  210. package/dist/syncConsents.js +113 -253
  211. package/dist/terrenoApp.d.ts +29 -0
  212. package/dist/terrenoApp.js +184 -257
  213. package/dist/tests/createTestData.d.ts +1 -3
  214. package/dist/tests/createTestData.js +147 -259
  215. package/dist/tests/models.d.ts +1 -0
  216. package/dist/tests/models.js +23 -56
  217. package/dist/tests/mongoTestSetup.js +42 -103
  218. package/dist/tests/testHelper.d.ts +0 -5
  219. package/dist/tests/testHelper.js +32 -101
  220. package/dist/tests.js +12 -51
  221. package/dist/transformers.js +61 -164
  222. package/dist/types/authToken.d.ts +3 -3
  223. package/dist/types/mcpServiceToken.d.ts +2 -2
  224. package/dist/types/membership.d.ts +23 -0
  225. package/dist/types/membership.js +2 -0
  226. package/dist/types/notification.d.ts +28 -0
  227. package/dist/types/notification.js +2 -0
  228. package/dist/types/notificationPreference.d.ts +20 -0
  229. package/dist/types/notificationPreference.js +2 -0
  230. package/dist/types/organization.d.ts +36 -0
  231. package/dist/types/organization.js +2 -0
  232. package/dist/utils.js +31 -93
  233. package/dist/vendor/wesleytodd-openapi/index.js +37 -51
  234. package/dist/vendor/wesleytodd-openapi/lib/generate-doc.js +32 -40
  235. package/dist/vendor/wesleytodd-openapi/lib/layer-schema.js +3 -3
  236. package/dist/vendor/wesleytodd-openapi/lib/ui.js +50 -19
  237. package/dist/vendor/wesleytodd-openapi/lib/validate.js +19 -47
  238. package/dist/versionCheckPlugin.js +52 -100
  239. package/dist/webhooks/headerValue.js +2 -2
  240. package/dist/webhooks/idempotency/memoryStore.js +16 -59
  241. package/dist/webhooks/idempotency/mongoStore.js +55 -130
  242. package/dist/webhooks/idempotency/webhookReceipt.d.ts +4 -49
  243. package/dist/webhooks/idempotency/webhookReceipt.js +14 -14
  244. package/dist/webhooks/rawBody.d.ts +1 -0
  245. package/dist/webhooks/rawBody.js +2 -1
  246. package/dist/webhooks/timingSafeEqual.js +4 -5
  247. package/dist/webhooks/verifiers/hmac.js +17 -18
  248. package/dist/webhooks/verifiers/sendgrid.js +20 -22
  249. package/dist/webhooks/verifiers/stripe.js +31 -65
  250. package/dist/webhooks/verifiers/twilio.js +23 -73
  251. package/dist/webhooks/webhooksApp.js +78 -177
  252. package/dist/zodOpenApi.js +2 -2
  253. package/package.json +34 -28
  254. package/src/__snapshots__/openApi.test.ts.snap +192 -54
  255. package/src/__snapshots__/openApiBuilder.test.ts.snap +0 -18
  256. package/src/__snapshots__/schemaMetadata.test.ts.snap +0 -1
  257. package/src/__tests__/browserLogsRoute.test.ts +165 -0
  258. package/src/adminTypes.ts +8 -0
  259. package/src/api.test.ts +39 -2
  260. package/src/api.ts +68 -0
  261. package/src/audit/auditApp.test.ts +243 -0
  262. package/src/audit/auditApp.ts +139 -0
  263. package/src/audit/auditEventModel.ts +160 -0
  264. package/src/audit/auditRouter.test.ts +456 -0
  265. package/src/audit/cloudTasksEnqueue.test.ts +124 -0
  266. package/src/audit/cloudTasksEnqueue.ts +104 -0
  267. package/src/audit/diff.ts +163 -0
  268. package/src/audit/processQueue.ts +69 -0
  269. package/src/audit/rbacSink.test.ts +86 -0
  270. package/src/audit/rbacSink.ts +42 -0
  271. package/src/audit/record.test.ts +402 -0
  272. package/src/audit/record.ts +329 -0
  273. package/src/auth.test.ts +1 -1
  274. package/src/auth.ts +1 -1
  275. package/src/authRecovery.test.ts +43 -0
  276. package/src/authRecovery.ts +16 -10
  277. package/src/authTokens.ts +6 -2
  278. package/src/authVerification.test.ts +22 -0
  279. package/src/betterAuth.ts +7 -0
  280. package/src/betterAuthSetup.test.ts +27 -0
  281. package/src/betterAuthSetup.ts +1 -0
  282. package/src/browserLogsRoute.ts +110 -0
  283. package/src/collectionRegistry.test.ts +8 -9
  284. package/src/collectionRegistry.ts +21 -1
  285. package/src/configurationPlugin.test.ts +1 -11
  286. package/src/express.d.ts +2 -0
  287. package/src/expressServer.test.ts +50 -2
  288. package/src/expressServer.ts +10 -0
  289. package/src/frameworkModelNames.test.ts +62 -0
  290. package/src/frameworkModelNames.ts +33 -0
  291. package/src/index.ts +76 -0
  292. package/src/isolated/migrateCliConnect.isolated.ts +51 -0
  293. package/src/mcp/auth.test.ts +34 -1
  294. package/src/mcp/handlers.test.ts +275 -0
  295. package/src/mcp/query.ts +3 -3
  296. package/src/mcp/toolGenerator.test.ts +81 -0
  297. package/src/migrations/cli.test.ts +353 -0
  298. package/src/migrations/cli.ts +283 -0
  299. package/src/migrations/fixtures/all-down/20260910120000-one.ts +6 -0
  300. package/src/migrations/fixtures/all-down/20260910120001-two.ts +6 -0
  301. package/src/migrations/fixtures/bad-id/20260910120000-mismatch.ts +4 -0
  302. package/src/migrations/fixtures/bad-name/not-a-migration.ts +4 -0
  303. package/src/migrations/fixtures/missing-up/20260910120000-noup.ts +2 -0
  304. package/src/migrations/fixtures/valid/20260910120000-alpha.ts +4 -0
  305. package/src/migrations/fixtures/valid/20260910120001-beta.ts +6 -0
  306. package/src/migrations/generate.test.ts +333 -0
  307. package/src/migrations/generate.ts +216 -0
  308. package/src/migrations/load.test.ts +103 -0
  309. package/src/migrations/load.ts +124 -0
  310. package/src/migrations/lock.test.ts +133 -0
  311. package/src/migrations/lock.ts +118 -0
  312. package/src/migrations/runner.test.ts +504 -0
  313. package/src/migrations/runner.ts +358 -0
  314. package/src/migrations/schemaCatalog.test.ts +159 -0
  315. package/src/migrations/schemaCatalog.ts +262 -0
  316. package/src/migrations/types.ts +94 -0
  317. package/src/models/mcpServiceToken.ts +4 -3
  318. package/src/models/notification.ts +69 -0
  319. package/src/models/notificationPreference.ts +62 -0
  320. package/src/notifications/notificationService.ts +254 -0
  321. package/src/notifications/notificationsApp.test.ts +528 -0
  322. package/src/notifications/notificationsApp.ts +200 -0
  323. package/src/notifications/notificationsBeforeSend.ts +51 -0
  324. package/src/notifiers/slackNotifier.test.ts +186 -1
  325. package/src/notifiers/slackNotifier.ts +167 -8
  326. package/src/openApi.test.ts +0 -1
  327. package/src/openApi.ts +2 -1
  328. package/src/openApiBuilder.ts +14 -3
  329. package/src/openApiValidator.test.ts +221 -2
  330. package/src/openApiValidator.ts +218 -33
  331. package/src/orgs/orgAccessOptIn.test.ts +87 -0
  332. package/src/orgs/orgContext.test.ts +259 -0
  333. package/src/orgs/orgContext.ts +151 -0
  334. package/src/orgs/orgPermissions.test.ts +105 -0
  335. package/src/orgs/orgPermissions.ts +40 -0
  336. package/src/orgs/orgPlugin.test.ts +130 -0
  337. package/src/orgs/orgPlugin.ts +70 -0
  338. package/src/orgs/orgRbac.test.ts +267 -0
  339. package/src/orgs/orgSecurityDefects.test.ts +415 -0
  340. package/src/orgs/organizationModel.test.ts +205 -0
  341. package/src/orgs/organizationModel.ts +262 -0
  342. package/src/orgs/organizationSettings.test.ts +113 -0
  343. package/src/orgs/organizationSettings.ts +126 -0
  344. package/src/orgs/orgsApp.test.ts +382 -0
  345. package/src/orgs/orgsApp.ts +563 -0
  346. package/src/permissions.test.ts +62 -36
  347. package/src/permissions.ts +8 -30
  348. package/src/plugins.test.ts +5 -0
  349. package/src/plugins.ts +3 -0
  350. package/src/rateLimit/middleware.ts +1 -1
  351. package/src/rateLimit/mongoStore.ts +1 -0
  352. package/src/rateLimit/policies.ts +2 -2
  353. package/src/rateLimit/redisStore.ts +1 -0
  354. package/src/rbac/access.ts +11 -3
  355. package/src/rbac/membershipOrgAdminSource.ts +59 -0
  356. package/src/rbac/modelRouterAccess.ts +3 -0
  357. package/src/rbac/permissionUtils.test.ts +26 -5
  358. package/src/rbac/resolve.test.ts +34 -2
  359. package/src/rbac/resolve.ts +26 -7
  360. package/src/rbac/roleModel.test.ts +34 -1
  361. package/src/rbac/roleModel.ts +17 -1
  362. package/src/rbac/statements.test.ts +19 -0
  363. package/src/rbac/statements.ts +19 -1
  364. package/src/rbac/types.ts +5 -0
  365. package/src/realtime/changeStreamWatcher.ts +73 -33
  366. package/src/realtime/deprecation.ts +1 -0
  367. package/src/realtime/realtime.test.ts +357 -185
  368. package/src/realtime/realtimeApp.ts +2 -1
  369. package/src/schemaMetadata.test.ts +14 -0
  370. package/src/schemaMetadata.ts +5 -5
  371. package/src/sync/adminBroadcastConfig.test.ts +96 -0
  372. package/src/sync/adminBroadcastScope.test.ts +155 -0
  373. package/src/sync/adminBroadcastScope.ts +123 -0
  374. package/src/sync/adminWindowAccess.test.ts +57 -0
  375. package/src/sync/adminWindowAccess.ts +32 -0
  376. package/src/sync/adminWindowMutation.test.ts +450 -0
  377. package/src/sync/adminWindowMutation.ts +283 -0
  378. package/src/sync/executors.ts +33 -6
  379. package/src/sync/integration.test.ts +2 -2
  380. package/src/sync/mutationHandler.test.ts +277 -1
  381. package/src/sync/mutationHandler.ts +171 -29
  382. package/src/sync/registry.ts +4 -0
  383. package/src/sync/routes.ts +52 -8
  384. package/src/sync/socketHandlers.ts +154 -58
  385. package/src/sync/streams.ts +6 -0
  386. package/src/sync/sync.test.ts +3 -2
  387. package/src/sync/syncApp.ts +2 -1
  388. package/src/sync/syncBatch.ts +7 -2
  389. package/src/sync/syncRoutes.test.ts +297 -3
  390. package/src/sync/syncSocket.test.ts +229 -0
  391. package/src/sync/types.ts +20 -0
  392. package/src/terrenoApp.migrations.test.ts +114 -0
  393. package/src/terrenoApp.test.ts +41 -0
  394. package/src/terrenoApp.ts +97 -31
  395. package/src/tests/createTestData.ts +2 -2
  396. package/src/tests/models.ts +10 -2
  397. package/src/tests/testHelper.ts +1 -7
  398. package/src/types/authToken.ts +2 -4
  399. package/src/types/mcpServiceToken.ts +1 -7
  400. package/src/types/membership.ts +48 -0
  401. package/src/types/notification.ts +34 -0
  402. package/src/types/notificationPreference.ts +28 -0
  403. package/src/types/organization.ts +49 -0
  404. package/src/types.d.ts +1 -0
  405. package/src/webhooks/idempotency/webhookReceipt.ts +8 -10
  406. package/src/webhooks/rawBody.test.ts +33 -0
  407. package/src/webhooks/rawBody.ts +1 -0
  408. package/tsconfig.json +13 -54
  409. package/tsconfig.typedoc.json +4 -1
  410. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.d.ts +0 -2
  411. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
  412. package/src/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
@@ -118,19 +118,30 @@ const composeRequestHandlers = (handlers: express.RequestHandler[]): express.Req
118
118
  */
119
119
  export interface OpenApiSchemaProperty {
120
120
  /** The JSON Schema type (e.g., "string", "number", "boolean", "object", "array") */
121
- type: string;
121
+ type?: string;
122
+ /** JSON Schema oneOf for query operators (scalar or Mongo-style object). */
123
+ oneOf?: OpenApiSchemaProperty[];
122
124
  /** Human-readable description of the property */
123
125
  description?: string;
126
+ /** Allowed values for string/number enums in query validation. */
127
+ enum?: string[];
124
128
  /** Format hint for the type (e.g., "date-time", "email", "uri", "uuid") */
125
129
  format?: string;
126
130
  /** Schema for array items when type is "array" */
127
131
  items?: OpenApiSchemaProperty;
132
+ /** Minimum array length when type is "array". */
133
+ minItems?: number;
128
134
  /** Nested properties when type is "object" */
129
135
  properties?: Record<string, OpenApiSchemaProperty>;
130
136
  /** Schema for additional properties or boolean to allow/disallow them */
131
137
  additionalProperties?: OpenApiSchemaProperty | boolean;
132
- /** Whether this property is required in the parent object */
133
- required?: boolean;
138
+ /**
139
+ * Property-level required flag, or object-schema required key list for nested
140
+ * operator shapes (`{$in: ...}`, `{$regex: ...}`).
141
+ */
142
+ required?: boolean | string[];
143
+ /** When true, string values must be escaped regex literals (query `$regex` operator). */
144
+ escapedRegexLiteral?: boolean;
134
145
  }
135
146
 
136
147
  /**
@@ -1,7 +1,9 @@
1
1
  import {afterEach, beforeEach, describe, expect, it} from "bun:test";
2
2
  import type {ErrorObject} from "ajv";
3
3
  import type {NextFunction, Request, Response} from "express";
4
+ import mongoose from "mongoose";
4
5
 
6
+ import {ADMIN_LIST_CHOICE_EMPTY_VALUE} from "./adminTypes";
5
7
  import {modelRouter} from "./api";
6
8
  import {type UserModel as AuthUserModel, addAuthRoutes, setupAuth} from "./auth";
7
9
  import type {OpenApiSchemaProperty} from "./openApiBuilder";
@@ -12,6 +14,7 @@ import {
12
14
  createValidator,
13
15
  getOpenApiValidatorConfig,
14
16
  getSchemaFromModel,
17
+ isEscapedRegexLiteral,
15
18
  isOpenApiValidatorConfigured,
16
19
  resetOpenApiValidatorConfig,
17
20
  validateModelRequestBody,
@@ -111,6 +114,22 @@ describe("openApiValidator", () => {
111
114
  const res = await admin.post("/required").send({about: "no name"}).expect(400);
112
115
  expect(res.body.title).toBe("Request validation failed");
113
116
  });
117
+
118
+ it("allows PATCH bodies that omit mongoose required fields", async () => {
119
+ configureOpenApiValidator();
120
+
121
+ const freshApp = await setupFreshApp();
122
+ freshApp.use("/required", modelRouter(RequiredModel, requiredRouterOptions));
123
+ const admin = await authAsUser(freshApp, "admin");
124
+ const created = await admin.post("/required").send({name: "Apple"}).expect(201);
125
+
126
+ const patched = await admin
127
+ .patch(`/required/${created.body.data._id}`)
128
+ .send({about: "partial"})
129
+ .expect(200);
130
+ expect(patched.body.data.name).toBe("Apple");
131
+ expect(patched.body.data.about).toBe("partial");
132
+ });
114
133
  });
115
134
 
116
135
  describe("onAdditionalPropertiesRemoved hook", () => {
@@ -266,9 +285,133 @@ describe("openApiValidator", () => {
266
285
  expect(schema.hidden).toBeUndefined();
267
286
  });
268
287
 
269
- it("marks query fields as not required", () => {
288
+ it("does not mark query fields as required", () => {
270
289
  const schema = buildQuerySchemaFromFields(FoodModel, ["name"]);
271
- expect(schema.name.required).toBe(false);
290
+ expect(schema.name.required).toBeUndefined();
291
+ });
292
+ });
293
+
294
+ describe("choice list query validation", () => {
295
+ const priorityListSchema = new mongoose.Schema({
296
+ name: {required: true, type: String},
297
+ priority: {enum: ["low", "high"], type: String},
298
+ });
299
+ const PriorityListModel =
300
+ mongoose.models.OpenApiPriorityList ??
301
+ mongoose.model("OpenApiPriorityList", priorityListSchema);
302
+
303
+ const assertQueryAccepted = (query: Record<string, unknown>): void => {
304
+ configureOpenApiValidator({coerceTypes: true});
305
+ const schema = buildQuerySchemaFromFields(PriorityListModel, ["priority"]);
306
+ const middleware = validateQueryParams(schema);
307
+ let nextCalled = false;
308
+ const req = {method: "GET", path: "/test", query: {...query}} as unknown as Request;
309
+ middleware(req, {} as Response, () => {
310
+ nextCalled = true;
311
+ });
312
+ expect(nextCalled).toBe(true);
313
+ };
314
+
315
+ it("accepts scalar and $in choice query shapes", () => {
316
+ assertQueryAccepted({limit: "25", page: "1", priority: "high"});
317
+ assertQueryAccepted({limit: "25", page: "1", priority: {$in: ["high"]}});
318
+ assertQueryAccepted({
319
+ limit: "25",
320
+ page: "1",
321
+ priority: {$in: ["high", ADMIN_LIST_CHOICE_EMPTY_VALUE]},
322
+ });
323
+ });
324
+
325
+ it("rejects invalid choice query shapes", () => {
326
+ configureOpenApiValidator({coerceTypes: true});
327
+ const schema = buildQuerySchemaFromFields(PriorityListModel, ["priority"]);
328
+ const middleware = validateQueryParams(schema);
329
+ const req = {
330
+ method: "GET",
331
+ path: "/test",
332
+ query: {limit: "25", page: "1", priority: {$in: ["high", "missing"]}},
333
+ } as unknown as Request;
334
+
335
+ expect(() => {
336
+ middleware(req, {} as Response, () => {});
337
+ }).toThrow();
338
+ });
339
+ });
340
+
341
+ describe("isEscapedRegexLiteral", () => {
342
+ it("accepts literal text and escaped metacharacters", () => {
343
+ expect(isEscapedRegexLiteral("alice")).toBe(true);
344
+ expect(isEscapedRegexLiteral("\\.\\*")).toBe(true);
345
+ });
346
+
347
+ it("rejects executable regex patterns", () => {
348
+ expect(isEscapedRegexLiteral(".*")).toBe(false);
349
+ expect(isEscapedRegexLiteral("^x")).toBe(false);
350
+ expect(isEscapedRegexLiteral("[a-z]")).toBe(false);
351
+ });
352
+ });
353
+
354
+ describe("query operator hardening", () => {
355
+ const assertQueryRejected = (query: Record<string, unknown>): void => {
356
+ configureOpenApiValidator({coerceTypes: true, removeAdditional: false});
357
+ const schema = buildQuerySchemaFromFields(FoodModel, ["name"]);
358
+ const middleware = validateQueryParams(schema);
359
+ const req = {method: "GET", path: "/test", query: {...query}} as unknown as Request;
360
+
361
+ expect(() => {
362
+ middleware(req, {} as Response, () => {});
363
+ }).toThrow();
364
+ };
365
+
366
+ const assertQueryAccepted = (query: Record<string, unknown>): void => {
367
+ configureOpenApiValidator({coerceTypes: true, removeAdditional: false});
368
+ const schema = buildQuerySchemaFromFields(FoodModel, ["name"]);
369
+ const middleware = validateQueryParams(schema);
370
+ let nextCalled = false;
371
+ const req = {method: "GET", path: "/test", query: {...query}} as unknown as Request;
372
+ middleware(req, {} as Response, () => {
373
+ nextCalled = true;
374
+ });
375
+ expect(nextCalled).toBe(true);
376
+ };
377
+
378
+ it("accepts escaped literal regex operators", () => {
379
+ assertQueryAccepted({
380
+ name: {$options: "i", $regex: "Green Beans"},
381
+ });
382
+ assertQueryAccepted({
383
+ name: {$options: "i", $regex: "\\.\\*"},
384
+ });
385
+ });
386
+
387
+ it("rejects executable regex operators even when removeAdditional is false", () => {
388
+ assertQueryRejected({
389
+ name: {$options: "i", $regex: ".*"},
390
+ });
391
+ assertQueryRejected({
392
+ name: {$options: "i", $regex: "^x"},
393
+ });
394
+ });
395
+
396
+ it("rejects extra nested operators on $in objects", () => {
397
+ assertQueryRejected({
398
+ name: {$in: ["Apple"], $ne: "Banana"},
399
+ });
400
+ });
401
+
402
+ it("rejects extra nested operators on range objects", () => {
403
+ configureOpenApiValidator({coerceTypes: true, removeAdditional: false});
404
+ const schema = buildQuerySchemaFromFields(FoodModel, ["calories"]);
405
+ const middleware = validateQueryParams(schema);
406
+ const req = {
407
+ method: "GET",
408
+ path: "/test",
409
+ query: {calories: {$gte: 1, $where: "1"}},
410
+ } as unknown as Request;
411
+
412
+ expect(() => {
413
+ middleware(req, {} as Response, () => {});
414
+ }).toThrow();
272
415
  });
273
416
  });
274
417
 
@@ -725,6 +868,23 @@ describe("openApiValidator", () => {
725
868
 
726
869
  expect(nextCalled).toBe(true);
727
870
  });
871
+
872
+ it("does not require mongoose required fields when partial is true", () => {
873
+ const middleware = validateModelRequestBody(RequiredModel, {partial: true});
874
+
875
+ let nextCalled = false;
876
+ const req = {
877
+ body: {about: "only about"},
878
+ method: "PATCH",
879
+ path: "/required",
880
+ } as unknown as Request;
881
+ const res = {} as Response;
882
+ middleware(req, res, () => {
883
+ nextCalled = true;
884
+ });
885
+
886
+ expect(nextCalled).toBe(true);
887
+ });
728
888
  });
729
889
 
730
890
  describe("getSchemaFromModel", () => {
@@ -733,6 +893,65 @@ describe("openApiValidator", () => {
733
893
  expect(schema.name).toBeDefined();
734
894
  expect(schema.about).toBeDefined();
735
895
  });
896
+
897
+ it("puts enum constraints on array items, not the array property", () => {
898
+ const enumArraySchema = new mongoose.Schema({
899
+ values: {
900
+ default: ["alpha", "beta"],
901
+ enum: ["alpha", "beta"],
902
+ type: [String],
903
+ },
904
+ });
905
+ const EnumArrayModel =
906
+ mongoose.models.OpenApiValidatorEnumArray ??
907
+ mongoose.model("OpenApiValidatorEnumArray", enumArraySchema);
908
+
909
+ const schema = getSchemaFromModel(EnumArrayModel);
910
+ expect(schema.values).toEqual({
911
+ items: {enum: ["alpha", "beta"], type: "string"},
912
+ type: "array",
913
+ });
914
+ });
915
+ });
916
+
917
+ describe("enum array request bodies", () => {
918
+ const enumArraySchema = new mongoose.Schema({
919
+ label: {required: true, type: String},
920
+ values: {
921
+ enum: ["alpha", "beta"],
922
+ type: [String],
923
+ },
924
+ });
925
+ const EnumArrayModel =
926
+ mongoose.models.OpenApiValidatorEnumArrayRoute ??
927
+ mongoose.model("OpenApiValidatorEnumArrayRoute", enumArraySchema);
928
+
929
+ const enumArrayRouterOptions = {
930
+ permissions: {
931
+ create: [Permissions.IsAuthenticated],
932
+ delete: [Permissions.IsAdmin],
933
+ list: [Permissions.IsAuthenticated],
934
+ read: [Permissions.IsAuthenticated],
935
+ update: [Permissions.IsAuthenticated],
936
+ },
937
+ queryFields: ["label"],
938
+ sort: "-label" as const,
939
+ };
940
+
941
+ it("accepts enum array values on create when validation is enabled", async () => {
942
+ configureOpenApiValidator();
943
+
944
+ const freshApp = await setupFreshApp();
945
+ freshApp.use("/enum-arrays", modelRouter(EnumArrayModel, enumArrayRouterOptions));
946
+ const admin = await authAsUser(freshApp, "admin");
947
+
948
+ const res = await admin
949
+ .post("/enum-arrays")
950
+ .send({label: "sample", values: ["alpha", "beta"]})
951
+ .expect(201);
952
+
953
+ expect(res.body.data.values).toEqual(["alpha", "beta"]);
954
+ });
736
955
  });
737
956
 
738
957
  describe("getOpenApiValidatorConfig", () => {
@@ -6,7 +6,8 @@
6
6
  *
7
7
  * Validation is always installed as middleware but only activates after
8
8
  * `configureOpenApiValidator()` is called. This makes it safe to include
9
- * in modelRouter by default.
9
+ * in modelRouter by default. Create bodies enforce Mongoose required fields;
10
+ * PATCH/update bodies are partial (present fields only).
10
11
  *
11
12
  * @module openApiValidator
12
13
  *
@@ -38,12 +39,11 @@ import Ajv, {type ErrorObject, type ValidateFunction} from "ajv";
38
39
  import addFormats from "ajv-formats";
39
40
  import type {NextFunction, Request, Response} from "express";
40
41
  import type {Model} from "mongoose";
41
- import m2s from "mongoose-to-swagger";
42
-
42
+ import {ADMIN_LIST_CHOICE_EMPTY_VALUE} from "./adminTypes";
43
43
  import {APIError} from "./errors";
44
44
  import {logger} from "./logger";
45
45
  import type {OpenApiSchema, OpenApiSchemaProperty} from "./openApiBuilder";
46
- import {fixMixedFields} from "./populate";
46
+ import {getOpenApiSpecForModel} from "./populate";
47
47
 
48
48
  /**
49
49
  * Global configuration for OpenAPI validation.
@@ -185,6 +185,11 @@ const getAjvInstance = (): Ajv => {
185
185
  validateSchema: false,
186
186
  });
187
187
  addFormats(instance as unknown as Parameters<typeof addFormats>[0]);
188
+ instance.addKeyword({
189
+ keyword: ESCAPED_REGEX_LITERAL_KEYWORD,
190
+ type: "string",
191
+ validate: (_enabled: boolean, data: string) => isEscapedRegexLiteral(data),
192
+ });
188
193
  ajvCache.set(key, instance);
189
194
  }
190
195
 
@@ -211,6 +216,44 @@ const VALID_JSON_SCHEMA_TYPES = new Set([
211
216
  "null",
212
217
  ]);
213
218
 
219
+ const REGEX_META_CHARACTERS = new Set([
220
+ "\\",
221
+ ".",
222
+ "*",
223
+ "+",
224
+ "?",
225
+ "^",
226
+ "$",
227
+ "{",
228
+ "}",
229
+ "(",
230
+ ")",
231
+ "|",
232
+ "[",
233
+ "]",
234
+ ]);
235
+
236
+ /** Accepts literal text and escaped metacharacters (e.g. `\\.`), rejects executable patterns. */
237
+ export const isEscapedRegexLiteral = (value: string): boolean => {
238
+ for (let index = 0; index < value.length; index += 1) {
239
+ const character = value[index];
240
+ if (character === "\\") {
241
+ const escapedCharacter = value[index + 1];
242
+ if (!escapedCharacter || !REGEX_META_CHARACTERS.has(escapedCharacter)) {
243
+ return false;
244
+ }
245
+ index += 1;
246
+ continue;
247
+ }
248
+ if (REGEX_META_CHARACTERS.has(character)) {
249
+ return false;
250
+ }
251
+ }
252
+ return true;
253
+ };
254
+
255
+ const ESCAPED_REGEX_LITERAL_KEYWORD = "escapedRegexLiteral";
256
+
214
257
  // mongoose-to-swagger emits non-standard type strings for some Mongoose types
215
258
  const MONGOOSE_TYPE_MAP: Record<string, {type: string; format?: string}> = {
216
259
  dateonly: {format: "date", type: "string"},
@@ -261,9 +304,61 @@ const sanitizeSchemaForAjv = (schema: Record<string, unknown>): Record<string, u
261
304
  );
262
305
  }
263
306
 
307
+ if (Array.isArray(result.oneOf)) {
308
+ result.oneOf = result.oneOf.map((entry) =>
309
+ typeof entry === "object" && entry !== null
310
+ ? sanitizeSchemaForAjv(entry as Record<string, unknown>)
311
+ : entry
312
+ );
313
+ }
314
+
315
+ if (typeof result.required === "boolean") {
316
+ delete result.required;
317
+ }
318
+
264
319
  return result;
265
320
  };
266
321
 
322
+ const stripBooleanRequiredFlag = (schema: OpenApiSchemaProperty): OpenApiSchemaProperty => {
323
+ if (schema.required === true || schema.required === false) {
324
+ const {required: _, ...rest} = schema;
325
+ const cleaned = {...rest} as OpenApiSchemaProperty;
326
+ if (cleaned.properties) {
327
+ cleaned.properties = Object.fromEntries(
328
+ Object.entries(cleaned.properties).map(([key, value]) => [
329
+ key,
330
+ stripBooleanRequiredFlag(value),
331
+ ])
332
+ );
333
+ }
334
+ if (cleaned.items) {
335
+ cleaned.items = stripBooleanRequiredFlag(cleaned.items);
336
+ }
337
+ if (cleaned.oneOf) {
338
+ cleaned.oneOf = cleaned.oneOf.map((entry) => stripBooleanRequiredFlag(entry));
339
+ }
340
+ return cleaned;
341
+ }
342
+ if (schema.properties) {
343
+ return {
344
+ ...schema,
345
+ properties: Object.fromEntries(
346
+ Object.entries(schema.properties).map(([key, value]) => [
347
+ key,
348
+ stripBooleanRequiredFlag(value),
349
+ ])
350
+ ),
351
+ };
352
+ }
353
+ if (schema.items) {
354
+ return {...schema, items: stripBooleanRequiredFlag(schema.items)};
355
+ }
356
+ if (schema.oneOf) {
357
+ return {...schema, oneOf: schema.oneOf.map((entry) => stripBooleanRequiredFlag(entry))};
358
+ }
359
+ return schema;
360
+ };
361
+
267
362
  /**
268
363
  * Get or create a compiled validator for a schema.
269
364
  * Uses the current config so changes take effect on next call.
@@ -315,20 +410,25 @@ const formatValidationErrors = (errors: ErrorObject[]): string => {
315
410
  */
316
411
  const propertiesToSchema = (
317
412
  properties: Record<string, OpenApiSchemaProperty>,
318
- requiredFields?: string[]
413
+ requiredFields?: string[],
414
+ options?: {partial?: boolean}
319
415
  ): OpenApiSchema => {
320
- // Extract required fields from properties that have required: true
321
- const autoRequired = Object.entries(properties)
322
- .filter(([_, prop]) => prop.required)
323
- .map(([key]) => key);
324
-
325
- const allRequired = [...new Set([...(requiredFields ?? []), ...autoRequired])];
326
-
327
- // Strip `required` from individual properties — AJV only accepts `required` at schema level
416
+ // Extract required fields from properties marked required: true (OpenAPI builder style).
417
+ // PATCH bodies are partial: omit mongoose/OpenAPI required so one field can be sent.
418
+ const autoRequired = options?.partial
419
+ ? []
420
+ : Object.entries(properties)
421
+ .filter(([_, prop]) => prop.required === true)
422
+ .map(([key]) => key);
423
+
424
+ const allRequired = options?.partial
425
+ ? []
426
+ : [...new Set([...(requiredFields ?? []), ...autoRequired])];
427
+
428
+ // Strip boolean `required` from individual properties — AJV only accepts `required` arrays on objects
328
429
  const cleanedProperties: Record<string, OpenApiSchemaProperty> = {};
329
430
  for (const [key, prop] of Object.entries(properties)) {
330
- const {required: _, ...rest} = prop;
331
- cleanedProperties[key] = rest as OpenApiSchemaProperty;
431
+ cleanedProperties[key] = stripBooleanRequiredFlag(prop);
332
432
  }
333
433
 
334
434
  const schema: OpenApiSchema = {
@@ -360,6 +460,12 @@ export interface RequestBodyValidatorOptions {
360
460
  */
361
461
  required?: string[];
362
462
 
463
+ /**
464
+ * When true, skip schema-level `required` (PATCH / partial update bodies).
465
+ * Present fields are still type-checked.
466
+ */
467
+ partial?: boolean;
468
+
363
469
  /**
364
470
  * Fields to exclude from validation (e.g. fields set by preCreate hooks).
365
471
  * Excluded fields are removed from both the schema properties and the required array.
@@ -392,7 +498,9 @@ export const validateRequestBody = (
392
498
  schema: Record<string, OpenApiSchemaProperty>,
393
499
  options?: RequestBodyValidatorOptions
394
500
  ): ((req: Request, res: Response, next: NextFunction) => void) => {
395
- const fullSchema = propertiesToSchema(schema, options?.required);
501
+ const fullSchema = propertiesToSchema(schema, options?.required, {
502
+ partial: options?.partial,
503
+ });
396
504
 
397
505
  return (req: Request, _res: Response, next: NextFunction): void => {
398
506
  // No-op if not configured
@@ -700,10 +808,6 @@ export const validateResponseData = (
700
808
  return {valid: true};
701
809
  };
702
810
 
703
- const m2sOptions = {
704
- props: ["readOnly", "required", "enum", "default"],
705
- };
706
-
707
811
  /**
708
812
  * Extract an OpenAPI-compatible schema from a Mongoose model.
709
813
  * This allows you to use the same schema definitions for both documentation
@@ -713,17 +817,16 @@ const m2sOptions = {
713
817
  * @returns Schema properties suitable for validation
714
818
  */
715
819
  export const getSchemaFromModel = <T>(model: Model<T>): Record<string, OpenApiSchemaProperty> => {
716
- const modelSwagger = m2s(model, m2sOptions);
717
- fixMixedFields(model.schema, modelSwagger.properties);
718
- return modelSwagger.properties as Record<string, OpenApiSchemaProperty>;
820
+ const {properties} = getOpenApiSpecForModel(model);
821
+ return properties as Record<string, OpenApiSchemaProperty>;
719
822
  };
720
823
 
721
824
  /**
722
825
  * Extract required field names from a Mongoose model's swagger schema.
723
826
  */
724
827
  const getRequiredFieldsFromModel = <T>(model: Model<T>): string[] => {
725
- const modelSwagger = m2s(model, m2sOptions);
726
- return (modelSwagger.required as string[]) ?? [];
828
+ const {required} = getOpenApiSpecForModel(model);
829
+ return required;
727
830
  };
728
831
 
729
832
  /**
@@ -739,7 +842,7 @@ export const validateModelRequestBody = <T>(
739
842
  options?: RequestBodyValidatorOptions
740
843
  ): ((req: Request, res: Response, next: NextFunction) => void) => {
741
844
  let schema = getSchemaFromModel(model);
742
- let requiredFields = getRequiredFieldsFromModel(model);
845
+ let requiredFields = options?.partial ? [] : getRequiredFieldsFromModel(model);
743
846
 
744
847
  if (options?.excludeFields?.length) {
745
848
  const excluded = new Set(options.excludeFields);
@@ -749,7 +852,7 @@ export const validateModelRequestBody = <T>(
749
852
 
750
853
  return validateRequestBody(schema, {
751
854
  ...options,
752
- required: [...(options?.required ?? []), ...requiredFields],
855
+ required: options?.partial ? [] : [...(options?.required ?? []), ...requiredFields],
753
856
  });
754
857
  };
755
858
 
@@ -824,10 +927,86 @@ export const createModelValidators = <T>(
824
927
  enabled: options?.validateUpdate,
825
928
  onAdditionalPropertiesRemoved: options?.onAdditionalPropertiesRemoved,
826
929
  onError: options?.onError,
930
+ partial: true,
827
931
  }),
828
932
  };
829
933
  };
830
934
 
935
+ const choiceEmptyInItemSchema = (baseItem: OpenApiSchemaProperty): OpenApiSchemaProperty => {
936
+ if (baseItem.enum) {
937
+ return {
938
+ oneOf: [
939
+ {enum: baseItem.enum, type: "string"},
940
+ {enum: [ADMIN_LIST_CHOICE_EMPTY_VALUE], type: "string"},
941
+ ],
942
+ };
943
+ }
944
+ return {
945
+ oneOf: [
946
+ stripBooleanRequiredFlag(baseItem),
947
+ {enum: [ADMIN_LIST_CHOICE_EMPTY_VALUE], type: "string"},
948
+ ],
949
+ };
950
+ };
951
+
952
+ const buildInOperatorSchema = (itemSchema: OpenApiSchemaProperty): OpenApiSchemaProperty => ({
953
+ additionalProperties: false,
954
+ properties: {
955
+ $in: {
956
+ items: itemSchema,
957
+ minItems: 1,
958
+ type: "array",
959
+ },
960
+ },
961
+ required: ["$in"],
962
+ type: "object",
963
+ });
964
+
965
+ const buildRegexOperatorSchema = (): OpenApiSchemaProperty => ({
966
+ additionalProperties: false,
967
+ properties: {
968
+ $options: {enum: ["i"], type: "string"},
969
+ $regex: {escapedRegexLiteral: true, type: "string"},
970
+ },
971
+ required: ["$regex", "$options"],
972
+ type: "object",
973
+ });
974
+
975
+ const buildRangeOperatorSchema = (valueSchema: OpenApiSchemaProperty): OpenApiSchemaProperty => ({
976
+ additionalProperties: false,
977
+ properties: {
978
+ $gt: valueSchema,
979
+ $gte: valueSchema,
980
+ $lt: valueSchema,
981
+ $lte: valueSchema,
982
+ },
983
+ type: "object",
984
+ });
985
+
986
+ /** Query schema for string/enum fields: scalar, `$in`, or escaped `$regex`. */
987
+ export const buildStringListQueryFieldSchema = (
988
+ fieldSchema: OpenApiSchemaProperty
989
+ ): OpenApiSchemaProperty => {
990
+ const scalar = stripBooleanRequiredFlag(fieldSchema);
991
+ const inItems = fieldSchema.enum
992
+ ? choiceEmptyInItemSchema(fieldSchema)
993
+ : stripBooleanRequiredFlag(fieldSchema);
994
+ return {
995
+ oneOf: [scalar, buildInOperatorSchema(inItems), buildRegexOperatorSchema()],
996
+ };
997
+ };
998
+
999
+ /** Query schema for number/date fields: scalar or comparison operators. */
1000
+ export const buildNumericListQueryFieldSchema = (
1001
+ fieldSchema: OpenApiSchemaProperty
1002
+ ): OpenApiSchemaProperty => {
1003
+ const scalar = stripBooleanRequiredFlag(fieldSchema);
1004
+ const valueSchema = stripBooleanRequiredFlag(fieldSchema);
1005
+ return {
1006
+ oneOf: [scalar, buildRangeOperatorSchema(valueSchema)],
1007
+ };
1008
+ };
1009
+
831
1010
  /**
832
1011
  * Build a query parameter schema from a model's Mongoose schema and queryFields array.
833
1012
  * Always includes pagination parameters (limit, page, sort).
@@ -849,13 +1028,19 @@ export const buildQuerySchemaFromFields = <T>(
849
1028
 
850
1029
  for (const field of queryFields) {
851
1030
  const modelField = modelSchema[field];
852
- if (modelField) {
853
- // Use the model's type info, but mark as not required for queries
854
- querySchema[field] = {...modelField, required: false};
855
- } else {
856
- // Field not in model schema — allow as string
857
- querySchema[field] = {type: "string"};
1031
+ if (!modelField) {
1032
+ querySchema[field] = buildStringListQueryFieldSchema({type: "string"});
1033
+ continue;
1034
+ }
1035
+ if (modelField.type === "boolean") {
1036
+ querySchema[field] = stripBooleanRequiredFlag(modelField);
1037
+ continue;
1038
+ }
1039
+ if (modelField.type === "number" || modelField.format === "date-time") {
1040
+ querySchema[field] = buildNumericListQueryFieldSchema(modelField);
1041
+ continue;
858
1042
  }
1043
+ querySchema[field] = buildStringListQueryFieldSchema(modelField);
859
1044
  }
860
1045
 
861
1046
  return querySchema;