@terreno/api 57.0.0 → 57.1.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 (175) hide show
  1. package/.ai/skills/mongoose-schema-safety/SKILL.md +8 -0
  2. package/dist/actions.d.ts +7 -2
  3. package/dist/actions.js +60 -25
  4. package/dist/adminModelRouter.d.ts +14 -0
  5. package/dist/adminModelRouter.js +199 -0
  6. package/dist/adminTypes.d.ts +156 -0
  7. package/dist/adminTypes.js +5 -0
  8. package/dist/api.d.ts +44 -3
  9. package/dist/api.js +74 -26
  10. package/dist/auth.d.ts +18 -1
  11. package/dist/auth.js +122 -20
  12. package/dist/consentApp.d.ts +2 -0
  13. package/dist/consentApp.js +98 -0
  14. package/dist/index.d.ts +22 -1
  15. package/dist/index.js +51 -7
  16. package/dist/mcp/auth.d.ts +11 -0
  17. package/dist/mcp/auth.js +133 -0
  18. package/dist/mcp/createMCPRequest.d.ts +16 -0
  19. package/dist/mcp/createMCPRequest.js +26 -0
  20. package/dist/mcp/handlers.d.ts +8 -0
  21. package/dist/mcp/handlers.js +793 -0
  22. package/dist/mcp/query.d.ts +32 -0
  23. package/dist/mcp/query.js +232 -0
  24. package/dist/mcp/registry.d.ts +21 -0
  25. package/dist/mcp/registry.js +54 -0
  26. package/dist/mcp/schemaGenerator.d.ts +14 -0
  27. package/dist/mcp/schemaGenerator.js +379 -0
  28. package/dist/mcp/server.d.ts +8 -0
  29. package/dist/mcp/server.js +133 -0
  30. package/dist/mcp/toolGenerator.d.ts +14 -0
  31. package/dist/mcp/toolGenerator.js +246 -0
  32. package/dist/mcp/types.d.ts +85 -0
  33. package/dist/mcp/types.js +2 -0
  34. package/dist/openApi.d.ts +1 -1
  35. package/dist/openApi.js +26 -8
  36. package/dist/permissions.js +15 -15
  37. package/dist/rbac/access.d.ts +3 -0
  38. package/dist/rbac/access.js +294 -0
  39. package/dist/rbac/auditModel.d.ts +31 -0
  40. package/dist/rbac/auditModel.js +112 -0
  41. package/dist/rbac/backfillAdmins.d.ts +18 -0
  42. package/dist/rbac/backfillAdmins.js +139 -0
  43. package/dist/rbac/fieldViews.d.ts +3 -0
  44. package/dist/rbac/fieldViews.js +201 -0
  45. package/dist/rbac/middleware.d.ts +21 -0
  46. package/dist/rbac/middleware.js +108 -0
  47. package/dist/rbac/modelRouterAccess.d.ts +42 -0
  48. package/dist/rbac/modelRouterAccess.js +388 -0
  49. package/dist/rbac/permissionUtils.d.ts +8 -0
  50. package/dist/rbac/permissionUtils.js +209 -0
  51. package/dist/rbac/realtimeAccess.d.ts +18 -0
  52. package/dist/rbac/realtimeAccess.js +173 -0
  53. package/dist/rbac/resolve.d.ts +28 -0
  54. package/dist/rbac/resolve.js +387 -0
  55. package/dist/rbac/roleManager.d.ts +20 -0
  56. package/dist/rbac/roleManager.js +741 -0
  57. package/dist/rbac/roleModel.d.ts +42 -0
  58. package/dist/rbac/roleModel.js +267 -0
  59. package/dist/rbac/routes.d.ts +9 -0
  60. package/dist/rbac/routes.js +211 -0
  61. package/dist/rbac/scopes.d.ts +15 -0
  62. package/dist/rbac/scopes.js +155 -0
  63. package/dist/rbac/statements.d.ts +20 -0
  64. package/dist/rbac/statements.js +115 -0
  65. package/dist/rbac/types.d.ts +202 -0
  66. package/dist/rbac/types.js +2 -0
  67. package/dist/rbac/userPlugin.d.ts +12 -0
  68. package/dist/rbac/userPlugin.js +41 -0
  69. package/dist/realtime/changeStreamWatcher.d.ts +1 -1
  70. package/dist/realtime/changeStreamWatcher.js +48 -39
  71. package/dist/realtime/realtimeApp.js +4 -8
  72. package/dist/realtime/registry.d.ts +5 -0
  73. package/dist/realtime/registry.js +13 -1
  74. package/dist/scrubAdminFields.d.ts +17 -0
  75. package/dist/scrubAdminFields.js +192 -0
  76. package/dist/sync/executors.d.ts +1 -1
  77. package/dist/sync/executors.js +63 -40
  78. package/dist/sync/loadHarness.js +4 -5
  79. package/dist/sync/registry.d.ts +5 -0
  80. package/dist/sync/registry.js +13 -1
  81. package/dist/sync/routes.js +41 -36
  82. package/dist/sync/serialize.js +5 -6
  83. package/dist/terrenoApp.d.ts +18 -0
  84. package/dist/terrenoApp.js +46 -3
  85. package/dist/terrenoPlugin.d.ts +8 -1
  86. package/dist/tests/createTestData.js +8 -0
  87. package/dist/tests/models.d.ts +1 -0
  88. package/dist/tests/models.js +5 -0
  89. package/dist/tests/testHelper.js +1 -2
  90. package/dist/transformers.js +16 -1
  91. package/package.json +16 -12
  92. package/src/__snapshots__/openApi.test.ts.snap +192 -0
  93. package/src/actions.test.ts +194 -1
  94. package/src/actions.ts +65 -8
  95. package/src/adminModelRouter.ts +154 -0
  96. package/src/adminTypes.ts +183 -0
  97. package/src/api.test.ts +66 -1
  98. package/src/api.ts +131 -12
  99. package/src/auth.test.ts +135 -1
  100. package/src/auth.ts +81 -3
  101. package/src/consentApp.test.ts +24 -0
  102. package/src/consentApp.ts +100 -0
  103. package/src/index.ts +56 -0
  104. package/src/mcp/auth.test.ts +197 -0
  105. package/src/mcp/auth.ts +100 -0
  106. package/src/mcp/createMCPRequest.test.ts +47 -0
  107. package/src/mcp/createMCPRequest.ts +32 -0
  108. package/src/mcp/customTools.test.ts +54 -0
  109. package/src/mcp/handlers.ts +639 -0
  110. package/src/mcp/integration.test.ts +1493 -0
  111. package/src/mcp/query.test.ts +172 -0
  112. package/src/mcp/query.ts +179 -0
  113. package/src/mcp/registry.ts +70 -0
  114. package/src/mcp/schemaGenerator.test.ts +182 -0
  115. package/src/mcp/schemaGenerator.ts +354 -0
  116. package/src/mcp/server.test.ts +226 -0
  117. package/src/mcp/server.ts +86 -0
  118. package/src/mcp/toolGenerator.test.ts +284 -0
  119. package/src/mcp/toolGenerator.ts +199 -0
  120. package/src/mcp/types.ts +95 -0
  121. package/src/openApi.test.ts +107 -0
  122. package/src/openApi.ts +32 -1
  123. package/src/permissions.ts +3 -2
  124. package/src/rbac/access.test.ts +357 -0
  125. package/src/rbac/access.ts +201 -0
  126. package/src/rbac/auditModel.ts +103 -0
  127. package/src/rbac/backfillAdmins.ts +54 -0
  128. package/src/rbac/fieldViews.test.ts +39 -0
  129. package/src/rbac/fieldViews.ts +122 -0
  130. package/src/rbac/middleware.ts +55 -0
  131. package/src/rbac/modelRouterAccess.test.ts +336 -0
  132. package/src/rbac/modelRouterAccess.ts +331 -0
  133. package/src/rbac/permissionUtils.test.ts +112 -0
  134. package/src/rbac/permissionUtils.ts +83 -0
  135. package/src/rbac/realtimeAccess.test.ts +242 -0
  136. package/src/rbac/realtimeAccess.ts +138 -0
  137. package/src/rbac/resolve.test.ts +358 -0
  138. package/src/rbac/resolve.ts +285 -0
  139. package/src/rbac/roleManager.test.ts +915 -0
  140. package/src/rbac/roleManager.ts +440 -0
  141. package/src/rbac/roleModel.test.ts +114 -0
  142. package/src/rbac/roleModel.ts +196 -0
  143. package/src/rbac/routes.ts +170 -0
  144. package/src/rbac/scopes.test.ts +105 -0
  145. package/src/rbac/scopes.ts +81 -0
  146. package/src/rbac/statements.test.ts +65 -0
  147. package/src/rbac/statements.ts +62 -0
  148. package/src/rbac/types.ts +198 -0
  149. package/src/rbac/userPlugin.test.ts +55 -0
  150. package/src/rbac/userPlugin.ts +25 -0
  151. package/src/realtime/changeStreamWatcher.ts +20 -15
  152. package/src/realtime/realtime.test.ts +25 -1
  153. package/src/realtime/realtimeApp.ts +2 -5
  154. package/src/realtime/registry.ts +15 -0
  155. package/src/scrubAdminFields.test.ts +113 -0
  156. package/src/scrubAdminFields.ts +158 -0
  157. package/src/sync/executors.ts +31 -1
  158. package/src/sync/loadHarness.ts +8 -7
  159. package/src/sync/models.test.ts +262 -0
  160. package/src/sync/registry.ts +15 -0
  161. package/src/sync/routes.ts +25 -11
  162. package/src/sync/scripts/compactTombstones.test.ts +4 -6
  163. package/src/sync/serialize.ts +17 -9
  164. package/src/sync/sync.test.ts +52 -0
  165. package/src/sync/syncRoutes.test.ts +5 -2
  166. package/src/sync/syncSocket.test.ts +28 -0
  167. package/src/terrenoApp.test.ts +100 -0
  168. package/src/terrenoApp.ts +65 -3
  169. package/src/terrenoPlugin.ts +10 -1
  170. package/src/tests/bunSetup.ts +2 -0
  171. package/src/tests/createTestData.ts +5 -1
  172. package/src/tests/models.ts +6 -0
  173. package/src/tests/testHelper.ts +1 -3
  174. package/src/transformers.test.ts +12 -0
  175. package/src/transformers.ts +7 -1
