@terreno/api 57.1.0 → 57.3.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 (283) hide show
  1. package/README.md +17 -7
  2. package/dist/actions.js +19 -7
  3. package/dist/adminTypes.d.ts +26 -0
  4. package/dist/api.d.ts +4 -0
  5. package/dist/api.js +12 -24
  6. package/dist/auth.d.ts +23 -10
  7. package/dist/auth.js +97 -32
  8. package/dist/authRecovery.d.ts +5 -0
  9. package/dist/authRecovery.js +350 -0
  10. package/dist/authTokens.d.ts +8 -0
  11. package/dist/authTokens.js +162 -0
  12. package/dist/betterAuth.d.ts +33 -0
  13. package/dist/betterAuthApp.d.ts +4 -0
  14. package/dist/betterAuthApp.js +26 -8
  15. package/dist/betterAuthSetup.d.ts +44 -2
  16. package/dist/betterAuthSetup.js +288 -18
  17. package/dist/collectionRegistry.d.ts +38 -0
  18. package/dist/collectionRegistry.js +72 -0
  19. package/dist/configurationApp.d.ts +11 -2
  20. package/dist/configurationApp.js +2 -4
  21. package/dist/docLoader.js +35 -6
  22. package/dist/expressServer.d.ts +26 -3
  23. package/dist/expressServer.js +79 -11
  24. package/dist/index.d.ts +16 -0
  25. package/dist/index.js +38 -2
  26. package/dist/mcp/auth.d.ts +1 -0
  27. package/dist/mcp/auth.js +47 -25
  28. package/dist/mcp/handlers.d.ts +1 -1
  29. package/dist/mcp/handlers.js +67 -233
  30. package/dist/mcp/query.d.ts +2 -2
  31. package/dist/mcp/registry.d.ts +1 -5
  32. package/dist/mcp/registry.js +31 -20
  33. package/dist/mcp/schemaGenerator.d.ts +2 -7
  34. package/dist/mcp/schemaGenerator.js +41 -116
  35. package/dist/mcp/server.d.ts +1 -0
  36. package/dist/mcp/server.js +1 -0
  37. package/dist/mcp/serviceTokens.d.ts +16 -0
  38. package/dist/mcp/serviceTokens.js +345 -0
  39. package/dist/mcp/types.d.ts +2 -2
  40. package/dist/models/mcpServiceToken.d.ts +3 -0
  41. package/dist/models/mcpServiceToken.js +208 -0
  42. package/dist/openApiBuilder.d.ts +5 -4
  43. package/dist/openApiBuilder.js +61 -8
  44. package/dist/openApiCompat.js +1 -1
  45. package/dist/openApiValidator.js +0 -2
  46. package/dist/plugins.d.ts +14 -1
  47. package/dist/plugins.js +17 -6
  48. package/dist/populate.d.ts +2 -2
  49. package/dist/populate.js +47 -42
  50. package/dist/rateLimit/applyTrustProxy.d.ts +3 -0
  51. package/dist/rateLimit/applyTrustProxy.js +17 -0
  52. package/dist/rateLimit/createStore.d.ts +2 -0
  53. package/dist/rateLimit/createStore.js +28 -0
  54. package/dist/rateLimit/memoryStore.d.ts +2 -0
  55. package/dist/rateLimit/memoryStore.js +108 -0
  56. package/dist/rateLimit/middleware.d.ts +11 -0
  57. package/dist/rateLimit/middleware.js +110 -0
  58. package/dist/rateLimit/mongoStore.d.ts +3 -0
  59. package/dist/rateLimit/mongoStore.js +122 -0
  60. package/dist/rateLimit/policies.d.ts +14 -0
  61. package/dist/rateLimit/policies.js +151 -0
  62. package/dist/rateLimit/redisStore.d.ts +3 -0
  63. package/dist/rateLimit/redisStore.js +155 -0
  64. package/dist/rateLimit/types.d.ts +54 -0
  65. package/dist/rateLimit/types.js +9 -0
  66. package/dist/rbac/access.js +5 -1
  67. package/dist/rbac/assertAllowed.d.ts +9 -0
  68. package/dist/rbac/assertAllowed.js +182 -0
  69. package/dist/rbac/modelRouterAccess.d.ts +1 -0
  70. package/dist/rbac/modelRouterAccess.js +8 -4
  71. package/dist/rbac/permissionUtils.js +3 -2
  72. package/dist/rbac/resolve.js +5 -4
  73. package/dist/rbac/routes.js +15 -6
  74. package/dist/rbac/statements.d.ts +10 -0
  75. package/dist/rbac/statements.js +13 -2
  76. package/dist/realtime/deprecation.d.ts +12 -0
  77. package/dist/realtime/deprecation.js +32 -0
  78. package/dist/realtime/realtimeApp.d.ts +1 -1
  79. package/dist/realtime/realtimeApp.js +10 -11
  80. package/dist/realtime/registry.d.ts +0 -31
  81. package/dist/realtime/registry.js +44 -31
  82. package/dist/realtime/socketAuth.d.ts +5 -5
  83. package/dist/realtime/socketAuth.js +11 -1
  84. package/dist/realtime/socketUser.d.ts +5 -1
  85. package/dist/realtime/types.d.ts +14 -4
  86. package/dist/schemaMetadata.d.ts +56 -0
  87. package/dist/schemaMetadata.js +513 -0
  88. package/dist/seedRunner.d.ts +88 -0
  89. package/dist/seedRunner.js +627 -0
  90. package/dist/sync/executors.d.ts +12 -2
  91. package/dist/sync/executors.js +8 -10
  92. package/dist/sync/loadHarness.js +28 -19
  93. package/dist/sync/models.js +26 -24
  94. package/dist/sync/mutationHandler.d.ts +9 -0
  95. package/dist/sync/mutationHandler.js +11 -6
  96. package/dist/sync/registrationSideEffects.d.ts +35 -0
  97. package/dist/sync/registrationSideEffects.js +151 -0
  98. package/dist/sync/registry.d.ts +2 -52
  99. package/dist/sync/registry.js +38 -187
  100. package/dist/sync/routes.js +3 -2
  101. package/dist/sync/scripts/compactTombstones.js +0 -2
  102. package/dist/sync/syncApp.d.ts +3 -3
  103. package/dist/sync/syncApp.js +4 -4
  104. package/dist/sync/syncBatch.js +3 -2
  105. package/dist/sync/syncSeqPlugin.d.ts +1 -1
  106. package/dist/sync/syncSeqPlugin.js +20 -16
  107. package/dist/terrenoApp.d.ts +19 -5
  108. package/dist/terrenoApp.js +66 -18
  109. package/dist/tests/models.d.ts +2 -0
  110. package/dist/tests/models.js +6 -0
  111. package/dist/types/authToken.d.ts +33 -0
  112. package/dist/types/authToken.js +2 -0
  113. package/dist/types/mcpServiceToken.d.ts +41 -0
  114. package/dist/types/mcpServiceToken.js +2 -0
  115. package/dist/webhooks/headerValue.d.ts +2 -0
  116. package/dist/webhooks/headerValue.js +14 -0
  117. package/dist/webhooks/idempotency/memoryStore.d.ts +10 -0
  118. package/dist/webhooks/idempotency/memoryStore.js +65 -0
  119. package/dist/webhooks/idempotency/mongoStore.d.ts +4 -0
  120. package/dist/webhooks/idempotency/mongoStore.js +150 -0
  121. package/dist/webhooks/idempotency/webhookReceipt.d.ts +62 -0
  122. package/dist/webhooks/idempotency/webhookReceipt.js +39 -0
  123. package/dist/webhooks/rawBody.d.ts +14 -0
  124. package/dist/webhooks/rawBody.js +22 -0
  125. package/dist/webhooks/timingSafeEqual.d.ts +4 -0
  126. package/dist/webhooks/timingSafeEqual.js +17 -0
  127. package/dist/webhooks/verifiers/hmac.d.ts +15 -0
  128. package/dist/webhooks/verifiers/hmac.js +49 -0
  129. package/dist/webhooks/verifiers/sendgrid.d.ts +10 -0
  130. package/dist/webhooks/verifiers/sendgrid.js +56 -0
  131. package/dist/webhooks/verifiers/stripe.d.ts +9 -0
  132. package/dist/webhooks/verifiers/stripe.js +99 -0
  133. package/dist/webhooks/verifiers/twilio.d.ts +9 -0
  134. package/dist/webhooks/verifiers/twilio.js +112 -0
  135. package/dist/webhooks/webhooksApp.d.ts +33 -0
  136. package/dist/webhooks/webhooksApp.js +195 -0
  137. package/package.json +5 -6
  138. package/src/__snapshots__/openApi.test.ts.snap +270 -0
  139. package/src/__snapshots__/openApiBuilder.test.ts.snap +30 -12
  140. package/src/__snapshots__/schemaMetadata.test.ts.snap +197 -0
  141. package/src/actions.ts +20 -13
  142. package/src/adminModelRouter.test.ts +133 -0
  143. package/src/adminTypes.ts +23 -0
  144. package/src/api.arrayOperations.test.ts +43 -31
  145. package/src/api.hooks.test.ts +38 -29
  146. package/src/api.query.test.ts +31 -31
  147. package/src/api.test.ts +95 -96
  148. package/src/api.ts +16 -27
  149. package/src/auth.test.ts +107 -51
  150. package/src/auth.ts +98 -29
  151. package/src/authRecovery.test.ts +281 -0
  152. package/src/authRecovery.ts +279 -0
  153. package/src/authTokens.test.ts +94 -0
  154. package/src/authTokens.ts +118 -0
  155. package/src/authVerification.test.ts +293 -0
  156. package/src/betterAuth.ts +24 -0
  157. package/src/betterAuthApp.test.ts +1 -0
  158. package/src/betterAuthApp.ts +27 -9
  159. package/src/betterAuthSetup.test.ts +568 -38
  160. package/src/betterAuthSetup.ts +260 -5
  161. package/src/collectionRegistry.test.ts +165 -0
  162. package/src/collectionRegistry.ts +115 -0
  163. package/src/configurationApp.ts +13 -7
  164. package/src/docLoader.test.ts +45 -1
  165. package/src/docLoader.ts +37 -6
  166. package/src/express.d.ts +1 -0
  167. package/src/expressServer.test.ts +130 -66
  168. package/src/expressServer.ts +75 -19
  169. package/src/githubAuth.test.ts +60 -55
  170. package/src/index.ts +58 -0
  171. package/src/mcp/auth.test.ts +47 -0
  172. package/src/mcp/auth.ts +32 -11
  173. package/src/mcp/handlers.ts +45 -172
  174. package/src/mcp/integration.test.ts +59 -9
  175. package/src/mcp/query.ts +2 -4
  176. package/src/mcp/registry.ts +29 -20
  177. package/src/mcp/schemaGenerator.test.ts +8 -0
  178. package/src/mcp/schemaGenerator.ts +49 -131
  179. package/src/mcp/server.ts +2 -0
  180. package/src/mcp/serviceTokens.test.ts +330 -0
  181. package/src/mcp/serviceTokens.ts +307 -0
  182. package/src/mcp/toolGenerator.test.ts +1 -1
  183. package/src/mcp/types.ts +2 -6
  184. package/src/models/mcpServiceToken.test.ts +129 -0
  185. package/src/models/mcpServiceToken.ts +158 -0
  186. package/src/openApi.test.ts +80 -64
  187. package/src/openApiBuilder.test.ts +95 -7
  188. package/src/openApiBuilder.ts +46 -9
  189. package/src/openApiCompat.ts +1 -1
  190. package/src/openApiValidator.test.ts +49 -54
  191. package/src/openApiValidator.ts +1 -3
  192. package/src/plugins.test.ts +14 -0
  193. package/src/plugins.ts +34 -9
  194. package/src/populate.test.ts +34 -0
  195. package/src/populate.ts +40 -29
  196. package/src/rateLimit/applyTrustProxy.ts +17 -0
  197. package/src/rateLimit/createStore.ts +25 -0
  198. package/src/rateLimit/memoryStore.ts +40 -0
  199. package/src/rateLimit/middleware.ts +79 -0
  200. package/src/rateLimit/mongoStore.test.ts +80 -0
  201. package/src/rateLimit/mongoStore.ts +76 -0
  202. package/src/rateLimit/policies.ts +130 -0
  203. package/src/rateLimit/rateLimit.test.ts +328 -0
  204. package/src/rateLimit/redisStore.ioredis.test.ts +29 -0
  205. package/src/rateLimit/redisStore.test.ts +114 -0
  206. package/src/rateLimit/redisStore.ts +85 -0
  207. package/src/rateLimit/types.ts +64 -0
  208. package/src/rbac/access.ts +5 -1
  209. package/src/rbac/assertAllowed.test.ts +325 -0
  210. package/src/rbac/assertAllowed.ts +157 -0
  211. package/src/rbac/backfillAdmins.test.ts +124 -0
  212. package/src/rbac/fieldViews.test.ts +89 -0
  213. package/src/rbac/modelRouterAccess.test.ts +126 -0
  214. package/src/rbac/modelRouterAccess.ts +5 -2
  215. package/src/rbac/permissionUtils.ts +3 -2
  216. package/src/rbac/realtimeAccess.test.ts +109 -1
  217. package/src/rbac/resolve.ts +5 -4
  218. package/src/rbac/roleManager.test.ts +169 -0
  219. package/src/rbac/routes.test.ts +233 -0
  220. package/src/rbac/routes.ts +16 -6
  221. package/src/rbac/statements.test.ts +2 -0
  222. package/src/rbac/statements.ts +12 -1
  223. package/src/realtime/deprecation.test.ts +60 -0
  224. package/src/realtime/deprecation.ts +32 -0
  225. package/src/realtime/realtime.test.ts +8 -4
  226. package/src/realtime/realtimeApp.ts +10 -11
  227. package/src/realtime/realtimeAppSetup.test.ts +32 -5
  228. package/src/realtime/registry.ts +48 -42
  229. package/src/realtime/sessionRevalidation.test.ts +57 -44
  230. package/src/realtime/socketAuth.test.ts +75 -23
  231. package/src/realtime/socketAuth.ts +17 -6
  232. package/src/realtime/socketUser.ts +5 -3
  233. package/src/realtime/types.ts +14 -4
  234. package/src/schemaMetadata.test.ts +405 -0
  235. package/src/schemaMetadata.ts +593 -0
  236. package/src/scrubAdminFields.test.ts +105 -0
  237. package/src/seedRunner.test.ts +591 -0
  238. package/src/seedRunner.ts +464 -0
  239. package/src/sync/docMatchesMutationData.test.ts +16 -0
  240. package/src/sync/ensureSyncIndexes.test.ts +54 -15
  241. package/src/sync/executors.test.ts +40 -0
  242. package/src/sync/executors.ts +24 -12
  243. package/src/sync/integration.test.ts +15 -7
  244. package/src/sync/loadHarness.ts +28 -19
  245. package/src/sync/models.ts +32 -18
  246. package/src/sync/mutationHandler.test.ts +16 -16
  247. package/src/sync/mutationHandler.ts +9 -7
  248. package/src/sync/registrationSideEffects.test.ts +126 -0
  249. package/src/sync/registrationSideEffects.ts +131 -0
  250. package/src/sync/registry.ts +45 -171
  251. package/src/sync/routes.ts +3 -2
  252. package/src/sync/scripts/compactTombstones.ts +0 -2
  253. package/src/sync/sessionRevalidationIntegration.test.ts +12 -11
  254. package/src/sync/sync.test.ts +25 -23
  255. package/src/sync/syncApp.ts +4 -4
  256. package/src/sync/syncBatch.ts +3 -2
  257. package/src/sync/syncFrontier.test.ts +17 -15
  258. package/src/sync/syncPhaseC.test.ts +54 -43
  259. package/src/sync/syncRoutes.test.ts +51 -36
  260. package/src/sync/syncSeqPlugin.ts +66 -44
  261. package/src/sync/syncSocket.test.ts +112 -81
  262. package/src/terrenoApp.mcpServiceTokens.test.ts +173 -0
  263. package/src/terrenoApp.ts +87 -15
  264. package/src/tests/models.ts +14 -1
  265. package/src/types/authToken.ts +43 -0
  266. package/src/types/mcpServiceToken.ts +54 -0
  267. package/src/webhooks/headerValue.test.ts +22 -0
  268. package/src/webhooks/headerValue.ts +12 -0
  269. package/src/webhooks/idempotency/memoryStore.ts +34 -0
  270. package/src/webhooks/idempotency/mongoStore.test.ts +274 -0
  271. package/src/webhooks/idempotency/mongoStore.ts +83 -0
  272. package/src/webhooks/idempotency/webhookReceipt.ts +70 -0
  273. package/src/webhooks/rawBody.test.ts +74 -0
  274. package/src/webhooks/rawBody.ts +23 -0
  275. package/src/webhooks/timingSafeEqual.ts +16 -0
  276. package/src/webhooks/verifiers/hmac.test.ts +110 -0
  277. package/src/webhooks/verifiers/hmac.ts +54 -0
  278. package/src/webhooks/verifiers/providerVerifiers.test.ts +388 -0
  279. package/src/webhooks/verifiers/sendgrid.ts +59 -0
  280. package/src/webhooks/verifiers/stripe.ts +67 -0
  281. package/src/webhooks/verifiers/twilio.ts +69 -0
  282. package/src/webhooks/webhooksApp.test.ts +221 -0
  283. package/src/webhooks/webhooksApp.ts +144 -0
