@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,200 @@
1
+ import type {Application} from "express";
2
+ import {DateTime} from "luxon";
3
+ import type {Model} from "mongoose";
4
+ import {
5
+ asyncHandler,
6
+ type ModelRouterOptions,
7
+ type ModelRouterRegistration,
8
+ modelRouter,
9
+ type OpenApiMiddleware,
10
+ } from "../api";
11
+ import {authenticateMiddleware, type User} from "../auth";
12
+ import {APIError} from "../errors";
13
+ import {logger} from "../logger";
14
+ import {Notification} from "../models/notification";
15
+ import {NotificationPreference} from "../models/notificationPreference";
16
+ import {createOpenApiBuilder} from "../openApiBuilder";
17
+ import {OwnerQueryFilter, Permissions} from "../permissions";
18
+ import type {TerrenoPlugin} from "../terrenoPlugin";
19
+ import type {NotificationDocument} from "../types/notification";
20
+ import type {NotificationPreferenceDocument} from "../types/notificationPreference";
21
+ import {
22
+ assertValidNotificationArchivedAt,
23
+ assertValidNotificationReadAt,
24
+ configureNotificationService,
25
+ type NotificationServiceOptions,
26
+ type NotificationsCommsService,
27
+ } from "./notificationService";
28
+
29
+ export interface NotificationsAppOptions extends NotificationServiceOptions {
30
+ getComms?: () => NotificationsCommsService;
31
+ retainDays?: number;
32
+ userModel?: Model<{email?: string; phone?: string}>;
33
+ }
34
+
35
+ const PREFERENCE_CHANNELS = ["inapp", "mail", "push", "sms"] as const;
36
+
37
+ const parseNotificationDate = (value: unknown, fieldName: "archivedAt" | "readAt"): Date | null => {
38
+ if (value === null || value === undefined) {
39
+ return null;
40
+ }
41
+ if (value instanceof Date) {
42
+ return value;
43
+ }
44
+ if (typeof value === "string") {
45
+ const parsed = DateTime.fromISO(value);
46
+ if (!parsed.isValid) {
47
+ throw new APIError({status: 400, title: `${fieldName} must be a date or null`});
48
+ }
49
+ return parsed.toJSDate();
50
+ }
51
+ throw new APIError({status: 400, title: `${fieldName} must be a date or null`});
52
+ };
53
+
54
+ const sanitizeNotificationUpdate = (body: unknown): NotificationDocument => {
55
+ const payload = body as Partial<Pick<NotificationDocument, "archivedAt" | "readAt">> & {
56
+ archivedAt?: unknown;
57
+ readAt?: unknown;
58
+ };
59
+ const update: Partial<NotificationDocument> = {};
60
+ if (payload.readAt !== undefined) {
61
+ assertValidNotificationReadAt(payload.readAt);
62
+ update.readAt = parseNotificationDate(payload.readAt, "readAt");
63
+ }
64
+ if (payload.archivedAt !== undefined) {
65
+ assertValidNotificationArchivedAt(payload.archivedAt);
66
+ update.archivedAt = parseNotificationDate(payload.archivedAt, "archivedAt");
67
+ }
68
+ return update as NotificationDocument;
69
+ };
70
+
71
+ const sanitizePreferenceUpdate = (body: unknown): NotificationPreferenceDocument => {
72
+ const payload = body as Partial<NotificationPreferenceDocument>;
73
+ const update: Partial<NotificationPreferenceDocument> = {};
74
+ for (const channel of PREFERENCE_CHANNELS) {
75
+ if (channel in payload) {
76
+ update[channel] = payload[channel];
77
+ }
78
+ }
79
+ return update as NotificationPreferenceDocument;
80
+ };
81
+
82
+ export class NotificationsApp implements TerrenoPlugin {
83
+ private readonly options: NotificationsAppOptions;
84
+ private routers?: ModelRouterRegistration[];
85
+
86
+ constructor(options: NotificationsAppOptions = {}) {
87
+ this.options = options;
88
+ }
89
+
90
+ register(app: Application, openApi?: unknown): void {
91
+ configureNotificationService({
92
+ getComms: this.options.getComms,
93
+ retainDays: this.options.retainDays,
94
+ userModel: this.options.userModel,
95
+ });
96
+
97
+ if (this.routers) {
98
+ for (const router of this.routers) {
99
+ app.use(router.path, router.router);
100
+ }
101
+ return;
102
+ }
103
+
104
+ const openApiMiddleware = openApi as OpenApiMiddleware | undefined;
105
+ const sharedRouterOptions: Partial<ModelRouterOptions<NotificationDocument>> = openApiMiddleware
106
+ ? {openApi: openApiMiddleware}
107
+ : {};
108
+
109
+ const notificationsRouter = modelRouter<NotificationDocument>("/notifications", Notification, {
110
+ ...sharedRouterOptions,
111
+ endpoints: (router) => {
112
+ router.post(
113
+ "/mark-all-read",
114
+ [
115
+ authenticateMiddleware(),
116
+ createOpenApiBuilder(sharedRouterOptions as Partial<ModelRouterOptions<unknown>>)
117
+ .withTags(["notifications"])
118
+ .withSummary("Mark all of the caller's unread notifications as read")
119
+ .withResponse(200, {
120
+ data: {
121
+ properties: {modified: {type: "number"}},
122
+ type: "object",
123
+ },
124
+ })
125
+ .build(),
126
+ ],
127
+ asyncHandler(async (req, res) => {
128
+ const user = req.user as User | undefined;
129
+ if (!user?.id) {
130
+ throw new APIError({status: 401, title: "Authentication required"});
131
+ }
132
+
133
+ const unread = await Notification.find({
134
+ $or: [{readAt: null}, {readAt: {$exists: false}}],
135
+ ownerId: user.id,
136
+ });
137
+ const now = DateTime.now().toJSDate();
138
+ let modified = 0;
139
+ for (const row of unread) {
140
+ row.readAt = now;
141
+ await row.save();
142
+ modified += 1;
143
+ }
144
+
145
+ logger.info("[notifications] mark-all-read", {modified, userId: user.id});
146
+ return res.json({data: {modified}});
147
+ })
148
+ );
149
+ },
150
+ permissions: {
151
+ create: [],
152
+ delete: [Permissions.IsOwner],
153
+ list: [Permissions.IsAuthenticated],
154
+ read: [Permissions.IsOwner],
155
+ update: [Permissions.IsOwner],
156
+ },
157
+ preUpdate: sanitizeNotificationUpdate,
158
+ queryFields: ["_id", "ownerId", "readAt", "archivedAt", "kind"],
159
+ queryFilter: OwnerQueryFilter,
160
+ sort: "-created",
161
+ sync: {scope: {type: "owner"}},
162
+ });
163
+ app.use(notificationsRouter.path, notificationsRouter.router);
164
+
165
+ const preferencesRouter = modelRouter<NotificationPreferenceDocument>(
166
+ "/notification-preferences",
167
+ NotificationPreference,
168
+ {
169
+ ...(openApiMiddleware ? {openApi: openApiMiddleware} : {}),
170
+ permissions: {
171
+ create: [Permissions.IsAuthenticated],
172
+ delete: [Permissions.IsOwner],
173
+ list: [Permissions.IsAuthenticated],
174
+ read: [Permissions.IsOwner],
175
+ update: [Permissions.IsOwner],
176
+ },
177
+ preCreate: (body, req) => {
178
+ const user = req.user as User | undefined;
179
+ if (!user?.id) {
180
+ throw new APIError({status: 401, title: "Authentication required"});
181
+ }
182
+ const payload = body as Partial<NotificationPreferenceDocument>;
183
+ return {
184
+ ...payload,
185
+ ownerId: user.id,
186
+ } as unknown as NotificationPreferenceDocument;
187
+ },
188
+ preUpdate: sanitizePreferenceUpdate,
189
+ queryFields: ["ownerId"],
190
+ queryFilter: OwnerQueryFilter,
191
+ sort: "-created",
192
+ sync: {scope: {type: "owner"}},
193
+ }
194
+ );
195
+ app.use(preferencesRouter.path, preferencesRouter.router);
196
+ this.routers = [notificationsRouter, preferencesRouter];
197
+
198
+ logger.info("NotificationsApp registered", {retainDays: this.options.retainDays ?? 0});
199
+ }
200
+ }
@@ -0,0 +1,51 @@
1
+ import {NotificationPreference} from "../models/notificationPreference";
2
+ import type {NotificationPreferenceChannel} from "../types/notificationPreference";
3
+
4
+ export type NotificationsBeforeSendChannel = "mail" | "push" | "sms" | "verification";
5
+
6
+ export interface NotificationsBeforeSendContext {
7
+ channel: NotificationsBeforeSendChannel;
8
+ userId?: string;
9
+ }
10
+
11
+ export interface NotificationsBeforeSendResult {
12
+ cancel?: boolean;
13
+ }
14
+
15
+ const PREFERENCE_FIELD_BY_CHANNEL: Partial<
16
+ Record<NotificationsBeforeSendChannel, NotificationPreferenceChannel>
17
+ > = {
18
+ mail: "mail",
19
+ push: "push",
20
+ sms: "sms",
21
+ };
22
+
23
+ /**
24
+ * Duck-typed CommsApp `beforeSend` hook that cancels outbound delivery when the user
25
+ * disabled that channel in NotificationPreference. Missing preference rows default to
26
+ * all channels on. The `verification` channel is never cancelled here.
27
+ */
28
+ export const notificationsBeforeSend = async ({
29
+ channel,
30
+ userId,
31
+ }: NotificationsBeforeSendContext): Promise<NotificationsBeforeSendResult | undefined> => {
32
+ if (channel === "verification" || !userId) {
33
+ return undefined;
34
+ }
35
+
36
+ const preferenceField = PREFERENCE_FIELD_BY_CHANNEL[channel];
37
+ if (!preferenceField) {
38
+ return undefined;
39
+ }
40
+
41
+ const preference = await NotificationPreference.findOneOrNone({ownerId: userId});
42
+ if (!preference) {
43
+ return undefined;
44
+ }
45
+
46
+ if (preference[preferenceField] === false) {
47
+ return {cancel: true};
48
+ }
49
+
50
+ return undefined;
51
+ };
@@ -3,7 +3,12 @@ import * as Sentry from "@sentry/bun";
3
3
  import axios from "axios";
