@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
@@ -0,0 +1,593 @@
1
+ import type {Model} from "mongoose";
2
+
3
+ import type {ModelRouterValidationOptions} from "./openApiValidator";
4
+ import type {PopulatePath} from "./populate";
5
+ import type {FieldMask} from "./rbac/types";
6
+
7
+ export const SYSTEM_FIELD_PATHS = new Set(["_id", "id", "__v", "created", "updated", "deleted"]);
8
+
9
+ export type FieldKind =
10
+ | "string"
11
+ | "number"
12
+ | "boolean"
13
+ | "date"
14
+ | "dateOnly"
15
+ | "objectId"
16
+ | "embedded"
17
+ | "mixed"
18
+ | "map";
19
+
20
+ export interface FieldDescription {
21
+ kind: FieldKind;
22
+ required: boolean;
23
+ description?: string;
24
+ enum?: string[];
25
+ ref?: string;
26
+ isArray?: boolean;
27
+ item?: FieldDescription;
28
+ fields?: Record<string, FieldDescription>;
29
+ system?: boolean;
30
+ default?: unknown;
31
+ writableOnCreate?: boolean;
32
+ writableOnUpdate?: boolean;
33
+ }
34
+
35
+ export interface ModelDescription {
36
+ modelName: string;
37
+ fields: Record<string, FieldDescription>;
38
+ }
39
+
40
+ export interface DescribeModelOptions {
41
+ populatePaths?: PopulatePath[];
42
+ extraProperties?: Record<string, FieldDescription>;
43
+ }
44
+
45
+ export interface DescribeModelForRouterOptions extends DescribeModelOptions {
46
+ validation?: boolean | ModelRouterValidationOptions;
47
+ excludeFields?: string[];
48
+ fieldView?: FieldMask;
49
+ }
50
+
51
+ interface MongooseSchemaPath {
52
+ $__schemaType?: MongooseSchemaPath;
53
+ caster?: MongooseSchemaPath;
54
+ enumValues?: string[];
55
+ getEmbeddedSchemaType?: () => MongooseSchemaPath | undefined;
56
+ instance?: string;
57
+ isRequired?: boolean;
58
+ options?: {
59
+ default?: unknown;
60
+ description?: string;
61
+ enum?: string[];
62
+ of?: unknown;
63
+ ref?: string;
64
+ type?: unknown;
65
+ };
66
+ schema?: {
67
+ paths: Record<string, unknown>;
68
+ };
69
+ }
70
+
71
+ const isSystemField = (path: string): boolean => SYSTEM_FIELD_PATHS.has(path);
72
+
73
+ const isMapWildcardPath = (path: string): boolean => path === "$*" || path.endsWith(".$*");
74
+
75
+ const normalizeKind = (instance: string | undefined): FieldKind => {
76
+ switch (instance) {
77
+ case "String":
78
+ return "string";
79
+ case "Number":
80
+ return "number";
81
+ case "Boolean":
82
+ return "boolean";
83
+ case "Date":
84
+ return "date";
85
+ case "DateOnly":
86
+ return "dateOnly";
87
+ case "ObjectId":
88
+ case "ObjectID":
89
+ case "SchemaObjectId":
90
+ return "objectId";
91
+ case "Mixed":
92
+ return "mixed";
93
+ case "Map":
94
+ return "map";
95
+ case "Embedded":
96
+ return "embedded";
97
+ default:
98
+ return "mixed";
99
+ }
100
+ };
101
+
102
+ const getNestedValueSchemaPath = (
103
+ schemaPath: MongooseSchemaPath
104
+ ): MongooseSchemaPath | undefined => {
105
+ if (typeof schemaPath.getEmbeddedSchemaType === "function") {
106
+ const embedded = schemaPath.getEmbeddedSchemaType();
107
+ if (embedded) {
108
+ return embedded;
109
+ }
110
+ }
111
+ return schemaPath.$__schemaType ?? schemaPath.caster;
112
+ };
113
+
114
+ const describeEmbeddedSchema = (
115
+ embeddedSchema: {paths: Record<string, unknown>} | undefined
116
+ ): Record<string, FieldDescription> | undefined => {
117
+ if (!embeddedSchema?.paths) {
118
+ return undefined;
119
+ }
120
+
121
+ const fields: Record<string, FieldDescription> = {};
122
+ for (const [path, rawSchemaPath] of Object.entries(embeddedSchema.paths)) {
123
+ if (isMapWildcardPath(path)) {
124
+ continue;
125
+ }
126
+ fields[path] = describeSchemaPath(path, rawSchemaPath as MongooseSchemaPath);
127
+ }
128
+ return nestDottedFieldDescriptions(fields);
129
+ };
130
+
131
+ const describeCaster = (caster: MongooseSchemaPath): FieldDescription => {
132
+ const kind = normalizeKind(caster.instance);
133
+ const enumValues = caster.enumValues?.length
134
+ ? (caster.enumValues as string[])
135
+ : caster.options?.enum;
136
+
137
+ return {
138
+ description: caster.options?.description,
139
+ enum: enumValues?.length ? enumValues : undefined,
140
+ kind,
141
+ ref: caster.options?.ref,
142
+ required: false,
143
+ };
144
+ };
145
+
146
+ const describeSchemaPath = (path: string, schemaPath: MongooseSchemaPath): FieldDescription => {
147
+ const enumValues = schemaPath.enumValues?.length
148
+ ? (schemaPath.enumValues as string[])
149
+ : schemaPath.options?.enum;
150
+ const base: FieldDescription = {
151
+ default: schemaPath.options?.default,
152
+ description: schemaPath.options?.description,
153
+ enum: enumValues?.length ? enumValues : undefined,
154
+ kind: normalizeKind(schemaPath.instance),
155
+ ref: schemaPath.options?.ref,
156
+ required: Boolean(schemaPath.isRequired),
157
+ system: isSystemField(path),
158
+ };
159
+
160
+ if (schemaPath.instance === "Array") {
161
+ if (schemaPath.schema) {
162
+ const nestedFields = describeEmbeddedSchema(schemaPath.schema);
163
+ return {
164
+ ...base,
165
+ fields: nestedFields,
166
+ isArray: true,
167
+ item: {
168
+ fields: nestedFields,
169
+ kind: "embedded",
170
+ required: false,
171
+ },
172
+ kind: "embedded",
173
+ };
174
+ }
175
+
176
+ const itemSchemaPath = getNestedValueSchemaPath(schemaPath);
177
+ if (itemSchemaPath) {
178
+ const item = describeCaster(itemSchemaPath);
179
+ return {
180
+ ...base,
181
+ isArray: true,
182
+ item,
183
+ kind: item.kind,
184
+ };
185
+ }
186
+
187
+ return {
188
+ ...base,
189
+ isArray: true,
190
+ item: {kind: "mixed", required: false},
191
+ kind: "mixed",
192
+ };
193
+ }
194
+
195
+ if (schemaPath.instance === "Embedded" && schemaPath.schema) {
196
+ const fields = describeEmbeddedSchema(schemaPath.schema);
197
+ return {
198
+ ...base,
199
+ fields,
200
+ kind: "embedded",
201
+ };
202
+ }
203
+
204
+ if (schemaPath.instance === "Map") {
205
+ const valueSchemaPath = getNestedValueSchemaPath(schemaPath);
206
+ return {
207
+ ...base,
208
+ item: valueSchemaPath ? describeCaster(valueSchemaPath) : {kind: "mixed", required: false},
209
+ kind: "map",
210
+ };
211
+ }
212
+
213
+ return base;
214
+ };
215
+
216
+ export const nestDottedFieldDescriptions = (
217
+ fields: Record<string, FieldDescription>
218
+ ): Record<string, FieldDescription> => {
219
+ const root: Record<string, FieldDescription> = {};
220
+
221
+ for (const [path, field] of Object.entries(fields)) {
222
+ if (!path.includes(".")) {
223
+ root[path] = field;
224
+ continue;
225
+ }
226
+
227
+ const parts = path.split(".");
228
+ let current = root;
229
+ for (let index = 0; index < parts.length - 1; index++) {
230
+ const part = parts[index];
231
+ if (!current[part]) {
232
+ current[part] = {
233
+ fields: {},
234
+ kind: "embedded",
235
+ required: false,
236
+ };
237
+ }
238
+ if (!current[part].fields) {
239
+ current[part].fields = {};
240
+ }
241
+ current = current[part].fields as Record<string, FieldDescription>;
242
+ }
243
+
244
+ current[parts[parts.length - 1]] = field;
245
+ }
246
+
247
+ return root;
248
+ };
249
+
250
+ const isWritePathAllowed = (path: string, write: string[] | "*"): boolean => {
251
+ if (write === "*") {
252
+ return true;
253
+ }
254
+ return write.some((allowed) => path === allowed || path.startsWith(`${allowed}.`));
255
+ };
256
+
257
+ const applyWriteMasks = (
258
+ fields: Record<string, FieldDescription>,
259
+ options: DescribeModelForRouterOptions
260
+ ): Record<string, FieldDescription> => {
261
+ const validation =
262
+ typeof options.validation === "object" && options.validation !== null
263
+ ? options.validation
264
+ : undefined;
265
+ const excludeFromCreate = new Set(validation?.excludeFromCreate ?? []);
266
+ const excludeFromUpdate = new Set(validation?.excludeFromUpdate ?? []);
267
+ const excludeFields = new Set(options.excludeFields ?? []);
268
+ const fieldView = options.fieldView;
269
+
270
+ const withMasks = (path: string, field: FieldDescription): FieldDescription => {
271
+ const writableOnCreate =
272
+ !field.system &&
273
+ !excludeFields.has(path) &&
274
+ !excludeFromCreate.has(path) &&
275
+ (!fieldView || isWritePathAllowed(path, fieldView.write));
276
+ const writableOnUpdate =
277
+ !field.system &&
278
+ !excludeFields.has(path) &&
279
+ !excludeFromUpdate.has(path) &&
280
+ (!fieldView || isWritePathAllowed(path, fieldView.write));
281
+
282
+ const next: FieldDescription = {
283
+ ...field,
284
+ writableOnCreate,
285
+ writableOnUpdate,
286
+ };
287
+
288
+ if (field.fields) {
289
+ next.fields = Object.fromEntries(
290
+ Object.entries(field.fields).map(([nestedPath, nestedField]) => [
291
+ nestedPath,
292
+ withMasks(`${path}.${nestedPath}`, nestedField),
293
+ ])
294
+ );
295
+ }
296
+
297
+ if (field.item?.fields) {
298
+ next.item = {
299
+ ...field.item,
300
+ fields: Object.fromEntries(
301
+ Object.entries(field.item.fields).map(([nestedPath, nestedField]) => [
302
+ nestedPath,
303
+ withMasks(`${path}.${nestedPath}`, nestedField),
304
+ ])
305
+ ),
306
+ };
307
+ }
308
+
309
+ return next;
310
+ };
311
+
312
+ return Object.fromEntries(
313
+ Object.entries(fields).map(([path, field]) => [path, withMasks(path, field)])
314
+ );
315
+ };
316
+
317
+ export const describeModel = <T>(
318
+ model: Model<T>,
319
+ options: DescribeModelOptions = {}
320
+ ): ModelDescription => {
321
+ const fields: Record<string, FieldDescription> = {};
322
+
323
+ for (const [path, rawSchemaPath] of Object.entries(model.schema.paths)) {
324
+ if (isMapWildcardPath(path)) {
325
+ continue;
326
+ }
327
+ fields[path] = describeSchemaPath(path, rawSchemaPath as unknown as MongooseSchemaPath);
328
+ }
329
+
330
+ if (options.extraProperties) {
331
+ for (const [path, field] of Object.entries(options.extraProperties)) {
332
+ fields[path] = field;
333
+ }
334
+ }
335
+
336
+ return {
337
+ fields,
338
+ modelName: model.modelName,
339
+ };
340
+ };
341
+
342
+ export const describeModelForRouter = <T>(
343
+ model: Model<T>,
344
+ options: DescribeModelForRouterOptions = {}
345
+ ): ModelDescription => {
346
+ const description = describeModel(model, options);
347
+ return {
348
+ ...description,
349
+ fields: applyWriteMasks(description.fields, options),
350
+ };
351
+ };
352
+
353
+ export const fieldDescriptionToOpenApiProperty = (
354
+ field: FieldDescription
355
+ ): Record<string, unknown> => {
356
+ if (field.isArray) {
357
+ const items = field.item
358
+ ? fieldDescriptionToOpenApiProperty({...field.item, isArray: false})
359
+ : {type: "string"};
360
+ const property: Record<string, unknown> = {
361
+ description: field.description,
362
+ items,
363
+ type: "array",
364
+ };
365
+ if (field.enum) {
366
+ property.enum = field.enum;
367
+ }
368
+ return property;
369
+ }
370
+
371
+ if (field.kind === "embedded" && field.fields) {
372
+ const nested = modelDescriptionToOpenApiSpec({fields: field.fields, modelName: ""});
373
+ const property: Record<string, unknown> = {
374
+ properties: nested.properties,
375
+ type: "object",
376
+ };
377
+ if (field.description) {
378
+ property.description = field.description;
379
+ }
380
+ property.required = nested.required.length ? nested.required : [];
381
+ return property;
382
+ }
383
+
384
+ if (field.kind === "mixed") {
385
+ return {description: field.description};
386
+ }
387
+
388
+ if (field.kind === "map") {
389
+ const property: Record<string, unknown> = {
390
+ additionalProperties: field.item
391
+ ? fieldDescriptionToOpenApiProperty({...field.item, isArray: false})
392
+ : {type: "string"},
393
+ type: "object",
394
+ };
395
+ if (field.description) {
396
+ property.description = field.description;
397
+ }
398
+ return property;
399
+ }
400
+
401
+ if (field.kind === "dateOnly") {
402
+ return {
403
+ description: field.description,
404
+ type: "dateonly",
405
+ };
406
+ }
407
+
408
+ const openApiType =
409
+ field.kind === "objectId" ? "string" : field.kind === "date" ? "string" : field.kind;
410
+ const property: Record<string, unknown> = {
411
+ type: openApiType,
412
+ };
413
+ if (field.description) {
414
+ property.description = field.description;
415
+ }
416
+ if (field.enum) {
417
+ property.enum = field.enum;
418
+ }
419
+ if (field.kind === "objectId" && !field.system) {
420
+ property.format = "objectid";
421
+ }
422
+ if (field.kind === "date") {
423
+ property.format = "date-time";
424
+ }
425
+ return property;
426
+ };
427
+
428
+ export const modelDescriptionToOpenApiSpec = (
429
+ description: ModelDescription
430
+ ): {properties: Record<string, unknown>; required: string[]} => {
431
+ const nestedFields = nestDottedFieldDescriptions(description.fields);
432
+ const properties: Record<string, unknown> = {};
433
+ const required: string[] = [];
434
+
435
+ for (const [path, field] of Object.entries(nestedFields)) {
436
+ // mongoose-to-swagger omits __v from OpenAPI components; keep parity for HTTP bodies.
437
+ if (path === "__v") {
438
+ continue;
439
+ }
440
+ properties[path] = fieldDescriptionToOpenApiProperty(field);
441
+ if (field.required) {
442
+ required.push(path);
443
+ }
444
+ }
445
+
446
+ return {properties, required};
447
+ };
448
+
449
+ export const fieldDescriptionToAdminMeta = (
450
+ field: FieldDescription
451
+ ): {
452
+ default?: unknown;
453
+ description?: string;
454
+ enum?: string[];
455
+ itemEnum?: string[];
456
+ itemRef?: string;
457
+ itemType?: string;
458
+ items?: Record<string, ReturnType<typeof fieldDescriptionToAdminMeta>>;
459
+ ref?: string;
460
+ required: boolean;
461
+ searchable?: boolean;
462
+ type: string;
463
+ } => {
464
+ const adminType = field.isArray
465
+ ? "array"
466
+ : field.kind === "objectId"
467
+ ? "objectid"
468
+ : field.kind === "embedded"
469
+ ? "object"
470
+ : field.kind === "mixed"
471
+ ? "mixed"
472
+ : field.kind === "map"
473
+ ? "object"
474
+ : field.kind === "dateOnly"
475
+ ? "dateonly"
476
+ : field.kind;
477
+
478
+ const meta: ReturnType<typeof fieldDescriptionToAdminMeta> = {
479
+ default: field.default,
480
+ description: field.description,
481
+ enum: field.enum,
482
+ ref: field.ref,
483
+ required: field.required,
484
+ searchable: adminType === "string" && !field.enum,
485
+ type: adminType,
486
+ };
487
+
488
+ if (field.isArray && field.item) {
489
+ if (field.item.ref) {
490
+ meta.ref = field.item.ref;
491
+ }
492
+ if (field.item.fields) {
493
+ meta.items = Object.fromEntries(
494
+ Object.entries(field.item.fields).map(([key, nestedField]) => [
495
+ key,
496
+ fieldDescriptionToAdminMeta(nestedField),
497
+ ])
498
+ );
499
+ } else {
500
+ meta.itemType =
501
+ field.item.kind === "objectId"
502
+ ? "objectid"
503
+ : field.item.kind === "embedded"
504
+ ? "object"
505
+ : field.item.kind;
506
+ meta.itemEnum = field.item.enum;
507
+ meta.itemRef = field.item.ref;
508
+ }
509
+ }
510
+
511
+ if (field.kind === "embedded" && field.fields && !field.isArray) {
512
+ meta.items = Object.fromEntries(
513
+ Object.entries(field.fields).map(([key, nestedField]) => [
514
+ key,
515
+ fieldDescriptionToAdminMeta(nestedField),
516
+ ])
517
+ );
518
+ }
519
+
520
+ return meta;
521
+ };
522
+
523
+ export const modelDescriptionToAdminFields = (
524
+ description: ModelDescription
525
+ ): Record<string, ReturnType<typeof fieldDescriptionToAdminMeta>> => {
526
+ const nestedFields = nestDottedFieldDescriptions(description.fields);
527
+ return Object.fromEntries(
528
+ Object.entries(nestedFields).map(([path, field]) => [path, fieldDescriptionToAdminMeta(field)])
529
+ );
530
+ };
531
+
532
+ export const fieldDescriptionToZodType = (
533
+ field: FieldDescription,
534
+ z: typeof import("zod").z
535
+ ): import("zod").ZodType => {
536
+ let zodType: import("zod").ZodType;
537
+
538
+ if (field.isArray) {
539
+ const itemType = field.item
540
+ ? fieldDescriptionToZodType({...field.item, isArray: false}, z)
541
+ : z.any();
542
+ zodType = z.array(itemType);
543
+ if (field.item?.kind === "embedded") {
544
+ zodType = zodType.describe("Array of subdocuments");
545
+ }
546
+ if (field.description) {
547
+ zodType = zodType.describe(field.description);
548
+ }
549
+ return zodType;
550
+ }
551
+
552
+ if (field.kind === "embedded" && field.fields) {
553
+ zodType = z.record(z.string(), z.any()).describe("Embedded document");
554
+ if (field.description) {
555
+ zodType = zodType.describe(field.description);
556
+ }
557
+ return zodType;
558
+ }
559
+
560
+ switch (field.kind) {
561
+ case "string":
562
+ zodType =
563
+ field.enum && field.enum.length > 0
564
+ ? z.enum(field.enum as [string, ...string[]])
565
+ : z.string();
566
+ break;
567
+ case "number":
568
+ zodType = z.number();
569
+ break;
570
+ case "boolean":
571
+ zodType = z.boolean();
572
+ break;
573
+ case "date":
574
+ case "dateOnly":
575
+ zodType = z.string().describe("ISO 8601 date string");
576
+ break;
577
+ case "objectId":
578
+ zodType = z.string().describe(field.ref ? `ObjectId reference to ${field.ref}` : "ObjectId");
579
+ break;
580
+ case "map":
581
+ zodType = z.record(z.string(), z.any());
582
+ break;
583
+ default:
584
+ zodType = z.record(z.string(), z.any());
585
+ break;
586
+ }
587
+
588
+ if (field.description) {
589
+ zodType = zodType.describe(field.description);
590
+ }
591
+
592
+ return zodType;
593
+ };
@@ -92,6 +92,74 @@ describe("scrubAdminFields", () => {
92
92
 
93
93
  expect(result.ownerId.hash).toBe("keep");
94
94
  });