@@ -1,12 +1,11 @@
1
- // noExplicitAny: test mock typing
2
- // biome-ignore-all lint/suspicious/noExplicitAny: test mock typing
3
1
  import {beforeEach, describe, expect, it} from "bun:test";
4
2
  import type express from "express";
5
3
  import type {Router} from "express";
6
4
  import supertest from "supertest";
7
5
  import type TestAgent from "supertest/lib/agent";
8
6
 
9
- import {type ModelRouterOptions, modelRouter} from "./api";
7
+ import {type ModelRouterOptions, modelRouter, type OpenApiMiddleware} from "./api";
8
+ import type {UserModel as AuthUserModel} from "./auth";
10
9
  import {
11
10
  createOpenApiMiddleware,
12
11
  deleteOpenApiMiddleware,
@@ -17,9 +16,30 @@ import {
17
16
  } from "./openApi";
18
17
  import {Permissions} from "./permissions";
19
18
  import {TerrenoApp} from "./terrenoApp";
20
- import {FoodModel, setupDb, UserModel} from "./tests";
21
-
22
- function getMessageSummaryOpenApiMiddleware(options: Partial<ModelRouterOptions<any>>): any {
19
+ import {type Food, FoodModel, setupDb, UserModel} from "./tests";
20
+
21
+ const createPassThroughMiddleware = (): express.RequestHandler => (_req, _res, next) => next();
22
+
23
+ const createOpenApiStub = (
24
+ path: OpenApiMiddleware["path"] = () => createPassThroughMiddleware()
25
+ ): OpenApiMiddleware => {
26
+ return Object.assign(createPassThroughMiddleware(), {
27
+ component: () => undefined,
28
+ document: {},
29
+ path,
30
+ schema: () => undefined,
31
+ });
32
+ };
33
+
34
+ const asFoodOptions = (
35
+ options?: Partial<ModelRouterOptions<unknown>>
36
+ ): Partial<ModelRouterOptions<Food>> => {
37
+ return options as unknown as Partial<ModelRouterOptions<Food>>;
38
+ };
39
+
40
+ function getMessageSummaryOpenApiMiddleware(
41
+ options: Partial<ModelRouterOptions<unknown>>
42
+ ): express.RequestHandler {
23
43
  if (!options.openApi) {
24
44
  throw new Error("Expected openApi to be configured for test routes");
25
45
  }
@@ -55,11 +75,11 @@ function getMessageSummaryOpenApiMiddleware(options: Partial<ModelRouterOptions<
55
75
  });
56
76
  }
57
77
 
58
- function addRoutes(router: Router, options?: Partial<ModelRouterOptions<any>>): void {
78
+ function addRoutes(router: Router, options?: Partial<ModelRouterOptions<unknown>>): void {
59
79
  router.use(
60
80
  "/food",
61
- modelRouter(FoodModel as any, {
62
- ...options,
81
+ modelRouter(FoodModel, {
82
+ ...asFoodOptions(options),
63
83
  allowAnonymous: true,
64
84
  openApiExtraModelProperties: {
65
85
  foo: {
@@ -93,7 +113,7 @@ describe("openApi", () => {
93
113
  app = new TerrenoApp({
94
114
  configureApp: addRoutes,
95
115
  skipListen: true,
96
- userModel: UserModel as any,
116
+ userModel: UserModel as unknown as AuthUserModel,
97
117
  }).build();
98
118
  });
99
119
 
@@ -187,11 +207,14 @@ describe("openApi", () => {
187
207
  });
188
208
  });
189
209
 
190
- function addRoutesStringQuery(router: Router, options?: Partial<ModelRouterOptions<any>>): void {
210
+ function addRoutesStringQuery(
211
+ router: Router,
212
+ options?: Partial<ModelRouterOptions<unknown>>
213
+ ): void {
191
214
  router.use(
192
215
  "/food",
193
- modelRouter(FoodModel as any, {
194
- ...options,
216
+ modelRouter(FoodModel, {
217
+ ...asFoodOptions(options),
195
218
  allowAnonymous: true,
196
219
  permissions: {
197
220
  create: [Permissions.IsAny],
@@ -216,7 +239,7 @@ describe("openApi string query fields", () => {
216
239
  app = new TerrenoApp({
217
240
  configureApp: addRoutesStringQuery,
218
241
  skipListen: true,
219
- userModel: UserModel as any,
242
+ userModel: UserModel as unknown as AuthUserModel,
220
243
  }).build();
221
244
  });
222
245
 
@@ -240,7 +263,7 @@ describe("openApi string query fields", () => {
240
263
  });
241
264
  });
242
265
 
243
- function addRoutesPopulate(router: Router, options?: Partial<ModelRouterOptions<any>>): void {
266
+ function addRoutesPopulate(router: Router, options?: Partial<ModelRouterOptions<unknown>>): void {
244
267
  options?.openApi?.component("schemas", "LimitedUser", {
245
268
  properties: {
246
269
  email: {
@@ -257,8 +280,8 @@ function addRoutesPopulate(router: Router, options?: Partial<ModelRouterOptions<
257
280
 
258
281
  router.use(
259
282
  "/food",
260
- modelRouter(FoodModel as any, {
261
- ...options,
283
+ modelRouter(FoodModel, {
284
+ ...asFoodOptions(options),
262
285
  allowAnonymous: true,
263
286
  openApiExtraModelProperties: {
264
287
  foo: {
@@ -300,7 +323,7 @@ describe("openApi without swagger", () => {
300
323
  app = new TerrenoApp({
301
324
  configureApp: addRoutes,
302
325
  skipListen: true,
303
- userModel: UserModel as any,
326
+ userModel: UserModel as unknown as AuthUserModel,
304
327
  }).build();
305
328
  });
306
329
 
@@ -320,7 +343,7 @@ describe("openApi populate", () => {
320
343
  app = new TerrenoApp({
321
344
  configureApp: addRoutesPopulate,
322
345
  skipListen: true,
323
- userModel: UserModel as any,
346
+ userModel: UserModel as unknown as AuthUserModel,
324
347
  }).build();
325
348
  });
326
349
 
@@ -395,14 +418,14 @@ describe("openApi populate", () => {
395
418
 
396
419
  describe("openApi middleware no-op paths", () => {
397
420
  it("getOpenApiMiddleware returns noop when openApi not configured", () => {
398
- const mw = getOpenApiMiddleware(FoodModel as any, {});
421
+ const mw = getOpenApiMiddleware(FoodModel, {});
399
422
  expect(typeof mw).toBe("function");
400
423
  expect(mw.length).toBe(3);
401
424
  });
402
425
 
403
426
  it("getOpenApiMiddleware returns noop when read permissions are empty", () => {
404
- const mw = getOpenApiMiddleware(FoodModel as any, {
405
- openApi: {component: () => {}, path: () => (() => {}) as any} as any,
427
+ const mw = getOpenApiMiddleware(FoodModel, {
428
+ openApi: createOpenApiStub(),
406
429
  permissions: {
407
430
  create: [],
408
431
  delete: [],
@@ -416,13 +439,13 @@ describe("openApi middleware no-op paths", () => {
416
439
  });
417
440
 
418
441
  it("listOpenApiMiddleware returns noop when openApi not configured", () => {
419
- const mw = listOpenApiMiddleware(FoodModel as any, {});
442
+ const mw = listOpenApiMiddleware(FoodModel, {});
420
443
  expect(mw.length).toBe(3);
421
444
  });
422
445
 
423
446
  it("listOpenApiMiddleware returns noop when list permissions are empty", () => {
424
- const mw = listOpenApiMiddleware(FoodModel as any, {
425
- openApi: {path: () => (() => {}) as any} as any,
447
+ const mw = listOpenApiMiddleware(FoodModel, {
448
+ openApi: createOpenApiStub(),
426
449
  permissions: {
427
450
  create: [],
428
451
  delete: [],
@@ -437,14 +460,12 @@ describe("openApi middleware no-op paths", () => {
437
460
  it("listOpenApiMiddleware emits x-terreno-sync when sync is configured", () => {
438
461
  let captured: Record<string, unknown> | undefined;
439
462
  listOpenApiMiddleware(
440
- FoodModel as any,
463
+ FoodModel,
441
464
  {
442
- openApi: {
443
- path: (spec: Record<string, unknown>) => {
444
- captured = spec;
445
- return (() => {}) as express.RequestHandler;
446
- },
447
- } as any,
465
+ openApi: createOpenApiStub((spec: Record<string, unknown>) => {
466
+ captured = spec;
467
+ return createPassThroughMiddleware();
468
+ }),
448
469
  permissions: {
449
470
  create: [Permissions.IsAny],
450
471
  delete: [Permissions.IsAny],
@@ -461,13 +482,11 @@ describe("openApi middleware no-op paths", () => {
461
482
 
462
483
  it("listOpenApiMiddleware omits x-terreno-sync when sync is not configured", () => {
463
484
  let captured: Record<string, unknown> | undefined;
464
- listOpenApiMiddleware(FoodModel as any, {
465
- openApi: {
466
- path: (spec: Record<string, unknown>) => {
467
- captured = spec;
468
- return (() => {}) as express.RequestHandler;
469
- },
470
- } as any,
485
+ listOpenApiMiddleware(FoodModel, {
486
+ openApi: createOpenApiStub((spec: Record<string, unknown>) => {
487
+ captured = spec;
488
+ return createPassThroughMiddleware();
489
+ }),
471
490
  permissions: {
472
491
  create: [Permissions.IsAny],
473
492
  delete: [Permissions.IsAny],
@@ -481,13 +500,11 @@ describe("openApi middleware no-op paths", () => {
481
500
 
482
501
  it("listOpenApiMiddleware falls back to the model collection name without routePath", () => {
483
502
  let captured: Record<string, unknown> | undefined;
484
- listOpenApiMiddleware(FoodModel as any, {
485
- openApi: {
486
- path: (spec: Record<string, unknown>) => {
487
- captured = spec;
488
- return (() => {}) as express.RequestHandler;
489
- },
490
- } as any,
503
+ listOpenApiMiddleware(FoodModel, {
504
+ openApi: createOpenApiStub((spec: Record<string, unknown>) => {
505
+ captured = spec;
506
+ return createPassThroughMiddleware();
507
+ }),
491
508
  permissions: {
492
509
  create: [Permissions.IsAny],
493
510
  delete: [Permissions.IsAny],
@@ -507,10 +524,10 @@ describe("openApi middleware no-op paths", () => {
507
524
  let captured: Record<string, unknown> | undefined;
508
525
  const capturePath = (spec: Record<string, unknown>): express.RequestHandler => {
509
526
  captured = spec;
510
- return (() => {}) as express.RequestHandler;
527
+ return createPassThroughMiddleware();
511
528
  };
512
- const baseOptions = {
513
- openApi: {path: capturePath} as any,
529
+ const baseOptions: Partial<ModelRouterOptions<Food>> = {
530
+ openApi: createOpenApiStub(capturePath),
514
531
  permissions: {
515
532
  create: [Permissions.IsAny],
516
533
  delete: [Permissions.IsAny],
@@ -521,7 +538,7 @@ describe("openApi middleware no-op paths", () => {
521
538
  };
522
539
 
523
540
  listOpenApiMiddleware(
524
- FoodModel as any,
541
+ FoodModel,
525
542
  {
526
543
  ...baseOptions,
527
544
  sync: {scope: {field: "organizationId", type: "tenant"}},
@@ -531,7 +548,7 @@ describe("openApi middleware no-op paths", () => {
531
548
  expect(captured?.["x-terreno-sync"]).toEqual({collection: "projects", scope: "tenant"});
532
549
 
533
550
  listOpenApiMiddleware(
534
- FoodModel as any,
551
+ FoodModel,
535
552
  {
536
553
  ...baseOptions,
537
554
  sync: {scope: () => "workspace"},
@@ -542,13 +559,13 @@ describe("openApi middleware no-op paths", () => {
542
559
  });
543
560
 
544
561
  it("createOpenApiMiddleware returns noop when openApi not configured", () => {
545
- const mw = createOpenApiMiddleware(FoodModel as any, {});
562
+ const mw = createOpenApiMiddleware(FoodModel, {});
546
563
  expect(mw.length).toBe(3);
547
564
  });
548
565
 
549
566
  it("createOpenApiMiddleware returns noop when create permissions are empty", () => {
550
- const mw = createOpenApiMiddleware(FoodModel as any, {
551
- openApi: {path: () => (() => {}) as any} as any,
567
+ const mw = createOpenApiMiddleware(FoodModel, {
568
+ openApi: createOpenApiStub(),
552
569
  permissions: {
553
570
  create: [],
554
571
  delete: [],
@@ -561,13 +578,13 @@ describe("openApi middleware no-op paths", () => {
561
578
  });
562
579
 
563
580
  it("patchOpenApiMiddleware returns noop when openApi not configured", () => {
564
- const mw = patchOpenApiMiddleware(FoodModel as any, {});
581
+ const mw = patchOpenApiMiddleware(FoodModel, {});
565
582
  expect(mw.length).toBe(3);
566
583
  });
567
584
 
568
585
  it("patchOpenApiMiddleware returns noop when update permissions are empty", () => {
569
- const mw = patchOpenApiMiddleware(FoodModel as any, {
570
- openApi: {path: () => (() => {}) as any} as any,
586
+ const mw = patchOpenApiMiddleware(FoodModel, {
587
+ openApi: createOpenApiStub(),
571
588
  permissions: {
572
589
  create: [],
573
590
  delete: [],
@@ -580,13 +597,13 @@ describe("openApi middleware no-op paths", () => {
580
597
  });
581
598
 
582
599
  it("deleteOpenApiMiddleware returns noop when openApi not configured", () => {
583
- const mw = deleteOpenApiMiddleware(FoodModel as any, {});
600
+ const mw = deleteOpenApiMiddleware(FoodModel, {});
584
601
  expect(mw.length).toBe(3);
585
602
  });
586
603
 
587
604
  it("deleteOpenApiMiddleware returns noop when delete permissions are empty", () => {
588
- const mw = deleteOpenApiMiddleware(FoodModel as any, {
589
- openApi: {path: () => (() => {}) as any} as any,
605
+ const mw = deleteOpenApiMiddleware(FoodModel, {
606
+ openApi: createOpenApiStub(),
590
607
  permissions: {
591
608
  create: [],
592
609
  delete: [],
@@ -606,7 +623,7 @@ describe("openApi middleware no-op paths", () => {
606
623
  it("readOpenApiMiddleware returns noop when read permissions are empty", () => {
607
624
  const mw = readOpenApiMiddleware(
608
625
  {
609
- openApi: {path: () => (() => {}) as any} as any,
626
+ openApi: createOpenApiStub(),
610
627
  permissions: {
611
628
  create: [],
612
629
  delete: [],
@@ -623,11 +640,10 @@ describe("openApi middleware no-op paths", () => {
623
640
  });
624
641
 
625
642
  it("readOpenApiMiddleware returns middleware when configured with permissions", () => {
626
- // Use a simple path stub that returns a middleware function
627
- const pathFn = () => ((_req: any, _res: any, next: any) => next()) as any;
643
+ const pathFn: OpenApiMiddleware["path"] = () => createPassThroughMiddleware();
628
644
  const mw = readOpenApiMiddleware(
629
645
  {
630
- openApi: {path: pathFn} as any,
646
+ openApi: createOpenApiStub(pathFn),
631
647
  permissions: {
632
648
  create: [],
633
649
  delete: [],
@@ -1,4 +1,4 @@
1
- import {beforeEach, describe, expect, it} from "bun:test";
1
+ import {afterEach, beforeEach, describe, expect, it} from "bun:test";
2
2
  import type express from "express";
3
3
  import type {Router} from "express";
4
4
  import supertest from "supertest";
@@ -378,7 +378,7 @@ describe("OpenApiMiddlewareBuilder without OpenAPI", () => {
378
378
  .withTags(["test"])
379
379
  .withSummary("Test")
380
380
  .withResponse(200, {id: {type: "string"}})
381
- .build() as express.RequestHandler;
381
+ .build();
382
382
 
383
383
  // Middleware should be a function
384
384
  expect(typeof middleware).toBe("function");
@@ -392,7 +392,7 @@ describe("OpenApiMiddlewareBuilder without OpenAPI", () => {
392
392
  });
393
393
 
394
394
  it("build returns noop middleware when options is empty", () => {
395
- const middleware = createOpenApiBuilder({}).build() as express.RequestHandler;
395
+ const middleware = createOpenApiBuilder({}).build();
396
396
 
397
397
  let nextCalled = false;
398
398
  middleware({} as express.Request, {} as express.Response, () => {
@@ -476,9 +476,17 @@ describe("OpenApiMiddlewareBuilder configuration", () => {
476
476
  });
477
477
 
478
478
  describe("OpenApiMiddlewareBuilder withValidation / buildWithSchemas", () => {
479
- beforeEach(() => {
479
+ const resetValidatorConfig = (): void => {
480
480
  const {resetOpenApiValidatorConfig} = require("./openApiValidator");
481
481
  resetOpenApiValidatorConfig();
482
+ };
483
+
484
+ beforeEach(() => {
485
+ resetValidatorConfig();
486
+ });
487
+
488
+ afterEach(() => {
489
+ resetValidatorConfig();
482
490
  });
483
491
 
484
492
  it("buildWithSchemas returns bodySchema and querySchema", () => {
@@ -519,15 +527,15 @@ describe("OpenApiMiddlewareBuilder withValidation / buildWithSchemas", () => {
519
527
  expect(result.validationEnabled).toBe(false);
520
528
  });
521
529
 
522
- it("build() returns an array when validation is enabled with body and query", () => {
530
+ it("build() returns a single composed middleware when validation is enabled with body and query", () => {
523
531
  const result = createOpenApiBuilder({})
524
532
  .withRequestBody({name: {required: true, type: "string"}})
525
533
  .withQueryParameter("page", {type: "number"})
526
534
  .withValidation()
527
535
  .build();
528
536
 
529
- expect(Array.isArray(result)).toBe(true);
530
- expect(result).toHaveLength(3);
537
+ expect(typeof result).toBe("function");
538
+ expect(Array.isArray(result)).toBe(false);
531
539
  });
532
540
 
533
541
  it("build() returns a single middleware when validation is disabled", () => {
@@ -554,4 +562,84 @@ describe("OpenApiMiddlewareBuilder withValidation / buildWithSchemas", () => {
554
562
  // No body/query validation = just the openApi middleware (single fn)
555
563
  expect(typeof result).toBe("function");
556
564
  });
565
+
566
+ // The composed handler must still run every validator in order and surface a
567
+ // validator's synchronous throw, which routes previously got from Express
568
+ // spreading an array of middleware.
569
+ describe("composed validation middleware", () => {
570
+ const buildTestApp = (): express.Express => {
571
+ const {configureOpenApiValidator} = require("./openApiValidator");
572
+ configureOpenApiValidator({logValidationErrors: false});
573
+
574
+ const {apiErrorMiddleware} = require("./errors");
575
+ const expressLib = require("express") as typeof import("express");
576
+
577
+ const app = expressLib();
578
+ app.use(expressLib.json());
579
+ app.post(
580
+ "/widgets",
581
+ createOpenApiBuilder({})
582
+ .withRequestBody({name: {required: true, type: "string"}})
583
+ .withQueryParameter("page", {type: "number"})
584
+ .withValidation()
585
+ .build(),
586
+ (req, res) => {
587
+ res.json({name: (req.body as {name: string}).name});
588
+ }
589
+ );
590
+ app.use(apiErrorMiddleware);
591
+ return app;
592
+ };
593
+
594
+ it("passes a valid request through to the route handler", async () => {
595
+ const response = await supertest(buildTestApp())
596
+ .post("/widgets?page=2")
597
+ .send({name: "valid"});
598
+
599
+ expect(response.status).toBe(200);
600
+ expect(response.body.name).toBe("valid");
601
+ });
602
+
603
+ it("rejects a body missing a required field with a 400", async () => {
604
+ const response = await supertest(buildTestApp()).post("/widgets").send({});
605
+
606
+ expect(response.status).toBe(400);
607
+ });
608
+
609
+ it("keeps the documented path in /openapi.json when validation is composed", async () => {
610
+ process.env.REFRESH_TOKEN_SECRET = "testsecret1234";
611
+ process.env.ENABLE_SWAGGER = "true";
612
+
613
+ const {configureOpenApiValidator} = require("./openApiValidator");
614
+ configureOpenApiValidator({logValidationErrors: false});
615
+
616
+ const addValidatedWidgetRoute = (
617
+ router: express.Router,
618
+ options?: Partial<ModelRouterOptions<unknown>>
619
+ ): void => {
620
+ const middleware = createOpenApiBuilder(options ?? {})
621
+ .withTags(["Widgets"])
622
+ .withSummary("Create a widget")
623
+ .withRequestBody({name: {required: true, type: "string"}})
624
+ .withQueryParameter("page", {type: "number"})
625
+ .withValidation()
626
+ .build();
627
+ router.post("/widgets", middleware, (_req, res) => {
628
+ res.json({ok: true});
629
+ });
630
+ };
631
+
632
+ const documentedApp = new TerrenoApp({
633
+ configureApp: addValidatedWidgetRoute,
634
+ skipListen: true,
635
+ userModel: UserModel as unknown as AuthUserModel,
636
+ }).build();
637
+
638
+ const spec = await supertest(documentedApp).get("/openapi.json").expect(200);
639
+ expect(spec.body.paths["/widgets"]).toBeDefined();
640
+ expect(spec.body.paths["/widgets"].post).toBeDefined();
641
+ expect(spec.body.paths["/widgets"].post.summary).toBe("Create a widget");
642
+ expect(spec.body.paths["/widgets"].post.requestBody).toBeDefined();
643
+ });
644
+ });
557
645
  });
@@ -41,6 +41,46 @@ import {
41
41
  validateQueryParams,
42
42
  validateRequestBody,
43
43
  } from "./openApiValidator";
44
+ import {
45
+ get as getOpenApiLayerSchema,
46
+ set as setOpenApiLayerSchema,
47
+ } from "./vendor/wesleytodd-openapi/lib/layer-schema";
48
+
49
+ /**
50
+ * Run handlers in order as one Express middleware function.
51
+ *
52
+ * `@wesleytodd/openapi` stores path schemas on a Map keyed by the function
53
+ * Express registers. Copying the schema from the documentation handler onto
54
+ * the composed function keeps `/openapi.json` generation working.
55
+ */
56
+ const composeRequestHandlers = (handlers: express.RequestHandler[]): express.RequestHandler => {
57
+ const composed: express.RequestHandler = (req, res, next): void => {
58
+ const run = (index: number): void => {
59
+ if (index >= handlers.length) {
60
+ next();
61
+ return;
62
+ }
63
+ handlers[index](req, res, (error?: unknown): void => {
64
+ if (error) {
65
+ next(error);
66
+ return;
67
+ }
68
+ run(index + 1);
69
+ });
70
+ };
71
+ run(0);
72
+ };
73
+
74
+ for (const handler of handlers) {
75
+ const schema = getOpenApiLayerSchema(handler);
76
+ if (schema) {
77
+ setOpenApiLayerSchema(composed, schema);
78
+ break;
79
+ }
80
+ }
81
+
82
+ return composed;
83
+ };
44
84
 
45
85
  /**
46
86
  * Defines a property within an OpenAPI schema.
@@ -741,13 +781,14 @@ export class OpenApiMiddlewareBuilder {
741
781
  * that integrates with the OpenAPI documentation system. If no OpenAPI
742
782
  * path is configured in options, returns a no-op middleware.
743
783
  *
744
- * If validation was enabled via `withValidation()`, returns an array
745
- * of middleware: [openApiDocMiddleware, validationMiddleware].
784
+ * If validation was enabled via `withValidation()`, body and query
785
+ * validators are composed into the same RequestHandler (they still run
786
+ * in order: OpenAPI docs, then body, then query).
746
787
  *
747
788
  * Default error responses (400, 401, 403, 404, 405) are automatically
748
789
  * merged with the configured responses.
749
790
  *
750
- * @returns Express middleware function(s) for OpenAPI documentation and optional validation
791
+ * @returns Express middleware for OpenAPI documentation and optional validation
751
792
  *
752
793
  * @example
753
794
  * ```typescript
@@ -759,9 +800,7 @@ export class OpenApiMiddlewareBuilder {
759
800
  * router.get("/users/:id", middleware, getUserHandler);
760
801
  * ```
761
802
  */
762
- // noExplicitAny: returns either a single RequestHandler or an array depending on validation config — callers spread or invoke
763
- // biome-ignore lint/suspicious/noExplicitAny: returns either a single RequestHandler or an array depending on validation config
764
- build(): any {
803
+ build(): express.RequestHandler {
765
804
  const noop: express.RequestHandler = (_a, _b, next) => next();
766
805
 
767
806
  // Build the OpenAPI documentation middleware
@@ -808,13 +847,11 @@ export class OpenApiMiddlewareBuilder {
808
847
  validators.push(validateQueryParams(this.queryParamSchemas, {enabled: true}));
809
848
  }
810
849
 
811
- // If only one middleware (the openApi one), return it directly
812
850
  if (validators.length === 1) {
813
851
  return openApiMiddleware;
814
852
  }
815
853
 
816
- // Return array of middleware to be spread in route definition
817
- return validators;
854
+ return composeRequestHandlers(validators);
818
855
  }
819
856
  }
820
857
 
@@ -175,7 +175,7 @@ export const patchExpressRouterUse = (): void => {
175
175
  ) => unknown;
176
176
  Object.defineProperty(routerPrototype, "use", {
177
177
  ...useDescriptor,
178
- value: function patchedRouterUse(this: {stack?: PatchedLayer[]}, ...args: unknown[]): unknown {
178
+ value(this: {stack?: PatchedLayer[]}, ...args: unknown[]): unknown {
179
179
  const stackBefore = this.stack?.length ?? 0;
180
180
  const result = originalUse.apply(this, args);
181
181
  annotateMountLayers(this.stack, stackBefore, args);