@terreno/api 57.3.0 → 57.4.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 (293) hide show
  1. package/.ai/skills/mongoose-schema-safety/SKILL.md +23 -10
  2. package/README.md +6 -0
  3. package/dist/adminTypes.d.ts +7 -0
  4. package/dist/adminTypes.js +6 -1
  5. package/dist/api.d.ts +10 -0
  6. package/dist/api.js +99 -36
  7. package/dist/audit/auditApp.d.ts +30 -0
  8. package/dist/audit/auditApp.js +155 -0
  9. package/dist/audit/auditEventModel.d.ts +29 -0
  10. package/dist/audit/auditEventModel.js +102 -0
  11. package/dist/audit/cloudTasksEnqueue.d.ts +32 -0
  12. package/dist/audit/cloudTasksEnqueue.js +162 -0
  13. package/dist/audit/diff.d.ts +10 -0
  14. package/dist/audit/diff.js +230 -0
  15. package/dist/audit/processQueue.d.ts +6 -0
  16. package/dist/audit/processQueue.js +101 -0
  17. package/dist/audit/rbacSink.d.ts +2 -0
  18. package/dist/audit/rbacSink.js +82 -0
  19. package/dist/audit/record.d.ts +56 -0
  20. package/dist/audit/record.js +373 -0
  21. package/dist/betterAuth.d.ts +6 -0
  22. package/dist/betterAuthSetup.js +1 -1
  23. package/dist/collectionRegistry.d.ts +3 -1
  24. package/dist/collectionRegistry.js +25 -0
  25. package/dist/index.d.ts +26 -1
  26. package/dist/index.js +48 -2
  27. package/dist/mcp/query.d.ts +0 -13
  28. package/dist/mcp/query.js +8 -8
  29. package/dist/migrations/fixtures/all-down/20260910120000-one.d.ts +4 -0
  30. package/dist/migrations/fixtures/all-down/20260910120000-one.js +49 -0
  31. package/dist/migrations/fixtures/all-down/20260910120001-two.d.ts +4 -0
  32. package/dist/migrations/fixtures/all-down/20260910120001-two.js +49 -0
  33. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.d.ts +3 -0
  34. package/dist/migrations/fixtures/bad-id/20260910120000-mismatch.js +45 -0
  35. package/dist/migrations/fixtures/bad-name/not-a-migration.d.ts +3 -0
  36. package/dist/migrations/fixtures/bad-name/not-a-migration.js +45 -0
  37. package/dist/migrations/fixtures/missing-up/20260910120000-noup.d.ts +2 -0
  38. package/dist/migrations/fixtures/missing-up/20260910120000-noup.js +5 -0
  39. package/dist/migrations/fixtures/valid/20260910120000-alpha.d.ts +3 -0
  40. package/dist/migrations/fixtures/valid/20260910120000-alpha.js +45 -0
  41. package/dist/migrations/fixtures/valid/20260910120001-beta.d.ts +4 -0
  42. package/dist/migrations/fixtures/valid/20260910120001-beta.js +49 -0
  43. package/dist/migrations/generate.d.ts +17 -0
  44. package/dist/migrations/generate.js +277 -0
  45. package/dist/migrations/load.d.ts +20 -0
  46. package/dist/migrations/load.js +236 -0
  47. package/dist/migrations/lock.d.ts +13 -0
  48. package/dist/migrations/lock.js +145 -0
  49. package/dist/migrations/runner.d.ts +42 -0
  50. package/dist/migrations/runner.js +503 -0
  51. package/dist/migrations/schemaCatalog.d.ts +44 -0
  52. package/dist/migrations/schemaCatalog.js +326 -0
  53. package/dist/migrations/types.d.ts +87 -0
  54. package/dist/migrations/types.js +7 -0
  55. package/dist/models/notification.d.ts +2 -0
  56. package/dist/models/notification.js +62 -0
  57. package/dist/models/notificationPreference.d.ts +2 -0
  58. package/dist/models/notificationPreference.js +49 -0
  59. package/dist/notifications/notificationService.d.ts +40 -0
  60. package/dist/notifications/notificationService.js +323 -0
  61. package/dist/notifications/notificationsApp.d.ts +18 -0
  62. package/dist/notifications/notificationsApp.js +250 -0
  63. package/dist/notifications/notificationsBeforeSend.d.ts +14 -0
  64. package/dist/notifications/notificationsBeforeSend.js +77 -0
  65. package/dist/openApi.d.ts +1 -7
  66. package/dist/openApi.js +7 -6
  67. package/dist/openApiBuilder.d.ts +14 -3
  68. package/dist/openApiValidator.d.ts +13 -1
  69. package/dist/openApiValidator.js +200 -36
  70. package/dist/orgs/orgContext.d.ts +23 -0
  71. package/dist/orgs/orgContext.js +198 -0
  72. package/dist/orgs/orgPermissions.d.ts +4 -0
  73. package/dist/orgs/orgPermissions.js +77 -0
  74. package/dist/orgs/orgPlugin.d.ts +13 -0
  75. package/dist/orgs/orgPlugin.js +84 -0
  76. package/dist/orgs/organizationModel.d.ts +13 -0
  77. package/dist/orgs/organizationModel.js +301 -0
  78. package/dist/orgs/organizationSettings.d.ts +19 -0
  79. package/dist/orgs/organizationSettings.js +120 -0
  80. package/dist/orgs/orgsApp.d.ts +28 -0
  81. package/dist/orgs/orgsApp.js +678 -0
  82. package/dist/permissions.d.ts +7 -13
  83. package/dist/permissions.js +8 -31
  84. package/dist/rateLimit/middleware.d.ts +0 -8
  85. package/dist/rateLimit/middleware.js +2 -3
  86. package/dist/rateLimit/mongoStore.d.ts +1 -0
  87. package/dist/rateLimit/mongoStore.js +1 -0
  88. package/dist/rateLimit/policies.d.ts +0 -4
  89. package/dist/rateLimit/policies.js +5 -7
  90. package/dist/rateLimit/redisStore.d.ts +1 -0
  91. package/dist/rateLimit/redisStore.js +1 -0
  92. package/dist/rbac/access.js +30 -13
  93. package/dist/rbac/membershipOrgAdminSource.d.ts +6 -0
  94. package/dist/rbac/membershipOrgAdminSource.js +122 -0
  95. package/dist/rbac/modelRouterAccess.d.ts +3 -0
  96. package/dist/rbac/modelRouterAccess.js +3 -0
  97. package/dist/rbac/resolve.js +60 -31
  98. package/dist/rbac/roleModel.d.ts +2 -5
  99. package/dist/rbac/roleModel.js +18 -4
  100. package/dist/rbac/statements.d.ts +10 -1
  101. package/dist/rbac/statements.js +19 -2
  102. package/dist/rbac/types.d.ts +5 -0
  103. package/dist/realtime/changeStreamWatcher.d.ts +10 -4
  104. package/dist/realtime/changeStreamWatcher.js +110 -64
  105. package/dist/realtime/deprecation.d.ts +1 -0
  106. package/dist/realtime/deprecation.js +1 -0
  107. package/dist/realtime/realtimeApp.d.ts +1 -0
  108. package/dist/realtime/realtimeApp.js +1 -0
  109. package/dist/schemaMetadata.js +16 -5
  110. package/dist/sync/adminBroadcastScope.d.ts +40 -0
  111. package/dist/sync/adminBroadcastScope.js +194 -0
  112. package/dist/sync/adminWindowAccess.d.ts +13 -0
  113. package/dist/sync/adminWindowAccess.js +96 -0
  114. package/dist/sync/adminWindowMutation.d.ts +88 -0
  115. package/dist/sync/adminWindowMutation.js +247 -0
  116. package/dist/sync/executors.d.ts +9 -3
  117. package/dist/sync/executors.js +190 -159
  118. package/dist/sync/mutationHandler.d.ts +5 -2
  119. package/dist/sync/mutationHandler.js +191 -71
  120. package/dist/sync/registry.js +4 -0
  121. package/dist/sync/routes.d.ts +13 -0
  122. package/dist/sync/routes.js +113 -56
  123. package/dist/sync/socketHandlers.d.ts +8 -2
  124. package/dist/sync/socketHandlers.js +144 -50
  125. package/dist/sync/streams.d.ts +2 -0
  126. package/dist/sync/streams.js +7 -1
  127. package/dist/sync/syncApp.d.ts +2 -1
  128. package/dist/sync/syncApp.js +2 -1
  129. package/dist/sync/syncBatch.d.ts +5 -2
  130. package/dist/sync/syncBatch.js +4 -4
  131. package/dist/sync/types.d.ts +18 -0
  132. package/dist/terrenoApp.d.ts +29 -0
  133. package/dist/terrenoApp.js +91 -54
  134. package/dist/tests/createTestData.d.ts +1 -3
  135. package/dist/tests/createTestData.js +3 -5
  136. package/dist/tests/models.d.ts +1 -0
  137. package/dist/tests/models.js +9 -2
  138. package/dist/tests/testHelper.d.ts +0 -5
  139. package/dist/tests/testHelper.js +2 -9
  140. package/dist/types/authToken.d.ts +3 -3
  141. package/dist/types/mcpServiceToken.d.ts +2 -2
  142. package/dist/types/membership.d.ts +23 -0
  143. package/dist/types/membership.js +2 -0
  144. package/dist/types/notification.d.ts +28 -0
  145. package/dist/types/notification.js +2 -0
  146. package/dist/types/notificationPreference.d.ts +20 -0
  147. package/dist/types/notificationPreference.js +2 -0
  148. package/dist/types/organization.d.ts +36 -0
  149. package/dist/types/organization.js +2 -0
  150. package/dist/webhooks/idempotency/webhookReceipt.d.ts +4 -49
  151. package/dist/webhooks/idempotency/webhookReceipt.js +7 -7
  152. package/dist/webhooks/rawBody.d.ts +1 -0
  153. package/dist/webhooks/rawBody.js +1 -0
  154. package/package.json +31 -25
  155. package/src/__snapshots__/openApi.test.ts.snap +192 -54
  156. package/src/__snapshots__/openApiBuilder.test.ts.snap +0 -18
  157. package/src/__snapshots__/schemaMetadata.test.ts.snap +0 -1
  158. package/src/adminTypes.ts +8 -0
  159. package/src/api.test.ts +39 -2
  160. package/src/api.ts +68 -0
  161. package/src/audit/auditApp.test.ts +243 -0
  162. package/src/audit/auditApp.ts +139 -0
  163. package/src/audit/auditEventModel.ts +156 -0
  164. package/src/audit/auditRouter.test.ts +456 -0
  165. package/src/audit/cloudTasksEnqueue.test.ts +124 -0
  166. package/src/audit/cloudTasksEnqueue.ts +104 -0
  167. package/src/audit/diff.ts +163 -0
  168. package/src/audit/processQueue.ts +69 -0
  169. package/src/audit/rbacSink.test.ts +86 -0
  170. package/src/audit/rbacSink.ts +42 -0
  171. package/src/audit/record.test.ts +402 -0
  172. package/src/audit/record.ts +328 -0
  173. package/src/auth.test.ts +1 -1
  174. package/src/betterAuth.ts +7 -0
  175. package/src/betterAuthSetup.test.ts +27 -0
  176. package/src/betterAuthSetup.ts +1 -0
  177. package/src/collectionRegistry.test.ts +8 -9
  178. package/src/collectionRegistry.ts +21 -1
  179. package/src/express.d.ts +2 -0
  180. package/src/expressServer.test.ts +50 -2
  181. package/src/index.ts +69 -0
  182. package/src/mcp/handlers.test.ts +275 -0
  183. package/src/mcp/query.ts +3 -3
  184. package/src/mcp/toolGenerator.test.ts +81 -0
  185. package/src/migrations/cli.test.ts +376 -0
  186. package/src/migrations/cli.ts +283 -0
  187. package/src/migrations/fixtures/all-down/20260910120000-one.ts +6 -0
  188. package/src/migrations/fixtures/all-down/20260910120001-two.ts +6 -0
  189. package/src/migrations/fixtures/bad-id/20260910120000-mismatch.ts +4 -0
  190. package/src/migrations/fixtures/bad-name/not-a-migration.ts +4 -0
  191. package/src/migrations/fixtures/missing-up/20260910120000-noup.ts +2 -0
  192. package/src/migrations/fixtures/valid/20260910120000-alpha.ts +4 -0
  193. package/src/migrations/fixtures/valid/20260910120001-beta.ts +6 -0
  194. package/src/migrations/generate.test.ts +333 -0
  195. package/src/migrations/generate.ts +216 -0
  196. package/src/migrations/load.test.ts +103 -0
  197. package/src/migrations/load.ts +124 -0
  198. package/src/migrations/lock.test.ts +133 -0
  199. package/src/migrations/lock.ts +118 -0
  200. package/src/migrations/runner.test.ts +504 -0
  201. package/src/migrations/runner.ts +358 -0
  202. package/src/migrations/schemaCatalog.test.ts +159 -0
  203. package/src/migrations/schemaCatalog.ts +262 -0
  204. package/src/migrations/types.ts +94 -0
  205. package/src/models/notification.ts +68 -0
  206. package/src/models/notificationPreference.ts +62 -0
  207. package/src/notifications/notificationService.ts +254 -0
  208. package/src/notifications/notificationsApp.test.ts +505 -0
  209. package/src/notifications/notificationsApp.ts +200 -0
  210. package/src/notifications/notificationsBeforeSend.ts +51 -0
  211. package/src/openApi.test.ts +0 -1
  212. package/src/openApi.ts +2 -1
  213. package/src/openApiBuilder.ts +14 -3
  214. package/src/openApiValidator.test.ts +221 -2
  215. package/src/openApiValidator.ts +218 -33
  216. package/src/orgs/orgAccessOptIn.test.ts +87 -0
  217. package/src/orgs/orgContext.test.ts +259 -0
  218. package/src/orgs/orgContext.ts +151 -0
  219. package/src/orgs/orgPermissions.test.ts +105 -0
  220. package/src/orgs/orgPermissions.ts +40 -0
  221. package/src/orgs/orgPlugin.test.ts +130 -0
  222. package/src/orgs/orgPlugin.ts +70 -0
  223. package/src/orgs/orgRbac.test.ts +267 -0
  224. package/src/orgs/orgSecurityDefects.test.ts +415 -0
  225. package/src/orgs/organizationModel.test.ts +205 -0
  226. package/src/orgs/organizationModel.ts +257 -0
  227. package/src/orgs/organizationSettings.test.ts +113 -0
  228. package/src/orgs/organizationSettings.ts +126 -0
  229. package/src/orgs/orgsApp.test.ts +382 -0
  230. package/src/orgs/orgsApp.ts +563 -0
  231. package/src/permissions.test.ts +62 -36
  232. package/src/permissions.ts +8 -30
  233. package/src/rateLimit/middleware.ts +1 -1
  234. package/src/rateLimit/mongoStore.ts +1 -0
  235. package/src/rateLimit/policies.ts +2 -2
  236. package/src/rateLimit/redisStore.ts +1 -0
  237. package/src/rbac/access.ts +11 -3
  238. package/src/rbac/membershipOrgAdminSource.ts +59 -0
  239. package/src/rbac/modelRouterAccess.ts +3 -0
  240. package/src/rbac/permissionUtils.test.ts +26 -5
  241. package/src/rbac/resolve.test.ts +34 -2
  242. package/src/rbac/resolve.ts +26 -7
  243. package/src/rbac/roleModel.test.ts +34 -1
  244. package/src/rbac/roleModel.ts +17 -1
  245. package/src/rbac/statements.test.ts +19 -0
  246. package/src/rbac/statements.ts +19 -1
  247. package/src/rbac/types.ts +5 -0
  248. package/src/realtime/changeStreamWatcher.ts +73 -33
  249. package/src/realtime/deprecation.ts +1 -0
  250. package/src/realtime/realtime.test.ts +357 -185
  251. package/src/realtime/realtimeApp.ts +1 -0
  252. package/src/schemaMetadata.test.ts +14 -0
  253. package/src/schemaMetadata.ts +5 -5
  254. package/src/sync/adminBroadcastConfig.test.ts +96 -0
  255. package/src/sync/adminBroadcastScope.test.ts +155 -0
  256. package/src/sync/adminBroadcastScope.ts +123 -0
  257. package/src/sync/adminWindowAccess.test.ts +57 -0
  258. package/src/sync/adminWindowAccess.ts +32 -0
  259. package/src/sync/adminWindowMutation.test.ts +450 -0
  260. package/src/sync/adminWindowMutation.ts +283 -0
  261. package/src/sync/executors.ts +33 -6
  262. package/src/sync/mutationHandler.test.ts +277 -1
  263. package/src/sync/mutationHandler.ts +171 -29
  264. package/src/sync/registry.ts +4 -0
  265. package/src/sync/routes.ts +52 -8
  266. package/src/sync/socketHandlers.ts +154 -58
  267. package/src/sync/streams.ts +6 -0
  268. package/src/sync/sync.test.ts +3 -2
  269. package/src/sync/syncApp.ts +2 -1
  270. package/src/sync/syncBatch.ts +7 -2
  271. package/src/sync/syncRoutes.test.ts +297 -3
  272. package/src/sync/syncSocket.test.ts +229 -0
  273. package/src/sync/types.ts +20 -0
  274. package/src/terrenoApp.migrations.test.ts +114 -0
  275. package/src/terrenoApp.test.ts +41 -0
  276. package/src/terrenoApp.ts +94 -31
  277. package/src/tests/createTestData.ts +2 -2
  278. package/src/tests/models.ts +10 -2
  279. package/src/tests/testHelper.ts +1 -7
  280. package/src/types/authToken.ts +2 -4
  281. package/src/types/mcpServiceToken.ts +1 -7
  282. package/src/types/membership.ts +48 -0
  283. package/src/types/notification.ts +34 -0
  284. package/src/types/notificationPreference.ts +28 -0
  285. package/src/types/organization.ts +49 -0
  286. package/src/webhooks/idempotency/webhookReceipt.ts +4 -7
  287. package/src/webhooks/rawBody.test.ts +33 -0
  288. package/src/webhooks/rawBody.ts +1 -0
  289. package/tsconfig.json +1 -1
  290. package/tsconfig.typedoc.json +2 -1
  291. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.d.ts +0 -2
  292. package/dist/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
  293. package/src/vendor/wesleytodd-openapi/lib/convert-yaml.js +0 -13