@@ -10,6 +10,13 @@ description: >-
10
10
 
11
11
  Typical Terreno apps keep models under `backend/src/models/` and types under `backend/src/types/models/`. The Terreno monorepo also uses `example-backend/` and `@terreno/ai` — adjust paths below to match your repo.
12
12
 
13
+ ## Documentation
14
+
15
+ 1. Read the app's model/API docs before changing schemas, types, or indexes.
16
+ 2. Implement against that design.
17
+ 3. Update those docs in the same slice. Schema field `description`s are public docs via OpenAPI.
18
+ 4. Ship without matching docs is a failed slice.
19
+
13
20
  ## Where Schemas and Types Live
14
21
 
15
22
  | Package | Schemas | Types |
@@ -128,6 +135,7 @@ A schema change in one place often ripples:
128
135
  - [ ] `modelRouter` config updated (`queryFields`, `populatePaths`, `responseHandler`) if needed
129
136
  - [ ] `AdminApp` `listFields` updated if the model is in the admin panel
130
137
  - [ ] `bun run sdk` run from `example-frontend/` if the API response shape changed
138
+ - [ ] Docs updated when the public shape or operator steps changed
131
139
  - [ ] Test covers old-format document behavior (missing new field) if the change rolls out before a backfill
132
140
  - [ ] Unique index: dedup migration written and run before the index is added