95
+
96
+ it("returns null and undefined unchanged", () => {
97
+ expect(scrubAdminFields(null, {admin: todoAdmin})).toBeNull();
98
+ expect(scrubAdminFields(undefined, {admin: todoAdmin})).toBeUndefined();
99
+ });
100
+
101
+ it("returns primitives unchanged", () => {
102
+ expect(scrubAdminFields("Buy milk", {admin: todoAdmin})).toBe("Buy milk");
103
+ expect(scrubAdminFields(7, {admin: todoAdmin})).toBe(7);
104
+ expect(scrubAdminFields(false, {admin: todoAdmin})).toBe(false);
105
+ });
106
+
107
+ it("keeps null and undefined field values", () => {
108
+ const result = scrubAdminFields(
109
+ {completed: null, secret: "x", title: undefined},
110
+ {admin: todoAdmin}
111
+ );
112
+ expect(result).toEqual({completed: null, title: undefined});
113
+ });
114
+
115
+ it("converts mongoose documents with toObject before scrubbing", () => {
116
+ const doc = new Todo({title: "Task"});
117
+ const result = scrubAdminFields(doc, {admin: todoAdmin}) as Record<string, unknown>;
118
+
119
+ expect(result.title).toBe("Task");
120
+ expect(result._id).toBeDefined();
121
+ });
122
+
123
+ it("scrubs each element of an array field", () => {
124
+ const result = scrubAdminFields(
125
+ {items: [{secret: "s", title: "a"}, "plain", 3], title: "Parent"},
126
+ {admin: todoAdmin}
127
+ ) as {items: unknown[]; title: string};
128
+
129
+ expect(result.title).toBe("Parent");
130
+ expect(result.items).toEqual([{title: "a"}, "plain", 3]);
131
+ });
132
+
133
+ it("leaves populated docs on paths without a ref unchanged", () => {
134
+ const admin: AdminConfig = {
135
+ displayName: "Todos",
136
+ listFields: ["title"],
137
+ };
138
+ const result = scrubAdminFields(
139
+ {title: {_id: "507f1f77bcf86cd799439011", hash: "keep"}},
140
+ {admin, allModelAdmins: {ScrubUser: userAdmin}, schema: Todo.schema}
141
+ ) as {title: Record<string, unknown>};
142
+
143
+ expect(result.title.hash).toBe("keep");
144
+ });
145
+
146
+ it("leaves populated docs unchanged when no schema is provided", () => {
147
+ const result = scrubAdminFields(
148
+ {ownerId: {_id: "507f1f77bcf86cd799439011", hash: "keep"}},
149
+ {admin: todoAdmin, allModelAdmins: {ScrubUser: userAdmin}}
150
+ ) as {ownerId: Record<string, unknown>};
151
+
152
+ expect(result.ownerId.hash).toBe("keep");
153
+ });
154
+
155
+ it("leaves unpopulated ref ids unchanged", () => {
156
+ const result = scrubAdminFields(
157
+ {ownerId: {_id: "507f1f77bcf86cd799439011"}, title: "Task"},
158
+ {admin: todoAdmin, allModelAdmins: {ScrubUser: userAdmin}, schema: Todo.schema}
159
+ ) as {ownerId: Record<string, unknown>};
160
+
161
+ expect(result.ownerId).toEqual({_id: "507f1f77bcf86cd799439011"});
162
+ });
95
163
  });