@@ -0,0 +1,257 @@
1
+ import mongoose from "mongoose";
2
+
3
+ import {APIError, ConflictError} from "../errors";
4
+ import {createdUpdatedPlugin, findExactlyOne, findOneOrNone, isDeletedPlugin} from "../plugins";
5
+ import type {MembershipDocument, MembershipModel} from "../types/membership";
6
+ import type {OrganizationDocument, OrganizationModel} from "../types/organization";
7
+ import {applyOrganizationSettings} from "./organizationSettings";
8
+
9
+ export type {
10
+ MembershipDocument,
11
+ MembershipMethods,
12
+ MembershipModel,
13
+ MembershipRoleName,
14
+ MembershipSchema,
15
+ MembershipStatics,
16
+ MembershipStatus,
17
+ } from "../types/membership";
18
+ export type {
19
+ OrganizationDocument,
20
+ OrganizationMethods,
21
+ OrganizationModel,
22
+ OrganizationSchema,
23
+ OrganizationSettings,
24
+ OrganizationStatics,
25
+ } from "../types/organization";
26
+
27
+ const MEMBERSHIP_ROLE_NAMES = ["org-admin", "member"] as const;
28
+ const MEMBERSHIP_STATUSES = ["active", "suspended"] as const;
29
+
30
+ const toObjectId = (value: mongoose.Types.ObjectId | string): mongoose.Types.ObjectId => {
31
+ if (value instanceof mongoose.Types.ObjectId) {
32
+ return value;
33
+ }
34
+ return new mongoose.Types.ObjectId(value);
35
+ };
36
+
37
+ export const assertOrganizationSlugAvailable = async (
38
+ slug: string,
39
+ excludeOrganizationId?: mongoose.Types.ObjectId
40
+ ): Promise<void> => {
41
+ const query: {
42
+ _id?: {$ne: mongoose.Types.ObjectId};
43
+ deleted: {$in: boolean[]};
44
+ slug: string;
45
+ } = {deleted: {$in: [true, false]}, slug};
46
+ if (excludeOrganizationId) {
47
+ query._id = {$ne: excludeOrganizationId};
48
+ }
49
+ const existing = await Organization.findOneOrNone(query);
50
+ if (existing) {
51
+ throw new ConflictError("Organization name already in use");
52
+ }
53
+ };
54
+
55
+ export const organizationSlugFromName = (name: string): string => {
56
+ const slug = name
57
+ .trim()
58
+ .toLowerCase()
59
+ .replace(/[^a-z0-9]+/g, "-")
60
+ .replace(/^-+|-+$/g, "");
61
+ if (!slug) {
62
+ throw new APIError({
63
+ status: 400,
64
+ title: "Organization name must produce a slug",
65
+ });
66
+ }
67
+ return slug;
68
+ };
69
+
70
+ const organizationSchema = new mongoose.Schema<OrganizationDocument, OrganizationModel>(
71
+ {
72
+ disabled: {
73
+ default: false,
74
+ description: "Whether operators have disabled this organization",
75
+ type: Boolean,
76
+ },
77
+ name: {
78
+ description: "Human-readable organization name",
79
+ required: true,
80
+ trim: true,
81
+ type: String,
82
+ },
83
+ ownerId: {
84
+ description: "User who created the organization; transferable",
85
+ ref: "User",
86
+ required: true,
87
+ type: mongoose.Schema.Types.ObjectId,
88
+ },
89
+ settings: {
90
+ description: "App-defined organization settings object",
91
+ type: mongoose.Schema.Types.Mixed,
92
+ },
93
+ slug: {
94
+ description: "URL-safe unique identifier generated from the organization name",
95
+ required: true,
96
+ trim: true,
97
+ type: String,
98
+ unique: true,
99
+ },
100
+ },
101
+ {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
102
+ );
103
+
104
+ organizationSchema.plugin(createdUpdatedPlugin);
105
+ organizationSchema.plugin(isDeletedPlugin);
106
+ organizationSchema.plugin(findOneOrNone);
107
+ organizationSchema.plugin(findExactlyOne);
108
+
109
+ organizationSchema.pre("validate", function (this: OrganizationDocument): void {
110
+ if (!this.slug) {
111
+ this.slug = organizationSlugFromName(this.name);
112
+ }
113
+ if (!this.isModified("settings")) {
114
+ return;
115
+ }
116
+ this.settings = applyOrganizationSettings(this.settings);
117
+ });
118
+
119
+ const membershipSchema = new mongoose.Schema<MembershipDocument, MembershipModel>(
120
+ {
121
+ organizationId: {
122
+ description: "Organization this membership belongs to",
123
+ index: true,
124
+ ref: "Organization",
125
+ required: true,
126
+ type: mongoose.Schema.Types.ObjectId,
127
+ },
128
+ roleName: {
129
+ default: "member",
130
+ description: "Per-organization role: org-admin or member",
131
+ enum: MEMBERSHIP_ROLE_NAMES,
132
+ required: true,
133
+ type: String,
134
+ },
135
+ status: {
136
+ default: "active",
137
+ description: "Whether this membership is active or suspended",
138
+ enum: MEMBERSHIP_STATUSES,
139
+ required: true,
140
+ type: String,
141
+ },
142
+ userId: {
143
+ description: "User who holds this membership",
144
+ index: true,
145
+ ref: "User",
146
+ required: true,
147
+ type: mongoose.Schema.Types.ObjectId,
148
+ },
149
+ },
150
+ {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
151
+ );
152
+
153
+ membershipSchema.index({organizationId: 1, userId: 1}, {unique: true});
154
+
155
+ membershipSchema.plugin(createdUpdatedPlugin);
156
+ membershipSchema.plugin(isDeletedPlugin);
157
+ membershipSchema.plugin(findOneOrNone);
158
+ membershipSchema.plugin(findExactlyOne);
159
+
160
+ membershipSchema.statics = {
161
+ ...membershipSchema.statics,
162
+ async findActiveForUser(
163
+ this: MembershipModel,
164
+ userId: mongoose.Types.ObjectId | string
165
+ ): Promise<MembershipDocument[]> {
166
+ return this.find({
167
+ status: "active",
168
+ userId: toObjectId(userId),
169
+ });
170
+ },
171
+ async isMember(
172
+ this: MembershipModel,
173
+ userId: mongoose.Types.ObjectId | string,
174
+ organizationId: mongoose.Types.ObjectId | string
175
+ ): Promise<boolean> {
176
+ const membership = await this.findOneOrNone({
177
+ organizationId: toObjectId(organizationId),
178
+ status: "active",
179
+ userId: toObjectId(userId),
180
+ });
181
+ return Boolean(membership);
182
+ },
183
+ async isOrgAdmin(
184
+ this: MembershipModel,
185
+ userId: mongoose.Types.ObjectId | string,
186
+ organizationId: mongoose.Types.ObjectId | string
187
+ ): Promise<boolean> {
188
+ const membership = await this.findOneOrNone({
189
+ organizationId: toObjectId(organizationId),
190
+ roleName: "org-admin",
191
+ status: "active",
192
+ userId: toObjectId(userId),
193
+ });
194
+ return Boolean(membership);
195
+ },
196
+ };
197
+
198
+ export const getOrganizationModel = (): OrganizationModel => {
199
+ const existing = mongoose.models.Organization as OrganizationModel | undefined;
200
+ if (existing) {
201
+ return existing;
202
+ }
203
+ return mongoose.model<OrganizationDocument, OrganizationModel>(
204
+ "Organization",
205
+ organizationSchema
206
+ );
207
+ };
208
+
209
+ export const getMembershipModel = (): MembershipModel => {
210
+ const existing = mongoose.models.Membership as MembershipModel | undefined;
211
+ if (existing) {
212
+ return existing;
213
+ }
214
+ return mongoose.model<MembershipDocument, MembershipModel>("Membership", membershipSchema);
215
+ };
216
+
217
+ const createLazyModel = <T extends mongoose.Model<unknown>>(getModel: () => T): T => {
218
+ const handler: ProxyHandler<object> = {
219
+ apply(_target, thisArg, argArray) {
220
+ return Reflect.apply(
221
+ getModel() as unknown as (...args: unknown[]) => unknown,
222
+ thisArg,
223
+ argArray
224
+ );
225
+ },
226
+ construct(_target, argArray) {
227
+ const Model = getModel() as unknown as new (...args: unknown[]) => object;
228
+ return new Model(...argArray);
229
+ },
230
+ get(_target, prop) {
231
+ const model = getModel();
232
+ const value = Reflect.get(model, prop, model);
233
+ if (typeof value === "function") {
234
+ return value.bind(model);
235
+ }
236
+ return value;
237
+ },
238
+ getPrototypeOf() {
239
+ return Object.getPrototypeOf(getModel());
240
+ },
241
+ has(_target, prop) {
242
+ return prop in getModel();
243
+ },
244
+ set(_target, prop, value) {
245
+ Reflect.set(getModel(), prop, value);
246
+ return true;
247
+ },
248
+ };
249
+ class LazyMongooseModel {}
250
+ return new Proxy(LazyMongooseModel, handler) as unknown as T;
251
+ };
252
+
253
+ /** Lazy so importing `@terreno/api` does not register Organization until first use. */
254
+ export const Organization = createLazyModel(getOrganizationModel);
255
+
256
+ /** Lazy so importing `@terreno/api` does not register Membership until first use. */
257
+ export const Membership = createLazyModel(getMembershipModel);
@@ -0,0 +1,113 @@
1
+ import {afterEach, describe, it} from "bun:test";
2
+ import {assert} from "chai";
3
+ import mongoose from "mongoose";
4
+
5
+ import {ValidationError} from "../errors";
6
+ import {Organization} from "./organizationModel";
7
+ import {
8
+ applyOrganizationSettings,
9
+ createOrganizationSettingsSchema,
10
+ getOrganizationSettingsSchema,
11
+ organizationSettingsOf,
12
+ registerOrganizationSettings,
13
+ } from "./organizationSettings";
14
+
15
+ const userId = (): mongoose.Types.ObjectId => new mongoose.Types.ObjectId();
16
+
17
+ interface ExampleSettings {
18
+ timezone?: string;
19
+ }
20
+
21
+ describe("organization settings schema", () => {
22
+ afterEach(() => {
23
+ registerOrganizationSettings();
24
+ });
25
+
26
+ it("passes Mixed settings through when no schema is registered", () => {
27
+ const settings = applyOrganizationSettings({nested: {ok: true}, plan: "pro"});
28
+ assert.deepEqual(settings, {nested: {ok: true}, plan: "pro"});
29
+ });
30
+
31
+ it("returns an empty object from organizationSettingsOf when settings are missing", () => {
32
+ assert.deepEqual(organizationSettingsOf({}), {});
33
+ assert.deepEqual(organizationSettingsOf({settings: {timezone: "UTC"}}), {timezone: "UTC"});
34
+ });
35
+
36
+ it("rejects unknown keys and wrong types when a schema is registered", () => {
37
+ registerOrganizationSettings(
38
+ createOrganizationSettingsSchema({
39
+ timezone: {
40
+ description: "IANA timezone for the organization",
41
+ type: String,
42
+ },
43
+ })
44
+ );
45
+ assert.isDefined(getOrganizationSettingsSchema());
46
+
47
+ const valid = applyOrganizationSettings({timezone: "America/New_York"});
48
+ assert.equal((valid as ExampleSettings).timezone, "America/New_York");
49
+
50
+ let extraKeyError: unknown;
51
+ try {
52
+ applyOrganizationSettings({plan: "pro"});
53
+ } catch (caughtError) {
54
+ extraKeyError = caughtError;
55
+ }
56
+ assert.instanceOf(extraKeyError, ValidationError);
57
+ assert.equal((extraKeyError as ValidationError).title, "Organization settings are invalid");
58
+ assert.match(
59
+ String((extraKeyError as ValidationError).meta?.fields?.settings),
60
+ /Unknown settings field: plan/
61
+ );
62
+
63
+ let typeError: unknown;
64
+ try {
65
+ applyOrganizationSettings({timezone: {notAString: true}});
66
+ } catch (caughtError) {
67
+ typeError = caughtError;
68
+ }
69
+ assert.instanceOf(typeError, ValidationError);
70
+
71
+ let notObjectError: unknown;
72
+ try {
73
+ applyOrganizationSettings(["timezone"]);
74
+ } catch (caughtError) {
75
+ notObjectError = caughtError;
76
+ }
77
+ assert.instanceOf(notObjectError, ValidationError);
78
+ assert.equal(
79
+ (notObjectError as ValidationError).title,
80
+ "Organization settings must be an object"
81
+ );
82
+ });
83
+
84
+ it("validates settings on Organization.create", async () => {
85
+ registerOrganizationSettings(
86
+ createOrganizationSettingsSchema({
87
+ timezone: {
88
+ description: "IANA timezone for the organization",
89
+ type: String,
90
+ },
91
+ })
92
+ );
93
+
94
+ const org = await Organization.create({
95
+ name: "Settings Org",
96
+ ownerId: userId(),
97
+ settings: {timezone: "UTC"},
98
+ });
99
+ assert.equal(organizationSettingsOf<ExampleSettings>(org).timezone, "UTC");
100
+
101
+ let error: unknown;
102
+ try {
103
+ await Organization.create({
104
+ name: "Bad Settings Org",
105
+ ownerId: userId(),
106
+ settings: {unknown: true},
107
+ });
108
+ } catch (caughtError) {
109
+ error = caughtError;
110
+ }
111
+ assert.instanceOf(error, ValidationError);
112
+ });
113
+ });
@@ -0,0 +1,126 @@
1
+ import mongoose from "mongoose";
2
+
3
+ import {ValidationError} from "../errors";
4
+ import type {OrganizationSettings} from "../types/organization";
5
+
6
+ const SETTINGS_VALIDATOR_MODEL = "__TerrenoOrganizationSettings";
7
+
8
+ let registeredOrganizationSettingsSchema: mongoose.Schema | undefined;
9
+
10
+ const dropSettingsValidatorModel = (): void => {
11
+ const existing = mongoose.models[SETTINGS_VALIDATOR_MODEL];
12
+ if (existing) {
13
+ mongoose.deleteModel(SETTINGS_VALIDATOR_MODEL);
14
+ }
15
+ };
16
+
17
+ /**
18
+ * Build a nested Mongoose schema for `Organization.settings`.
19
+ * Fields should be optional or have defaults so existing organizations still validate.
20
+ */
21
+ export const createOrganizationSettingsSchema = (
22
+ definition: mongoose.SchemaDefinition,
23
+ options?: mongoose.SchemaOptions
24
+ ): mongoose.Schema => {
25
+ return new mongoose.Schema(definition, {
26
+ _id: false,
27
+ id: false,
28
+ strict: "throw",
29
+ ...options,
30
+ });
31
+ };
32
+
33
+ /** Register the app settings schema. Call before creating or patching organizations. */
34
+ export const registerOrganizationSettings = (schema?: mongoose.Schema): void => {
35
+ dropSettingsValidatorModel();
36
+ registeredOrganizationSettingsSchema = schema;
37
+ };
38
+
39
+ export const getOrganizationSettingsSchema = (): mongoose.Schema | undefined => {
40
+ return registeredOrganizationSettingsSchema;
41
+ };
42
+
43
+ const settingsValidationMessage = (error: unknown): string => {
44
+ if (error instanceof mongoose.Error.ValidationError) {
45
+ return Object.values(error.errors)
46
+ .map((fieldError) => fieldError.message)
47
+ .join("; ");
48
+ }
49
+ if (error instanceof Error) {
50
+ return error.message;
51
+ }
52
+ return "Organization settings are invalid";
53
+ };
54
+
55
+ const getSettingsValidatorModel = (schema: mongoose.Schema): mongoose.Model<mongoose.Document> => {
56
+ const existing = mongoose.models[SETTINGS_VALIDATOR_MODEL] as
57
+ | mongoose.Model<mongoose.Document>
58
+ | undefined;
59
+ if (existing) {
60
+ return existing;
61
+ }
62
+ return mongoose.model<mongoose.Document>(SETTINGS_VALIDATOR_MODEL, schema, undefined, {
63
+ overwriteModels: true,
64
+ });
65
+ };
66
+
67
+ /**
68
+ * Validate and cast `Organization.settings` when a schema is registered.
69
+ * With no schema, Mixed values pass through unchanged.
70
+ */
71
+ export const applyOrganizationSettings = <
72
+ TSettings extends OrganizationSettings = OrganizationSettings,
73
+ >(
74
+ settings: unknown
75
+ ): TSettings | undefined => {
76
+ if (settings === undefined || settings === null) {
77
+ return undefined;
78
+ }
79
+ const schema = registeredOrganizationSettingsSchema;
80
+ if (!schema) {
81
+ return settings as TSettings;
82
+ }
83
+ if (typeof settings !== "object" || Array.isArray(settings)) {
84
+ throw new ValidationError({
85
+ fields: {settings: "Organization settings must be an object"},
86
+ title: "Organization settings must be an object",
87
+ });
88
+ }
89
+ try {
90
+ const unknownKeys = Object.keys(settings).filter((key) => {
91
+ return schema.path(key) === undefined;
92
+ });
93
+ if (unknownKeys.length > 0) {
94
+ throw new ValidationError({
95
+ fields: {settings: `Unknown settings field: ${unknownKeys.join(", ")}`},
96
+ title: "Organization settings are invalid",
97
+ });
98
+ }
99
+ const ValidatorModel = getSettingsValidatorModel(schema);
100
+ const document = new ValidatorModel(settings);
101
+ const validationError = document.validateSync();
102
+ if (validationError) {
103
+ throw validationError;
104
+ }
105
+ return document.toObject({versionKey: false}) as unknown as TSettings;
106
+ } catch (error) {
107
+ if (error instanceof ValidationError) {
108
+ throw error;
109
+ }
110
+ throw new ValidationError({
111
+ cause: error instanceof Error ? error : undefined,
112
+ detail: settingsValidationMessage(error),
113
+ fields: {settings: settingsValidationMessage(error)},
114
+ title: "Organization settings are invalid",
115
+ });
116
+ }
117
+ };
118
+
119
+ /** Read typed settings from an organization document or API payload. */
120
+ export const organizationSettingsOf = <
121
+ TSettings extends OrganizationSettings = OrganizationSettings,
122
+ >(organization: {
123
+ settings?: TSettings | null;
124
+ }): TSettings => {
125
+ return (organization.settings ?? {}) as TSettings;
126
+ };