4
4
 
5
5
  import {APIError, isAPIError} from "../errors";
6
- import {sendToSlack} from "./slackNotifier";
6
+ import {
7
+ formatSlackUserMention,
8
+ lookupSlackUserIdByEmail,
9
+ normalizeSlackUserId,
10
+ sendToSlack,
11
+ } from "./slackNotifier";
7
12
 
8
13
  describe("sendToSlack", () => {
9
14
  let mockAxiosPost: Mock<typeof axios.post>;
@@ -136,4 +141,184 @@ describe("sendToSlack", () => {
136
141
  await sendToSlack("err", {shouldThrow: false});
137
142
  expect(mockAxiosPost.mock.calls.length).toBe(1);
138
143
  });
144
+
145
+ it("prepends Slack member-id mentions so incoming webhooks notify those users", async () => {
146
+ await sendToSlack("needs review", {
147
+ mentionUserIds: ["U012ABCDEF", "<@W0ENTERPR1>"],
148
+ url: "https://direct.example/hook",
149
+ });
150
+ const [, payload] = mockAxiosPost.mock.calls[0];
151
+ expect(payload).toEqual({text: "<@U012ABCDEF> <@W0ENTERPR1> needs review"});
152
+ });
153
+
154
+ it("dedupes mention ids and skips names or emails that cannot mention anyone", async () => {
155
+ await sendToSlack("ping", {
156
+ mentionUserIds: ["U012ABCDEF", "u012abcdef", "jane@example.com", "Jane Doe", ""],
157
+ url: "https://direct.example/hook",
158
+ });
159
+ const [, payload] = mockAxiosPost.mock.calls[0];
160
+ expect(payload).toEqual({text: "<@U012ABCDEF> ping"});
161
+ });
162
+
163
+ it("applies env prefix after mention tokens", async () => {
164
+ await sendToSlack("deployed", {
165
+ env: "prd",
166
+ mentionUserIds: ["U012ABCDEF"],
167
+ url: "https://direct.example/hook",
168
+ });
169
+ const [, payload] = mockAxiosPost.mock.calls[0];
170
+ expect(payload).toEqual({text: "[PRD] <@U012ABCDEF> deployed"});
171
+ });
172
+
173
+ it("sends mention tokens alone when the message text is empty", async () => {
174
+ await sendToSlack("", {
175
+ mentionUserIds: ["U012ABCDEF"],
176
+ url: "https://direct.example/hook",
177
+ });
178
+ const [, payload] = mockAxiosPost.mock.calls[0];
179
+ expect(payload).toEqual({text: "<@U012ABCDEF>"});
180
+ });
181
+ });
182
+
183
+ describe("normalizeSlackUserId / formatSlackUserMention", () => {
184
+ it("accepts bare ids and already-wrapped mention tokens", () => {
185
+ expect(normalizeSlackUserId("U012ABCDEF")).toBe("U012ABCDEF");
186
+ expect(normalizeSlackUserId("<@u012abcdef>")).toBe("U012ABCDEF");
187
+ expect(normalizeSlackUserId("W0ENTERPR1")).toBe("W0ENTERPR1");
188
+ });
189
+
190
+ it("rejects display names and emails", () => {
191
+ expect(normalizeSlackUserId("Jane Doe")).toBeUndefined();
192
+ expect(normalizeSlackUserId("jane@example.com")).toBeUndefined();
193
+ expect(normalizeSlackUserId("@jane")).toBeUndefined();
194
+ });
195
+
196
+ it("formats a valid member id as a Slack mention token", () => {
197
+ expect(formatSlackUserMention("U012ABCDEF")).toBe("<@U012ABCDEF>");
198
+ });
199
+
200
+ it("throws APIError for values that are not Slack member ids", () => {
201
+ try {
202
+ formatSlackUserMention("jane@example.com");
203
+ throw new Error("Expected formatSlackUserMention to throw");
204
+ } catch (error) {
205
+ expect(isAPIError(error)).toBe(true);
206
+ expect((error as APIError).title).toBe("Invalid Slack user id");
207
+ }
208
+ });
209
+ });
210
+
211
+ describe("lookupSlackUserIdByEmail", () => {
212
+ let mockAxiosGet: Mock<typeof axios.get>;
213
+
214
+ beforeEach(() => {
215
+ mockAxiosGet = spyOn(axios, "get").mockResolvedValue({
216
+ data: {ok: true, user: {id: "U012ABCDEF"}},
217
+ status: 200,
218
+ });
219
+ Reflect.deleteProperty(process.env, "SLACK_BOT_TOKEN");
220
+ (Sentry.captureException as Mock<typeof Sentry.captureException>).mockClear();
221
+ });
222
+
223
+ afterEach(() => {
224
+ mockAxiosGet.mockRestore();
225
+ });
226
+
227
+ it("returns the member id from users.lookupByEmail", async () => {
228
+ const id = await lookupSlackUserIdByEmail({
229
+ email: "jane@example.com",
230
+ token: "xoxb-test",
231
+ });
232
+ expect(id).toBe("U012ABCDEF");
233
+ expect(mockAxiosGet.mock.calls.length).toBe(1);
234
+ const [url, config] = mockAxiosGet.mock.calls[0];
235
+ expect(url).toBe("https://slack.com/api/users.lookupByEmail");
236
+ expect(config).toEqual({
237
+ headers: {Authorization: "Bearer xoxb-test"},
238
+ params: {email: "jane@example.com"},
239
+ });
240
+ });
241
+
242
+ it("returns undefined when no bot token is configured", async () => {
243
+ const id = await lookupSlackUserIdByEmail({email: "jane@example.com"});
244
+ expect(id).toBeUndefined();
245
+ expect(mockAxiosGet.mock.calls.length).toBe(0);
246
+ });
247
+
248
+ it("returns undefined when email is empty and shouldThrow is false", async () => {
249
+ const id = await lookupSlackUserIdByEmail({email: " ", token: "xoxb-test"});
250
+ expect(id).toBeUndefined();
251
+ expect(mockAxiosGet.mock.calls.length).toBe(0);
252
+ });
253
+
254
+ it("returns undefined when Slack reports the user was not found", async () => {
255
+ mockAxiosGet.mockResolvedValue({data: {error: "users_not_found", ok: false}, status: 200});
256
+ const id = await lookupSlackUserIdByEmail({
257
+ email: "missing@example.com",
258
+ token: "xoxb-test",
259
+ });
260
+ expect(id).toBeUndefined();
261
+ });
262
+
263
+ it("throws when shouldThrow is true and Slack returns an error", async () => {
264
+ mockAxiosGet.mockResolvedValue({data: {error: "missing_scope", ok: false}, status: 200});
265
+ try {
266
+ await lookupSlackUserIdByEmail({
267
+ email: "jane@example.com",
268
+ shouldThrow: true,
269
+ token: "xoxb-test",
270
+ });
271
+ throw new Error("Expected lookupSlackUserIdByEmail to throw");
272
+ } catch (error) {
273
+ expect(isAPIError(error)).toBe(true);
274
+ expect((error as APIError).title).toBe("Slack user lookup failed");
275
+ expect((error as APIError).detail).toBe("missing_scope");
276
+ }
277
+ });
278
+
279
+ it("throws when shouldThrow is true and email is empty", async () => {
280
+ try {
281
+ await lookupSlackUserIdByEmail({email: " ", shouldThrow: true, token: "xoxb-test"});
282
+ throw new Error("Expected lookupSlackUserIdByEmail to throw");
283
+ } catch (error) {
284
+ expect(isAPIError(error)).toBe(true);
285
+ expect((error as APIError).title).toBe("Email is required to look up a Slack user");
286
+ }
287
+ expect(mockAxiosGet.mock.calls.length).toBe(0);
288
+ });
289
+
290
+ it("throws when shouldThrow is true and no bot token is set", async () => {
291
+ try {
292
+ await lookupSlackUserIdByEmail({email: "jane@example.com", shouldThrow: true});
293
+ throw new Error("Expected lookupSlackUserIdByEmail to throw");
294
+ } catch (error) {
295
+ expect(isAPIError(error)).toBe(true);
296
+ expect((error as APIError).title).toContain("SLACK_BOT_TOKEN");
297
+ }
298
+ expect(mockAxiosGet.mock.calls.length).toBe(0);
299
+ });
300
+
301
+ it("throws when shouldThrow is true and the Slack HTTP call fails", async () => {
302
+ mockAxiosGet.mockRejectedValue(new Error("network down"));
303
+ try {
304
+ await lookupSlackUserIdByEmail({
305
+ email: "jane@example.com",
306
+ shouldThrow: true,
307
+ token: "xoxb-test",
308
+ });
309
+ throw new Error("Expected lookupSlackUserIdByEmail to throw");
310
+ } catch (error) {
311
+ expect(isAPIError(error)).toBe(true);
312
+ expect((error as APIError).title).toMatch(/Error looking up Slack user by email/i);
313
+ }
314
+ });
315
+
316
+ it("returns undefined when the Slack HTTP call fails and shouldThrow is false", async () => {
317
+ mockAxiosGet.mockRejectedValue(new Error("network down"));
318
+ const id = await lookupSlackUserIdByEmail({
319
+ email: "jane@example.com",
320
+ token: "xoxb-test",
321
+ });
322
+ expect(id).toBeUndefined();
323
+ });
139
324
  });