133
141
  - [ ] `checkModelsStrict()` still passes (it runs on non-prod startup)
package/dist/actions.d.ts CHANGED
@@ -5,6 +5,7 @@ import type { ZodSchema } from "zod";
5
5
  import { type ModelRouterOptions } from "./api";
6
6
  import { type User } from "./auth";
7
7
  import { type PermissionMethod } from "./permissions";
8
+ import type { AnyTerrenoAccess, ModelRouterAccessOptions } from "./rbac/types";
8
9
  export declare const ACTION_NAME_PATTERN: RegExp;
9
10
  export interface ActionContext<TDoc, TBody, TQuery> {
10
11
  req: Request;
@@ -16,7 +17,11 @@ export interface ActionContext<TDoc, TBody, TQuery> {
16
17
  }
17
18
  interface BaseActionConfig<TBody, TQuery, TResponse> {
18
19
  method: "GET" | "POST";
19
- permissions: PermissionMethod<unknown>[];
20
+ permissions?: PermissionMethod<unknown>[];
21
+ access?: {
22
+ resource: string;
23
+ action: string;
24
+ };
20
25
  body?: ZodSchema<TBody>;
21
26
  query?: ZodSchema<TQuery>;
22
27
  response?: ZodSchema<TResponse>;
@@ -34,7 +39,7 @@ export interface CollectionActionConfig<TBody, TQuery, TResponse> extends BaseAc
34
39
  export declare const defineInstanceAction: <TDoc, TBody = unknown, TQuery = unknown, TResponse = unknown>(config: InstanceActionConfig<TDoc, TBody, TQuery, TResponse>) => InstanceActionConfig<TDoc, TBody, TQuery, TResponse>;
35
40
  export declare const defineCollectionAction: <TBody = unknown, TQuery = unknown, TResponse = unknown>(config: CollectionActionConfig<TBody, TQuery, TResponse>) => CollectionActionConfig<TBody, TQuery, TResponse>;
36
41
  type ActionScope = "instance" | "collection";
37
- export declare const runActionPermissions: <T>(action: BaseActionConfig<unknown, unknown, unknown>, scope: ActionScope, model: Model<T>, req: Request, doc?: T) => Promise<void>;
42
+ export declare const runActionPermissions: <T>(action: BaseActionConfig<unknown, unknown, unknown>, scope: ActionScope, model: Model<T>, req: Request, doc?: T, accessControl?: AnyTerrenoAccess, routerAccess?: ModelRouterAccessOptions) => Promise<void>;
38
43
  export declare const validateActionRequest: <TBody, TQuery>({ action, req, }: {
39
44
  action: BaseActionConfig<TBody, TQuery, unknown>;
40
45
  req: Request;
package/dist/actions.js CHANGED
@@ -46,17 +46,6 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
46
46
  if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
47
47
  }
48
48
  };
49
- var __values = (this && this.__values) || function(o) {
50
- var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
51
- if (m) return m.call(o);
52
- if (o && typeof o.length === "number") return {
53
- next: function () {
54
- if (o && i >= o.length) o = void 0;
55
- return { value: o && o[i++], done: !o };
56
- }
57
- };
58
- throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
59
- };
60
49
  var __read = (this && this.__read) || function (o, n) {
61
50
  var m = typeof Symbol === "function" && o[Symbol.iterator];
62
51
  if (!m) return o;
@@ -82,6 +71,17 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
82
71
  }
83
72
  return to.concat(ar || Array.prototype.slice.call(from));
84
73
  };
74
+ var __values = (this && this.__values) || function(o) {
75
+ var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
76
+ if (m) return m.call(o);
77
+ if (o && typeof o.length === "number") return {
78
+ next: function () {
79
+ if (o && i >= o.length) o = void 0;
80
+ return { value: o && o[i++], done: !o };
81
+ }
82
+ };
83
+ throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
84
+ };
85
85
  Object.defineProperty(exports, "__esModule", { value: true });
86
86
  exports.registerActionRoutes = exports.assertNoActionCollisions = exports.createActionOpenApiMiddleware = exports.wrapActionResponse = exports.validateActionRequest = exports.runActionPermissions = exports.defineCollectionAction = exports.defineInstanceAction = exports.ACTION_NAME_PATTERN = void 0;
87
87
  var zod_to_openapi_1 = require("@asteasolutions/zod-to-openapi");
@@ -91,6 +91,7 @@ var docLoader_1 = require("./docLoader");
91
91
  var errors_1 = require("./errors");
92
92
  var openApi_1 = require("./openApi");
93
93
  var permissions_1 = require("./permissions");
94
+ var middleware_1 = require("./rbac/middleware");
94
95
  // At least two characters: leading letter plus one or more alphanumeric/_/- chars.
95
96
  exports.ACTION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]+$/;