96
164
 
97
165
  describe("stripAdminBodyFields", () => {
@@ -110,4 +178,41 @@ describe("stripAdminBodyFields", () => {
110
178
  );
111
179
  expect(result).toEqual({title: "x"});
112
180
  });
181
+
182
+ it("strips keys from every object in an array body and leaves non-objects alone", () => {
183
+ const result = stripAdminBodyFields(
184
+ [
185
+ {slug: "fixed", title: "a"},
186
+ {internal: "n", title: "b"},
187
+ ] as Record<string, unknown>[],
188
+ admin
189
+ );
190
+ expect(result).toEqual([{title: "a"}, {title: "b"}]);
191
+ });
192
+
193
+ it("returns array entries that are not objects unchanged", () => {
194
+ const body = [null, {role: "admin", title: "a"}] as unknown as Record<string, unknown>[];
195
+ expect(stripAdminBodyFields(body, admin)).toEqual([null, {title: "a"}] as unknown as Record<
196
+ string,
197
+ unknown
198
+ >[]);
199
+ });
200
+
201
+ it("returns null and undefined bodies unchanged", () => {
202
+ expect(stripAdminBodyFields(null, admin)).toBeNull();
203
+ expect(stripAdminBodyFields(undefined, admin)).toBeUndefined();
204
+ });
205
+
206
+ it("returns non-object bodies unchanged", () => {
207
+ const body = "not-an-object" as unknown as Record<string, unknown>;
208
+ expect(stripAdminBodyFields(body, admin)).toBe(body);
209
+ });
210
+
211
+ it("keeps an admin config without any strip lists intact", () => {
212
+ const bareAdmin: AdminConfig = {displayName: "Todos", listFields: ["title"]};
213
+ expect(stripAdminBodyFields({slug: "fixed", title: "x"}, bareAdmin)).toEqual({
214
+ slug: "fixed",
215
+ title: "x",
216
+ });
217
+ });
113
218
  });