@@ -3,18 +3,177 @@ import axios from "axios";
3
3
 
4
4
  import {APIError, errorMessage} from "../errors";
5
5
  import {logger} from "../logger";
6
+
7
+ /** Slack member IDs are `U…` (users) or `W…` (Enterprise Grid). */
8
+ const SLACK_USER_ID_PATTERN = /^[UW][A-Z0-9]{8,}$/i;
9
+
10
+ const SLACK_LOOKUP_BY_EMAIL_URL = "https://slack.com/api/users.lookupByEmail";
11
+
12
+ export interface SendToSlackOptions {
13
+ slackChannel?: string;
14
+ shouldThrow?: boolean;
15
+ env?: string;
16
+ url?: string;
17
+ /**
18
+ * Slack member IDs to @-mention. Incoming webhooks only notify when the
19
+ * payload contains `<@U123…>` (or `<@W123…>`). Display names and emails in
20
+ * the message text do not mention anyone.
21
+ */
22
+ mentionUserIds?: string[];
23
+ }
24
+
25
+ export interface LookupSlackUserIdByEmailOptions {
26
+ email: string;
27
+ /** Slack bot token (`xoxb-…`) with `users:read.email`. Defaults to `SLACK_BOT_TOKEN`. */
28
+ token?: string;
29
+ shouldThrow?: boolean;
30
+ }
31
+
32
+ /**
33
+ * Normalize a Slack member ID. Accepts a bare id (`U012ABCDEF`) or a mention
34
+ * token (`<@U012ABCDEF>`). Returns undefined when the value is not a Slack
35
+ * member ID — names and emails cannot be used for mentions.
36
+ */
37
+ export const normalizeSlackUserId = (value: string): string | undefined => {
38
+ const trimmed = value.trim();
39
+ if (!trimmed) {
40
+ return undefined;
41
+ }
42
+ const unwrapped =
43
+ trimmed.startsWith("<@") && trimmed.endsWith(">") ? trimmed.slice(2, -1) : trimmed;
44
+ if (!SLACK_USER_ID_PATTERN.test(unwrapped)) {
45
+ return undefined;
46
+ }
47
+ return unwrapped.toUpperCase();
48
+ };
49
+
50
+ /** Format a Slack member ID as an incoming-webhook mention token. */
51
+ export const formatSlackUserMention = (slackUserId: string): string => {
52
+ const id = normalizeSlackUserId(slackUserId);
53
+ if (!id) {
54
+ throw new APIError({
55
+ detail: slackUserId,
56
+ status: 400,
57
+ title: "Invalid Slack user id",
58
+ });
59
+ }
60
+ return `<@${id}>`;
61
+ };
62
+
63
+ const uniqueMentionTokens = (mentionUserIds: string[] | undefined): string[] => {
64
+ if (!mentionUserIds?.length) {
65
+ return [];
66
+ }
67
+ const seen = new Set<string>();
68
+ const tokens: string[] = [];
69
+ for (const rawId of mentionUserIds) {
70
+ const id = normalizeSlackUserId(rawId);
71
+ if (!id) {
72
+ logger.warn("Skipping Slack mention; value is not a Slack member id", {value: rawId});
73
+ continue;
74
+ }
75
+ if (seen.has(id)) {
76
+ continue;
77
+ }
78
+ seen.add(id);
79
+ tokens.push(`<@${id}>`);
80
+ }
81
+ return tokens;
82
+ };
83
+
84
+ const applyMentions = (text: string, mentionUserIds: string[] | undefined): string => {
85
+ const tokens = uniqueMentionTokens(mentionUserIds);
86
+ if (tokens.length === 0) {
87
+ return text;
88
+ }
89
+ if (!text) {
90
+ return tokens.join(" ");
91
+ }
92
+ return `${tokens.join(" ")} ${text}`;
93
+ };
94
+
95
+ /**
96
+ * Resolve a workspace member's Slack user id from their email.
97
+ *
98
+ * Incoming webhooks cannot look users up. This calls `users.lookupByEmail` and
99
+ * needs a bot token with the `users:read.email` scope. Store the returned id on
100
+ * the staff/user record and pass it to `sendToSlack({mentionUserIds})`.
101
+ */
102
+ export const lookupSlackUserIdByEmail = async ({
103
+ email,
104
+ token,
105
+ shouldThrow = false,
106
+ }: LookupSlackUserIdByEmailOptions): Promise<string | undefined> => {
107
+ const trimmedEmail = email.trim();
108
+ if (!trimmedEmail) {
109
+ if (shouldThrow) {
110
+ throw new APIError({status: 400, title: "Email is required to look up a Slack user"});
111
+ }
112
+ logger.debug("lookupSlackUserIdByEmail skipped: empty email");
113
+ return undefined;
114
+ }
115
+
116
+ const botToken = token ?? process.env.SLACK_BOT_TOKEN;
117
+ if (!botToken) {
118
+ if (shouldThrow) {
119
+ throw new APIError({
120
+ status: 500,
121
+ title: "SLACK_BOT_TOKEN is not set; cannot look up Slack user ids",
122
+ });
123
+ }
124
+ logger.debug("lookupSlackUserIdByEmail skipped: no Slack bot token");
125
+ return undefined;
126
+ }
127
+
128
+ try {
129
+ const response = await axios.get<{ok: boolean; error?: string; user?: {id?: string}}>(
130
+ SLACK_LOOKUP_BY_EMAIL_URL,
131
+ {
132
+ headers: {Authorization: `Bearer ${botToken}`},
133
+ params: {email: trimmedEmail},
134
+ }
135
+ );
136
+ const payload = response.data;
137
+ if (!payload?.ok || !payload.user?.id) {
138
+ const slackError = payload?.error ?? "unknown_error";
139
+ logger.warn("Slack users.lookupByEmail did not return a user id", {
140
+ email: trimmedEmail,
141
+ slackError,
142
+ });
143
+ if (shouldThrow) {
144
+ throw new APIError({
145
+ detail: slackError,
146
+ status: 502,
147
+ title: "Slack user lookup failed",
148
+ });
149
+ }
150
+ return undefined;
151
+ }
152
+ return normalizeSlackUserId(payload.user.id);
153
+ } catch (error: unknown) {
154
+ if (error instanceof APIError) {
155
+ throw error;
156
+ }
157
+ const message = errorMessage(error);
158
+ logger.error(`Error looking up Slack user by email: ${message}`);
159
+ Sentry.captureException(error);
160
+ if (shouldThrow) {
161
+ throw new APIError({
162
+ status: 500,
163
+ title: `Error looking up Slack user by email: ${message}`,
164
+ });
165
+ }
166
+ return undefined;
167
+ }
168
+ };
169
+
6
170
  // Convenience method to send data to a Slack webhook.