96
97
  var defineInstanceAction = function (config) {
@@ -107,16 +108,47 @@ var mapActionToCrudMethod = function (scope, httpMethod) {
107
108
  }
108
109
  return httpMethod === "GET" ? "list" : "create";
109
110
  };
110
- var runActionPermissions = function (action, scope, model, req, doc) { return __awaiter(void 0, void 0, void 0, function () {
111
- var method, allowed;
112
- var _a, _b;
113
- return __generator(this, function (_c) {
114
- switch (_c.label) {
111
+ var resolveActionAccess = function (action, scope, routerAccess) {
112
+ var _a;
113
+ if (action.access) {
114
+ return action.access;
115
+ }
116
+ if (!(routerAccess === null || routerAccess === void 0 ? void 0 : routerAccess.resource)) {
117
+ return undefined;
118
+ }
119
+ var crud = mapActionToCrudMethod(scope, action.method);
120
+ var mapped = (_a = routerAccess.actions) === null || _a === void 0 ? void 0 : _a[crud];
121
+ if (mapped === null) {
122
+ return null;
123
+ }
124
+ return { action: mapped !== null && mapped !== void 0 ? mapped : crud, resource: routerAccess.resource };
125
+ };
126
+ var runActionPermissions = function (action, scope, model, req, doc, accessControl, routerAccess) { return __awaiter(void 0, void 0, void 0, function () {
127
+ var method, permissions, rbacAccess, isPermitted, rbacCheck, allowed;
128
+ var _a;
129
+ var _b, _c, _d;
130
+ return __generator(this, function (_e) {
131
+ switch (_e.label) {
115
132
  case 0:
116
133
  method = mapActionToCrudMethod(scope, action.method);
117
- return [4 /*yield*/, (0, permissions_1.checkPermissions)(method, action.permissions, req.user, doc)];
134
+ permissions = action.permissions;
135
+ rbacAccess = resolveActionAccess(action, scope, routerAccess);
136
+ if (rbacAccess === null || (permissions === null || permissions === void 0 ? void 0 : permissions.length) === 0) {
137
+ permissions = [];
138
+ }
139
+ else if (rbacAccess && accessControl) {
140
+ isPermitted = (0, middleware_1.createIsPermitted)({ can: accessControl.can });
141
+ rbacCheck = isPermitted((_a = {},
142
+ _a[rbacAccess.resource] = [rbacAccess.action],
143
+ _a));
144
+ permissions = __spreadArray(__spreadArray([], __read(((_b = action.permissions) !== null && _b !== void 0 ? _b : [])), false), [rbacCheck], false);
145
+ }
146
+ if (!permissions) {
147
+ throw new errors_1.APIError({ status: 500, title: "Action missing permissions configuration" });
148
+ }
149
+ return [4 /*yield*/, (0, permissions_1.checkPermissions)(method, permissions, req.user, doc)];
118
150
  case 1:
119
- allowed = _c.sent();
151
+ allowed = _e.sent();
120
152
  if (allowed) {
121
153
  return [2 /*return*/];
122
154
  }
@@ -125,7 +157,7 @@ var runActionPermissions = function (action, scope, model, req, doc) { return __
125
157
  // in modelRouter's array operations; changing it would break consumers matching on it.
126
158
  throw new errors_1.APIError({
127
159
  code: "action-access-denied",
128
- detail: "Access to ".concat(method.toUpperCase(), " on ").concat(model.modelName, " ") + "denied for ".concat((_a = req.user) === null || _a === void 0 ? void 0 : _a.id),
160
+ detail: "Access to ".concat(method.toUpperCase(), " on ").concat(model.modelName, " ") + "denied for ".concat((_c = req.user) === null || _c === void 0 ? void 0 : _c.id),
129
161
  meta: { action: method.toUpperCase(), model: model.modelName },
130
162
  status: 405,
131
163
  title: "Access denied",
@@ -134,7 +166,7 @@ var runActionPermissions = function (action, scope, model, req, doc) { return __
134
166
  throw new errors_1.ForbiddenError({
135
167
  code: "action-access-denied",
136
168
  detail: "Access to ".concat(method.toUpperCase(), " on ").concat(model.modelName, ":").concat(req.params.id, " ") +
137
- "denied for ".concat((_b = req.user) === null || _b === void 0 ? void 0 : _b.id),
169
+ "denied for ".concat((_d = req.user) === null || _d === void 0 ? void 0 : _d.id),
138
170
  meta: { action: method.toUpperCase(), model: model.modelName },
139
171
  title: "Access denied",
140
172
  });
@@ -314,9 +346,12 @@ var validateActionConfig = function (scope, name, config) {
314
346
  if (!exports.ACTION_NAME_PATTERN.test(name)) {
315
347
  throw new Error("Invalid action name \"".concat(name, "\". Action names must match ").concat(exports.ACTION_NAME_PATTERN.toString()));
316
348
  }
317
- if (config.permissions === undefined) {
318
- throw new Error("Action \"".concat(name, "\" (").concat(scope, ") is missing required \"permissions\". ") +
319
- "Provide at least one permission function, or [] to disable the action.");
349
+ if (config.permissions === undefined && !config.access) {
350
+ throw new Error("Action \"".concat(name, "\" (").concat(scope, ") is missing required \"permissions\" or \"access\". ") +
351
+ "Provide at least one permission function, an access descriptor, or [] to disable the action.");
352
+ }
353
+ if (config.permissions !== undefined && config.permissions.length === 0 && !config.access) {
354
+ return;
320
355
  }
321
356
  if (config.method !== "GET" && config.method !== "POST") {
322
357
  throw new Error("Action \"".concat(name, "\" (").concat(scope, ") only supports GET and POST methods"));
@@ -360,7 +395,7 @@ var buildActionMiddleware = function (model, options, registered) {
360
395
  switch (_a.label) {
361
396
  case 0:
362
397
  _a.trys.push([0, 2, , 3]);
363
- return [4 /*yield*/, (0, exports.runActionPermissions)(action, scope, model, req)];
398
+ return [4 /*yield*/, (0, exports.runActionPermissions)(action, scope, model, req, undefined, options.accessControl, options.access)];
364
399
  case 1:
365
400
  _a.sent();
366
401
  return [2 /*return*/, next()];
@@ -382,7 +417,7 @@ var buildActionMiddleware = function (model, options, registered) {
382
417
  case 1:
383
418
  doc = _a.sent();
384
419
  req.obj = doc;
385
- return [4 /*yield*/, (0, exports.runActionPermissions)(action, scope, model, req, doc)];
420
+ return [4 /*yield*/, (0, exports.runActionPermissions)(action, scope, model, req, doc, options.accessControl, options.access)];
386
421
  case 2:
387
422
  _a.sent();
388
423
  return [2 /*return*/, next()];
@@ -0,0 +1,14 @@
1
+ import type { Model } from "mongoose";
2
+ import type { ModelRouterOptions } from "./api";
3
+ import type { AnyTerrenoAccess } from "./rbac/types";
4
+ import type { TerrenoApp } from "./terrenoApp";
5
+ export interface ModelRouterBuildContext {
6
+ accessControl?: AnyTerrenoAccess;
7
+ openApi?: ModelRouterOptions<unknown>["openApi"];
8
+ routePath?: string;
9
+ terrenoApp?: TerrenoApp;
10
+ }
11
+ /**
12
+ * Wraps modelRouter lifecycle hooks to enforce admin body scrubbing and optional realtime emits.
13
+ */
14
+ export declare const enrichModelRouterOptions: <T>(model: Model<T>, options: ModelRouterOptions<T>, context: ModelRouterBuildContext) => ModelRouterOptions<T>;
@@ -0,0 +1,199 @@
1
+ "use strict";
2
+ var __assign = (this && this.__assign) || function () {
3
+ __assign = Object.assign || function(t) {
4
+ for (var s, i = 1, n = arguments.length; i < n; i++) {
5
+ s = arguments[i];
6
+ for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
7
+ t[p] = s[p];
8
+ }
9
+ return t;
10
+ };
11
+ return __assign.apply(this, arguments);
12
+ };
13
+ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
14
+ function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
15
+ return new (P || (P = Promise))(function (resolve, reject) {
16
+ function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
17
+ function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
18
+ function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
19
+ step((generator = generator.apply(thisArg, _arguments || [])).next());
20
+ });
21
+ };
22
+ var __generator = (this && this.__generator) || function (thisArg, body) {
23
+ var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
24
+ return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
25
+ function verb(n) { return function (v) { return step([n, v]); }; }
26
+ function step(op) {
27
+ if (f) throw new TypeError("Generator is already executing.");
28
+ while (g && (g = 0, op[0] && (_ = 0)), _) try {
29
+ if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
30
+ if (y = 0, t) op = [op[0] & 2, t.value];
31
+ switch (op[0]) {
32
+ case 0: case 1: t = op; break;
33
+ case 4: _.label++; return { value: op[1], done: false };
34
+ case 5: _.label++; y = op[1]; op = [0]; continue;
35
+ case 7: op = _.ops.pop(); _.trys.pop(); continue;
36
+ default:
37
+ if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
38
+ if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
39
+ if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
40
+ if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
41
+ if (t[2]) _.ops.pop();
42
+ _.trys.pop(); continue;
43
+ }
44
+ op = body.call(thisArg, _);
45
+ } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
46
+ if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
47
+ }
48
+ };
49
+ Object.defineProperty(exports, "__esModule", { value: true });
50
+ exports.enrichModelRouterOptions = void 0;
51
+ var luxon_1 = require("luxon");
52
+ var scrubAdminFields_1 = require("./scrubAdminFields");
53
+ var emitAdminModelChanged = function (_a) {
54
+ var _b, _c, _d;
55
+ var admin = _a.admin, doc = _a.doc, model = _a.model, req = _a.req, routePath = _a.routePath, terrenoApp = _a.terrenoApp, type = _a.type;
56
+ var userId = (_c = (_b = req.user) === null || _b === void 0 ? void 0 : _b._id) !== null && _c !== void 0 ? _c : (_d = req.user) === null || _d === void 0 ? void 0 : _d.id;
57
+ if (!userId) {
58
+ return;
59
+ }
60
+ var event = {
61
+ at: luxon_1.DateTime.utc().toISO(),
62
+ documentId: String(doc._id),
63
+ modelName: model.modelName,
64
+ routePath: routePath,
65
+ type: type,
66
+ user: { id: String(userId) },
67
+ };
68
+ if (type !== "delete") {
69
+ event.document = (0, scrubAdminFields_1.scrubAdminFields)(doc, {
70
+ admin: admin,
71
+ schema: model.schema,
72
+ });
73
+ }
74
+ terrenoApp.emitAdminModelChanged(event);
75
+ };
76
+ /**
77
+ * Wraps modelRouter lifecycle hooks to enforce admin body scrubbing and optional realtime emits.
78
+ */
79
+ var enrichModelRouterOptions = function (model, options, context) {
80
+ var _a;
81
+ var openApi = (_a = context.openApi) !== null && _a !== void 0 ? _a : options.openApi;
82
+ var admin = options.admin;
83
+ var routePath = context.routePath;
84
+ var terrenoApp = context.terrenoApp;
85
+ if (!admin) {
86
+ return openApi ? __assign(__assign({}, options), { openApi: openApi }) : options;
87
+ }
88
+ var userPreCreate = options.preCreate;
89
+ var userPreUpdate = options.preUpdate;
90
+ var userPostCreate = options.postCreate;
91
+ var userPostUpdate = options.postUpdate;
92
+ var userPostDelete = options.postDelete;
93
+ return __assign(__assign({}, options), { openApi: openApi, postCreate: function (value, request) { return __awaiter(void 0, void 0, void 0, function () {
94
+ return __generator(this, function (_a) {
95
+ switch (_a.label) {
96
+ case 0:
97
+ if (!userPostCreate) return [3 /*break*/, 2];
98
+ return [4 /*yield*/, userPostCreate(value, request)];
99
+ case 1:
100
+ _a.sent();
101
+ _a.label = 2;
102
+ case 2:
103
+ if (admin.realtime && terrenoApp && routePath) {
104
+ emitAdminModelChanged({
105
+ admin: admin,
106
+ doc: value,
107
+ model: model,
108
+ req: request,
109
+ routePath: routePath,
110
+ terrenoApp: terrenoApp,
111
+ type: "create",
112
+ });
113
+ }
114
+ return [2 /*return*/];
115
+ }
116
+ });
117
+ }); }, postDelete: function (request, value) { return __awaiter(void 0, void 0, void 0, function () {
118
+ return __generator(this, function (_a) {
119
+ switch (_a.label) {
120
+ case 0:
121
+ if (!userPostDelete) return [3 /*break*/, 2];
122
+ return [4 /*yield*/, userPostDelete(request, value)];
123
+ case 1:
124
+ _a.sent();
125
+ _a.label = 2;
126
+ case 2:
127
+ if (admin.realtime && terrenoApp && routePath) {
128
+ emitAdminModelChanged({
129
+ admin: admin,
130
+ doc: value,
131
+ model: model,
132
+ req: request,
133
+ routePath: routePath,
134
+ terrenoApp: terrenoApp,
135
+ type: "delete",
136
+ });
137
+ }
138
+ return [2 /*return*/];
139
+ }
140
+ });
141
+ }); }, postUpdate: function (value, cleanedBody, request, prevValue) { return __awaiter(void 0, void 0, void 0, function () {
142
+ return __generator(this, function (_a) {
143
+ switch (_a.label) {
144
+ case 0:
145
+ if (!userPostUpdate) return [3 /*break*/, 2];
146
+ return [4 /*yield*/, userPostUpdate(value, cleanedBody, request, prevValue)];
147
+ case 1:
148
+ _a.sent();
149
+ _a.label = 2;
150
+ case 2:
151
+ if (admin.realtime && terrenoApp && routePath) {
152
+ emitAdminModelChanged({
153
+ admin: admin,
154
+ doc: value,
155
+ model: model,
156
+ req: request,
157
+ routePath: routePath,
158
+ terrenoApp: terrenoApp,
159
+ type: "update",
160
+ });
161
+ }
162
+ return [2 /*return*/];
163
+ }
164
+ });
165
+ }); }, preCreate: function (value, request) { return __awaiter(void 0, void 0, void 0, function () {
166
+ var body;
167
+ return __generator(this, function (_a) {
168
+ switch (_a.label) {
169
+ case 0:
170
+ body = (0, scrubAdminFields_1.stripAdminBodyFields)(value, admin);
171
+ if (!userPreCreate) return [3 /*break*/, 2];
172
+ return [4 /*yield*/, userPreCreate(body, request)];
173
+ case 1:
174
+ body = _a.sent();
175
+ _a.label = 2;
176
+ case 2: return [2 /*return*/, body];
177
+ }
178
+ });
179
+ }); }, preUpdate: function (value, request) { return __awaiter(void 0, void 0, void 0, function () {
180
+ var body, next;
181
+ return __generator(this, function (_a) {
182
+ switch (_a.label) {
183
+ case 0:
184
+ body = (0, scrubAdminFields_1.stripAdminBodyFields)(value, admin);
185
+ if (!userPreUpdate) return [3 /*break*/, 2];
186
+ return [4 /*yield*/, userPreUpdate(body, request)];
187
+ case 1:
188
+ next = _a.sent();
189
+ if (next === null) {
190
+ return [2 /*return*/, null];
191
+ }
192
+ body = next;
193
+ _a.label = 2;
194
+ case 2: return [2 /*return*/, body];
195
+ }
196
+ });
197
+ }); } });
198
+ };
199
+ exports.enrichModelRouterOptions = enrichModelRouterOptions;
@@ -0,0 +1,156 @@
1
+ import type express from "express";
2
+ import type { Model } from "mongoose";
3
+ import type { PermissionMethod, RESTPermissions } from "./permissions";
4
+ import type { PopulatePath } from "./populate";
5
+ import type { ScriptArgDef, ScriptRunner } from "./scriptRunner";
6
+ /** Server-side cap on bulk action id lists (v2 bulk-patch). */
7
+ export declare const MAX_BULK_PATCH_IDS = 1000;
8
+ export type AdminFilterKind = "boolean" | "choice" | "dateRange" | "ref" | "text";
9
+ export interface AdminFilterBoolean {
10
+ field: string;
11
+ kind: "boolean";
12
+ label?: string;
13
+ }
14
+ export interface AdminFilterChoice {
15
+ choices: {
16
+ label: string;
17
+ value: string;
18
+ }[];
19
+ field: string;
20
+ kind: "choice";
21
+ label?: string;
22
+ }
23
+ export interface AdminFilterDateRange {
24
+ field: string;
25
+ kind: "dateRange";
26
+ label?: string;
27
+ }
28
+ export interface AdminFilterRef {
29
+ field: string;
30
+ kind: "ref";
31
+ label?: string;
32
+ refModel?: string;
33
+ }
34
+ export interface AdminFilterText {
35
+ field: string;
36
+ kind: "text";
37
+ label?: string;
38
+ }
39
+ export type AdminFilter = AdminFilterBoolean | AdminFilterChoice | AdminFilterDateRange | AdminFilterRef | AdminFilterText;
40
+ export interface AdminFieldset {
41
+ collapsed?: boolean;
42
+ description?: string;
43
+ fields: string[];
44
+ title: string;
45
+ }
46
+ export interface AdminFieldOverride {
47
+ helpText?: string;
48
+ label?: string;
49
+ widget?: string;
50
+ }
51
+ /** Declarative bulk action (v2 bulk-patch / background-tasks — no imperative run handler). */
52
+ export interface AdminAction {
53
+ background?: boolean;
54
+ confirm?: string;
55
+ id: string;
56
+ label: string;
57
+ /** Keys allowed for synchronous bulk-patch actions */
58
+ patchKeys?: string[];
59
+ }
60
+ export interface AdminModelPermissions {
61
+ create?: boolean;
62
+ delete?: boolean;
63
+ update?: boolean;
64
+ }
65
+ export interface AdminConfig {
66
+ displayName: string;
67
+ group?: string;
68
+ icon?: string;
69
+ listFields: string[];
70
+ listDisplay?: string[];
71
+ listDisplayLinks?: string[];
72
+ searchFields?: string[];
73
+ sortableFields?: string[];
74
+ defaultSort?: string | string[];
75
+ pageSize?: number;
76
+ filters?: AdminFilter[];
77
+ fieldsets?: AdminFieldset[];
78
+ fieldOrder?: string[];
79
+ readonlyFields?: string[];
80
+ excludeFields?: string[];
81
+ hiddenFields?: string[];
82
+ autocompleteFields?: string[];
83
+ fieldOverrides?: Record<string, AdminFieldOverride>;
84
+ adminPermissions?: Partial<{
85
+ create: PermissionMethod<unknown>[];
86
+ delete: PermissionMethod<unknown>[];
87
+ list: PermissionMethod<unknown>[];
88
+ read: PermissionMethod<unknown>[];
89
+ update: PermissionMethod<unknown>[];
90
+ }>;
91
+ adminFilter?: (req: express.Request) => Record<string, unknown> | Promise<Record<string, unknown>>;
92
+ actions?: AdminAction[];
93
+ /** When true, scrubbed `admin:model.changed` events fire after mutations (no socket transport). */
94
+ realtime?: boolean;
95
+ /** Forward-compat placeholder — no behavior in v1. */
96
+ includeDeleted?: boolean;
97
+ bulkPatchAllowlist?: string[];
98
+ recordTitleField?: string;
99
+ }
100
+ export interface AdminScriptContribution {
101
+ args?: ScriptArgDef[];
102
+ description: string;
103
+ name: string;
104
+ runner: ScriptRunner;
105
+ }
106
+ export interface AdminCustomScreen {
107
+ displayName: string;
108
+ group?: string;
109
+ icon?: string;
110
+ name: string;
111
+ }
112
+ export interface AdminHomeSlots {
113
+ contentTop?: string[];
114
+ main?: string[];
115
+ navGlobal?: string[];
116
+ sidebar?: string[];
117
+ }
118
+ export interface AdminHomeConfig {
119
+ slots?: AdminHomeSlots;
120
+ title?: string;
121
+ /** Legacy widget ids; normalized to `slots.main` by admin-backend when slots omitted. */
122
+ widgets?: string[];
123
+ }
124
+ export interface AdminHomeWidgetContribution {
125
+ displayName: string;
126
+ icon?: string;
127
+ id: string;
128
+ watches?: string[];
129
+ }
130
+ export interface AdminModelContribution<T = unknown> {
131
+ admin: AdminConfig;
132
+ model: Model<T>;
133
+ permissions?: RESTPermissions<T>;
134
+ populatePaths?: PopulatePath[];
135
+ routePath: string;
136
+ }
137
+ export interface AdminContribution {
138
+ customScreens?: AdminCustomScreen[];
139
+ homeWidgets?: AdminHomeWidgetContribution[];
140
+ models?: AdminModelContribution[];
141
+ scripts?: AdminScriptContribution[];
142
+ }
143
+ export type AdminChangeType = "create" | "delete" | "update";
144
+ export interface AdminChangeEvent {
145
+ at: string;
146
+ document?: unknown;
147
+ documentId: string;
148
+ modelName: string;
149
+ routePath: string;
150
+ type: AdminChangeType;
151
+ user: {
152
+ id: string;
153
+ };
154
+ }
155
+ export type AdminModelAdminMap = Record<string, AdminConfig>;
156
+ export type TerrenoAppAdminEvent = "admin:model.changed";
@@ -0,0 +1,5 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MAX_BULK_PATCH_IDS = void 0;
4
+ /** Server-side cap on bulk action id lists (v2 bulk-patch). */
5
+ exports.MAX_BULK_PATCH_IDS = 1000;
package/dist/api.d.ts CHANGED
@@ -1,10 +1,14 @@
1
1
  import express, { type NextFunction, type Request, type Response } from "express";
2
2
  import mongoose, { type Document, type Model } from "mongoose";
3
3
  import { type CollectionActionConfig, type InstanceActionConfig } from "./actions";
4
+ import { type ModelRouterBuildContext } from "./adminModelRouter";
5
+ import type { AdminConfig } from "./adminTypes";
4
6
  import { type User } from "./auth";
7
+ import type { MCPConfig } from "./mcp/types";
5
8
  import { type ModelRouterValidationOptions } from "./openApiValidator";
6
9
  import { type RESTPermissions } from "./permissions";
7
10
  import type { PopulatePath } from "./populate";
11
+ import type { AnyTerrenoAccess, ModelRouterAccessOptions } from "./rbac/types";
8
12
  import type { RealtimeConfig } from "./realtime/types";
9
13
  import type { SyncConfig } from "./sync/types";
10
14
  import { type TerrenoTransformer } from "./transformers";
@@ -52,8 +56,17 @@ export interface ModelRouterOptions<T> {
52
56
  * A group of method-level (create/read/update/delete/list) permissions.
53
57
  * Determine if the user can perform the operation at all, and for read/update/delete methods,
54
58
  * whether the user can perform the operation on the object referenced.
59
+ * @deprecated Use `access` with `accessControl` instead. Still required as a type-level
60
+ * fallback; `resolveModelRouterAccess` replaces these methods when `access` is set.
55
61
  * */
56
62
  permissions: RESTPermissions<T>;
63
+ /**
64
+ * RBAC access configuration for this router. Requires `accessControl` on the same options object
65
+ * or injected by TerrenoApp at build time.
66
+ */
67
+ access?: ModelRouterAccessOptions;
68
+ /** TerrenoAccess instance used to evaluate `access` permissions. */
69
+ accessControl?: AnyTerrenoAccess;
57
70
  /**
58
71
  * Allow anonymous users to access the resource.
59
72
  * Defaults to false.
@@ -243,6 +256,25 @@ export interface ModelRouterOptions<T> {
243
256
  * This option overrides the global setting for this specific router.
244
257
  */
245
258
  validation?: boolean | ModelRouterValidationOptions;
259
+ /**
260
+ * MCP (Model Context Protocol) configuration. When provided, registers this model's
261
+ * CRUD operations as MCP tools that can be called by LLMs.
262
+ *
263
+ * Tools are auto-generated based on the methods specified (default: ['list', 'read']).
264
+ * Auth, permissions, population, and filtering all work the same as REST.
265
+ *
266
+ * @example
267
+ * ```typescript
268
+ * modelRouter("/todos", Todo, {
269
+ * mcp: {
270
+ * methods: ['list', 'read', 'create'],
271
+ * excludeFields: ['internalNote'],
272
+ * maxLimit: 25,
273
+ * },
274
+ * });
275
+ * ```
276
+ */
277
+ mcp?: MCPConfig;
246
278
  /**
247
279
  * Enable real-time sync for this model via WebSocket events.
248
280
  * When configured, CRUD operations will emit events to connected clients
@@ -260,6 +292,11 @@ export interface ModelRouterOptions<T> {
260
292
  * Only works with the three-argument form: modelRouter('/path', Model, options).
261
293
  */
262
294
  sync?: SyncConfig;
295
+ /**
296
+ * Optional admin panel metadata for this model. Consumed by {@link AdminApp} when aggregating
297
+ * `/admin/config` and for server-side field scrubbing / realtime change events.
298
+ */
299
+ admin?: AdminConfig;
263
300
  }
264
301
  /**
265
302
  * Registration object returned by modelRouter when called with a path.
@@ -277,8 +314,12 @@ export interface ModelRouterRegistration {
277
314
  path: string;
278
315
  /** The Express router containing CRUD endpoints */
279
316
  router: express.Router;
280
- /** @internal Rebuilds the router with the openApi instance injected into options */
281
- _buildWithOpenApi: (openApi: OpenApiMiddleware) => express.Router;
317
+ /** The Mongoose model this router serves */
318
+ model: ModelLike<any>;
319
+ /** Options passed to modelRouter (includes optional admin config) */
320
+ options: ModelRouterOptions<any>;
321
+ /** @internal Rebuilds the router with OpenAPI and TerrenoApp context injected */
322
+ _buildWithContext: (context: ModelRouterBuildContext) => express.Router;
282
323
  }
283
324
  /**
284
325
  * Create a set of CRUD routes given a Mongoose model and configuration options.
@@ -353,4 +394,4 @@ type AsyncHandlerFn = (req: any, res: Response, next: NextFunction) => Promise<u
353
394
  export declare const asyncHandler: (fn: AsyncHandlerFn, options?: AsyncHandlerOptions) => (req: Request, res: Response, next: NextFunction) => void;
354
395
  export declare const gooseRestRouter: typeof modelRouter;
355
396
  export type GooseRESTOptions<T> = ModelRouterOptions<T>;
356
- export {};
397
+ export type { ModelRouterBuildContext } from "./adminModelRouter";