@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
@@ -0,0 +1,358 @@
1
+ /**
2
+ * Apply, roll back, and inspect MongoDB migration history. This module also
3
+ * owns the production wet-apply gate, the TerrenoApp `runOnStart` hook, and the
4
+ * CI helper that applies then reverses reversible files.
5
+ */
6
+ import {DateTime} from "luxon";
7
+ import mongoose from "mongoose";
8
+
9
+ import {APIError} from "../errors";
10
+ import {logger as defaultLogger} from "../logger";
11
+ import {checkMigrationFiles} from "./load";
12
+ import {withMigrationLock} from "./lock";
13
+ import {
14
+ type AppliedMigrationRecord,
15
+ type LoadedMigration,
16
+ MIGRATION_LOCK_ID,
17
+ MIGRATIONS_COLLECTION,
18
+ type MigrationContext,
19
+ type MigrationStatus,
20
+ type MigrationStoreDoc,
21
+ type RunDownMigrationsOptions,
22
+ type RunDownMigrationsResult,
23
+ type RunMigrationsOptions,
24
+ type RunMigrationsResult,
25
+ } from "./types";
26
+
27
+ const historyCollection = (
28
+ connection: mongoose.Connection
29
+ ): mongoose.Collection<MigrationStoreDoc> => {
30
+ return connection.collection<MigrationStoreDoc>(MIGRATIONS_COLLECTION);
31
+ };
32
+
33
+ const toJsDate = (value: Date | string | undefined): Date => {
34
+ if (value instanceof Date) {
35
+ const parsed = DateTime.fromJSDate(value, {zone: "utc"});
36
+ if (!parsed.isValid) {
37
+ throw new APIError({status: 500, title: "Invalid migration timestamp"});
38
+ }
39
+ return parsed.toJSDate();
40
+ }
41
+ const parsed = DateTime.fromISO(String(value ?? ""), {zone: "utc"});
42
+ if (!parsed.isValid) {
43
+ throw new APIError({status: 500, title: "Invalid migration timestamp"});
44
+ }
45
+ return parsed.toJSDate();
46
+ };
47
+
48
+ const loadApplied = async (
49
+ connection: mongoose.Connection
50
+ ): Promise<Map<string, AppliedMigrationRecord>> => {
51
+ const docs = await historyCollection(connection)
52
+ .find({_id: {$ne: MIGRATION_LOCK_ID}})
53
+ .toArray();
54
+ const applied = new Map<string, AppliedMigrationRecord>();
55
+ for (const doc of docs) {
56
+ const id = String(doc.id ?? doc._id);
57
+ applied.set(id, {
58
+ appliedAt: toJsDate(doc.appliedAt),
59
+ checksum: String(doc.checksum ?? ""),
60
+ id,
61
+ });
62
+ }
63
+ return applied;
64
+ };
65
+
66
+ const recordApplied = async ({
67
+ connection,
68
+ migration,
69
+ }: {
70
+ connection: mongoose.Connection;
71
+ migration: LoadedMigration;
72
+ }): Promise<void> => {
73
+ await historyCollection(connection).insertOne({
74
+ _id: migration.id,
75
+ appliedAt: DateTime.utc().toJSDate(),
76
+ checksum: migration.checksum,
77
+ id: migration.id,
78
+ });
79
+ };
80
+
81
+ export const runMigrations = async ({
82
+ addLog,
83
+ checkCancellation,
84
+ connection,
85
+ dryRun,
86
+ lockPollMs,
87
+ lockTtlMs,
88
+ logger = defaultLogger,
89
+ migrations,
90
+ mongoose: mongooseNs,
91
+ }: RunMigrationsOptions): Promise<RunMigrationsResult> => {
92
+ const execute = async (): Promise<RunMigrationsResult> => {
93
+ const appliedRecords = await loadApplied(connection);
94
+ const applied: string[] = [];
95
+ const skipped: string[] = [];
96
+
97
+ for (const migration of migrations) {
98
+ const existing = appliedRecords.get(migration.id);
99
+ if (existing) {
100
+ if (existing.checksum !== migration.checksum) {
101
+ throw new APIError({
102
+ detail: `Migration ${migration.id} was applied with checksum ${existing.checksum} but the current file is ${migration.checksum}`,
103
+ status: 409,
104
+ title: "Migration checksum mismatch",
105
+ });
106
+ }
107
+ skipped.push(migration.id);
108
+ continue;
109
+ }
110
+
111
+ const ctx: MigrationContext = {
112
+ addLog,
113
+ checkCancellation,
114
+ dryRun,
115
+ logger,
116
+ mongoose: mongooseNs,
117
+ };
118
+ await checkCancellation?.();
119
+ await migration.up(ctx);
120
+ applied.push(migration.id);
121
+ if (!dryRun) {
122
+ await recordApplied({connection, migration});
123
+ }
124
+ }
125
+
126
+ return {applied, dryRun, skipped};
127
+ };
128
+
129
+ return withMigrationLock({
130
+ connection,
131
+ fn: execute,
132
+ pollMs: lockPollMs,
133
+ ttlMs: lockTtlMs,
134
+ });
135
+ };
136
+
137
+ const removeApplied = async ({
138
+ connection,
139
+ id,
140
+ }: {
141
+ connection: mongoose.Connection;
142
+ id: string;
143
+ }): Promise<void> => {
144
+ await historyCollection(connection).deleteOne({_id: id});
145
+ };
146
+
147
+ export const getMigrationStatus = async ({
148
+ connection,
149
+ migrations,
150
+ }: {
151
+ connection: mongoose.Connection;
152
+ migrations: LoadedMigration[];
153
+ }): Promise<MigrationStatus> => {
154
+ const appliedRecords = await loadApplied(connection);
155
+ const applied: AppliedMigrationRecord[] = [];
156
+ const pending: Array<{checksum: string; id: string}> = [];
157
+ for (const migration of migrations) {
158
+ const existing = appliedRecords.get(migration.id);
159
+ if (existing) {
160
+ applied.push(existing);
161
+ continue;
162
+ }
163
+ pending.push({checksum: migration.checksum, id: migration.id});
164
+ }
165
+
166
+ const collection = historyCollection(connection);
167
+ const lockDoc = await collection.findOne({_id: MIGRATION_LOCK_ID});
168
+ const lock =
169
+ lockDoc == null
170
+ ? null
171
+ : {
172
+ expiresAt: toJsDate(lockDoc.expiresAt),
173
+ holder: String(lockDoc.holder ?? ""),
174
+ };
175
+
176
+ return {applied, lock, pending};
177
+ };
178
+
179
+ export const runDownMigrations = async ({
180
+ connection,
181
+ dryRun,
182
+ lockPollMs,
183
+ lockTtlMs,
184
+ logger = defaultLogger,
185
+ migrations,
186
+ mongoose: mongooseNs,
187
+ steps,
188
+ }: RunDownMigrationsOptions): Promise<RunDownMigrationsResult> => {
189
+ if (!Number.isInteger(steps) || steps < 1) {
190
+ throw new APIError({
191
+ detail: "down --steps must be a positive integer",
192
+ status: 400,
193
+ title: "Invalid down steps",
194
+ });
195
+ }
196
+
197
+ const execute = async (): Promise<RunDownMigrationsResult> => {
198
+ const appliedRecords = await loadApplied(connection);
199
+ const appliedInOrder = migrations.filter((migration) => appliedRecords.has(migration.id));
200
+ const targets = appliedInOrder.slice(-steps).reverse();
201
+ const reversed: string[] = [];
202
+
203
+ const reversible = targets.map((migration) => {
204
+ if (typeof migration.down !== "function") {
205
+ throw new APIError({
206
+ detail: `Migration ${migration.id} has no down. Rollback stopped.`,
207
+ status: 400,
208
+ title: "Migration has no down",
209
+ });
210
+ }
211
+ return {down: migration.down, id: migration.id};
212
+ });
213
+
214
+ for (const migration of reversible) {
215
+ const ctx: MigrationContext = {
216
+ dryRun,
217
+ logger,
218
+ mongoose: mongooseNs,
219
+ };
220
+ await ctx.checkCancellation?.();
221
+ await migration.down(ctx);
222
+ reversed.push(migration.id);
223
+ if (!dryRun) {
224
+ await removeApplied({connection, id: migration.id});
225
+ }
226
+ }
227
+
228
+ return {dryRun, reversed};
229
+ };
230
+
231
+ return withMigrationLock({
232
+ connection,
233
+ fn: execute,
234
+ pollMs: lockPollMs,
235
+ ttlMs: lockTtlMs,
236
+ });
237
+ };
238
+
239
+ export interface AssertMigrationsAllowedOptions {
240
+ allowEnv: boolean;
241
+ dryRun: boolean;
242
+ force: boolean;
243
+ isProduction: boolean;
244
+ }
245
+
246
+ /** Fail closed for production wet apply unless ALLOW_MIGRATIONS and force (CLI `--force` or boot/admin Apply). */
247
+ export const assertMigrationsAllowed = ({
248
+ allowEnv,
249
+ dryRun,
250
+ force,
251
+ isProduction,
252
+ }: AssertMigrationsAllowedOptions): void => {
253
+ if (dryRun) {
254
+ return;
255
+ }
256
+ if (!isProduction) {
257
+ return;
258
+ }
259
+ if (allowEnv && force) {
260
+ return;
261
+ }
262
+
263
+ const detail = allowEnv
264
+ ? "Production wet migrations also require --force (or an equivalent boot/admin Apply)."
265
+ : "Set ALLOW_MIGRATIONS=true for production wet migrations.";
266
+ throw new APIError({
267
+ detail,
268
+ status: 403,
269
+ title: "Migrations not allowed",
270
+ });
271
+ };
272
+
273
+ export interface StartupMigrationsOption {
274
+ dir: string;
275
+ runOnStart?: boolean;
276
+ }
277
+
278
+ export const runStartupMigrations = async ({
279
+ env = process.env,
280
+ migrations,
281
+ mongoose: mongooseNs,
282
+ }: {
283
+ env?: NodeJS.ProcessEnv;
284
+ migrations?: StartupMigrationsOption;
285
+ mongoose: typeof mongoose;
286
+ }): Promise<{applied: string[]; ran: boolean}> => {
287
+ if (!migrations?.runOnStart) {
288
+ return {applied: [], ran: false};
289
+ }
290
+
291
+ assertMigrationsAllowed({
292
+ allowEnv: env.ALLOW_MIGRATIONS === "true",
293
+ dryRun: false,
294
+ force: true,
295
+ isProduction: env.NODE_ENV === "production",
296
+ });
297
+
298
+ const loaded = await checkMigrationFiles({dir: migrations.dir});
299
+ const result = await runMigrations({
300
+ connection: mongooseNs.connection,
301
+ dryRun: false,
302
+ migrations: loaded,
303
+ mongoose: mongooseNs,
304
+ });
305
+ return {applied: result.applied, ran: true};
306
+ };
307
+
308
+ export interface ExerciseReversibleMigrationsOptions {
309
+ dir: string;
310
+ connect: () => Promise<mongoose.Connection>;
311
+ }
312
+
313
+ export interface ExerciseReversibleMigrationsResult {
314
+ applied: string[];
315
+ reversed: string[];
316
+ skippedIrreversible: string | null;
317
+ }
318
+
319
+ /**
320
+ * CI helper: apply every file, then roll back in reverse until a file without
321
+ * `down` stops the chain. The irreversible id is recorded; earlier files stay applied.
322
+ */
323
+ export const exerciseReversibleMigrations = async ({
324
+ connect,
325
+ dir,
326
+ }: ExerciseReversibleMigrationsOptions): Promise<ExerciseReversibleMigrationsResult> => {
327
+ const connection = await connect();
328
+ const migrations = await checkMigrationFiles({dir});
329
+ const upResult = await runMigrations({
330
+ connection,
331
+ dryRun: false,
332
+ migrations,
333
+ mongoose,
334
+ });
335
+
336
+ const reversed: string[] = [];
337
+ let skippedIrreversible: string | null = null;
338
+ for (const migration of [...migrations].reverse()) {
339
+ if (typeof migration.down !== "function") {
340
+ skippedIrreversible = migration.id;
341
+ break;
342
+ }
343
+ const downResult = await runDownMigrations({
344
+ connection,
345
+ dryRun: false,
346
+ migrations,
347
+ mongoose,
348
+ steps: 1,
349
+ });
350
+ reversed.push(...downResult.reversed);
351
+ }
352
+
353
+ return {
354
+ applied: [...upResult.applied, ...upResult.skipped],
355
+ reversed,
356
+ skippedIrreversible,
357
+ };
358
+ };
@@ -0,0 +1,159 @@
1
+ /**
2
+ * Tests for cataloging Mongoose schemas and classifying generate-time diffs.
3
+ */
4
+ import {describe, expect, it} from "bun:test";
5
+ import mongoose from "mongoose";
6
+
7
+ import {buildSchemaCatalog, diffSchemaCatalog} from "./schemaCatalog";
8
+
9
+ const catalogTodo = (): mongoose.Model<mongoose.Document> => {
10
+ const schema = new mongoose.Schema(
11
+ {
12
+ notes: {description: "Notes", type: String},
13
+ title: {description: "Title", required: true, type: String},
14
+ },
15
+ {collection: "todos"}
16
+ );
17
+ schema.index({title: 1});
18
+ return mongoose.model(`TodoCatalog${Math.random().toString(16).slice(2)}`, schema);
19
+ };
20
+
21
+ describe("buildSchemaCatalog", () => {
22
+ it("records paths, required flags, and indexes without methods", () => {
23
+ const Model = catalogTodo();
24
+ const catalog = buildSchemaCatalog({models: [Model]});
25
+ const model = catalog.models[Model.modelName];
26
+ expect(model.collection).toBe("todos");
27
+ expect(model.fields.map((field) => field.path).sort()).toEqual(["notes", "title"]);
28
+ expect(model.fields.find((field) => field.path === "title")?.required).toBe(true);
29
+ expect(model.fields.find((field) => field.path === "notes")?.required).toBe(false);
30
+ expect(model.indexes.some((index) => index.keys.title === 1)).toBe(true);
31
+ const again = buildSchemaCatalog({models: [Model]});
32
+ expect(JSON.stringify(again)).toBe(JSON.stringify(catalog));
33
+ });
34
+ });
35
+
36
+ describe("diffSchemaCatalog", () => {
37
+ it("classifies optional field and index adds as safe", () => {
38
+ const before = {
39
+ models: {
40
+ Todo: {
41
+ collection: "todos",
42
+ fields: [{instance: "String", path: "title", required: true, unique: false}],
43
+ indexes: [],
44
+ modelName: "Todo",
45
+ },
46
+ },
47
+ };
48
+ const after = {
49
+ models: {
50
+ Todo: {
51
+ collection: "todos",
52
+ fields: [
53
+ {instance: "String", path: "notes", required: false, unique: false},
54
+ {instance: "String", path: "title", required: true, unique: false},
55
+ ],
56
+ indexes: [{keys: {title: 1}, unique: false}],
57
+ modelName: "Todo",
58
+ },
59
+ },
60
+ };
61
+ const diff = diffSchemaCatalog({after, before});
62
+ expect(diff.ops.map((op) => op.kind).sort()).toEqual(["addIndex", "addOptionalField"]);
63
+ expect(diff.ops.every((op) => op.safe)).toBe(true);
64
+ });
65
+
66
+ it("classifies required, unique, and rename as unsafe", () => {
67
+ const before = {
68
+ models: {
69
+ Todo: {
70
+ collection: "todos",
71
+ fields: [{instance: "String", path: "title", required: false, unique: false}],
72
+ indexes: [],
73
+ modelName: "Todo",
74
+ },
75
+ },
76
+ };
77
+ const after = {
78
+ models: {
79
+ Todo: {
80
+ collection: "todos",
81
+ fields: [
82
+ {instance: "String", path: "heading", required: true, unique: false},
83
+ {instance: "String", path: "owner", required: false, unique: true},
84
+ ],
85
+ indexes: [{keys: {owner: 1}, unique: true}],
86
+ modelName: "Todo",
87
+ },
88
+ },
89
+ };
90
+ const diff = diffSchemaCatalog({after, before});
91
+ const kinds = diff.ops.map((op) => op.kind).sort();
92
+ expect(kinds).toContain("renameField");
93
+ expect(kinds).toContain("addRequiredField");
94
+ expect(kinds).toContain("addUniqueIndex");
95
+ expect(diff.ops.filter((op) => !op.safe).length).toBeGreaterThan(0);
96
+ expect(diff.ops.find((op) => op.kind === "renameField")?.safe).toBe(false);
97
+ expect(diff.ops.find((op) => op.kind === "addRequiredField")?.safe).toBe(false);
98
+ expect(diff.ops.find((op) => op.kind === "addUniqueIndex")?.safe).toBe(false);
99
+ });
100
+
101
+ it("classifies tightening required on an existing path as unsafe", () => {
102
+ const before = {
103
+ models: {
104
+ Todo: {
105
+ collection: "todos",
106
+ fields: [{instance: "String", path: "title", required: false, unique: false}],
107
+ indexes: [{keys: {title: 1}, unique: false}],
108
+ modelName: "Todo",
109
+ },
110
+ },
111
+ };
112
+ const after = {
113
+ models: {
114
+ Todo: {
115
+ collection: "todos",
116
+ fields: [{instance: "String", path: "title", required: true, unique: false}],
117
+ indexes: [],
118
+ modelName: "Todo",
119
+ },
120
+ },
121
+ };
122
+ const diff = diffSchemaCatalog({after, before});
123
+ expect(diff.ops.some((op) => op.kind === "addRequiredField" && op.safe === false)).toBe(true);
124
+ expect(diff.ops.some((op) => op.kind === "dropIndex" && op.safe === true)).toBe(true);
125
+ });
126
+
127
+ it("classifies removed paths and same-path type changes as unsafe", () => {
128
+ const before = {
129
+ models: {
130
+ Todo: {
131
+ collection: "todos",
132
+ fields: [
133
+ {instance: "String", path: "notes", required: false, unique: false},
134
+ {instance: "String", path: "title", required: true, unique: false},
135
+ ],
136
+ indexes: [],
137
+ modelName: "Todo",
138
+ },
139
+ },
140
+ };
141
+ const after = {
142
+ models: {
143
+ Todo: {
144
+ collection: "todos",
145
+ fields: [{instance: "Number", path: "title", required: true, unique: false}],
146
+ indexes: [],
147
+ modelName: "Todo",
148
+ },
149
+ },
150
+ };
151
+ const diff = diffSchemaCatalog({after, before});
152
+ expect(diff.ops).toEqual(
153
+ expect.arrayContaining([
154
+ {kind: "removeField", modelName: "Todo", path: "notes", safe: false},
155
+ {kind: "changeFieldType", modelName: "Todo", path: "title", safe: false},
156
+ ])
157
+ );
158
+ });
159
+ });