7
171
  // If `url` is provided, it will be used directly instead of looking up from environment.
8
172
  // DEPRECATED: Looking up webhook URLs from the SLACK_WEBHOOKS environment variable by channel name
9
173
  // is deprecated and will be removed in a future version. Please pass the `url` parameter directly.
10
174
  export const sendToSlack = async (
11
175
  text: string,
12
- {
13
- slackChannel,
14
- shouldThrow = false,
15
- env,
16
- url,
17
- }: {slackChannel?: string; shouldThrow?: boolean; env?: string; url?: string} = {}
176
+ {slackChannel, shouldThrow = false, env, url, mentionUserIds}: SendToSlackOptions = {}
18
177
  ): Promise<void> => {
19
178
  let slackWebhookUrl = url;
20
179
 
@@ -46,9 +205,9 @@ export const sendToSlack = async (
46
205
  }
47
206
  }
48
207
 
49
- let formattedText = text;
208
+ let formattedText = applyMentions(text, mentionUserIds);
50
209
  if (env) {
51
- formattedText = `[${env.toUpperCase()}] ${text}`;
210
+ formattedText = `[${env.toUpperCase()}] ${formattedText}`;
52
211
  }
53
212
 
54
213
  try {
@@ -391,7 +391,6 @@ describe("openApi populate", () => {
391
391
  $ref: "#/components/schemas/LimitedUser",
392
392
  },
393
393
  },
394
- required: [],
395
394
  type: "object",
396
395
  },
397
396
  type: "array",
package/src/openApi.ts CHANGED
@@ -15,7 +15,7 @@ const m2sOptions = {
15
15
  props: ["readOnly", "required", "enum", "default"],
16
16
  };
17
17
 
18
- export const apiErrorContent = {
18
+ const apiErrorContent = {
19
19
  "application/json": {
20
20
  schema: {$ref: "#/components/schemas/APIError"},
21
21
  },
@@ -491,6 +491,7 @@ export const deleteOpenApiMiddleware = <T>(
491
491
 
492
492
  // This is a generic OpenAPI wrapper for a read that returns any object described by `properties`.
493
493
  // Useful for endpoints that don't directly map to a model.
494
+ /** @internal */
494
495
  export const readOpenApiMiddleware = <T>(
495
496
  options: Partial<ModelRouterOptions<T>>,
496
497
  properties: Record<string, unknown>,