@terreno/api 57.0.0-beta.1 → 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
@@ -0,0 +1,246 @@
1
+ "use strict";
2
+ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
3
+ function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
4
+ return new (P || (P = Promise))(function (resolve, reject) {
5
+ function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
6
+ function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
7
+ function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
8
+ step((generator = generator.apply(thisArg, _arguments || [])).next());
9
+ });
10
+ };
11
+ var __generator = (this && this.__generator) || function (thisArg, body) {
12
+ 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);
13
+ return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
14
+ function verb(n) { return function (v) { return step([n, v]); }; }
15
+ function step(op) {
16
+ if (f) throw new TypeError("Generator is already executing.");
17
+ while (g && (g = 0, op[0] && (_ = 0)), _) try {
18
+ 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;
19
+ if (y = 0, t) op = [op[0] & 2, t.value];
20
+ switch (op[0]) {
21
+ case 0: case 1: t = op; break;
22
+ case 4: _.label++; return { value: op[1], done: false };
23
+ case 5: _.label++; y = op[1]; op = [0]; continue;
24
+ case 7: op = _.ops.pop(); _.trys.pop(); continue;
25
+ default:
26
+ if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
27
+ if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
28
+ if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
29
+ if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
30
+ if (t[2]) _.ops.pop();
31
+ _.trys.pop(); continue;
32
+ }
33
+ op = body.call(thisArg, _);
34
+ } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
35
+ if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
36
+ }
37
+ };
38
+ var __values = (this && this.__values) || function(o) {
39
+ var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
40
+ if (m) return m.call(o);
41
+ if (o && typeof o.length === "number") return {
42
+ next: function () {
43
+ if (o && i >= o.length) o = void 0;
44
+ return { value: o && o[i++], done: !o };
45
+ }
46
+ };
47
+ throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
48
+ };
49
+ var __read = (this && this.__read) || function (o, n) {
50
+ var m = typeof Symbol === "function" && o[Symbol.iterator];
51
+ if (!m) return o;
52
+ var i = m.call(o), r, ar = [], e;
53
+ try {
54
+ while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
55
+ }
56
+ catch (error) { e = { error: error }; }
57
+ finally {
58
+ try {
59
+ if (r && !r.done && (m = i["return"])) m.call(i);
60
+ }
61
+ finally { if (e) throw e.error; }
62
+ }
63
+ return ar;
64
+ };
65
+ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
66
+ if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
67
+ if (ar || !(i in from)) {
68
+ if (!ar) ar = Array.prototype.slice.call(from, 0, i);
69
+ ar[i] = from[i];
70
+ }
71
+ }
72
+ return to.concat(ar || Array.prototype.slice.call(from));
73
+ };
74
+ Object.defineProperty(exports, "__esModule", { value: true });
75
+ exports.getAllMCPTools = exports.generateAllTools = exports.generateToolsForEntry = void 0;
76
+ var zod_1 = require("zod");
77
+ var logger_1 = require("../logger");
78
+ var requestContext_1 = require("../requestContext");
79
+ var handlers_1 = require("./handlers");
80
+ var registry_1 = require("./registry");
81
+ var schemaGenerator_1 = require("./schemaGenerator");
82
+ var getToolPrefix = function (entry) {
83
+ if (entry.config.toolPrefix) {
84
+ return entry.config.toolPrefix;
85
+ }
86
+ // Default: lowercase model name with simple pluralization. Irregular nouns are expected
87
+ // to set config.toolPrefix rather than growing an exception list here.
88
+ var name = entry.modelName.toLowerCase();
89
+ if (/(?:s|x|z|ch|sh)$/.test(name)) {
90
+ return "".concat(name, "es");
91
+ }
92
+ if (name.endsWith("y") && !/[aeiou]y$/i.test(name)) {
93
+ return "".concat(name.slice(0, -1), "ies");
94
+ }
95
+ return "".concat(name, "s");
96
+ };
97
+ var METHOD_HANDLERS = {
98
+ create: handlers_1.handleCreate,
99
+ delete: handlers_1.handleDelete,
100
+ list: handlers_1.handleList,
101
+ read: handlers_1.handleRead,
102
+ update: handlers_1.handleUpdate,
103
+ };
104
+ var getToolErrorMessage = function (result) {
105
+ var _a;
106
+ var text = (_a = result.content[0]) === null || _a === void 0 ? void 0 : _a.text;
107
+ if (!text) {
108
+ return "Unknown MCP tool error";
109
+ }
110
+ try {
111
+ var parsed = JSON.parse(text);
112
+ return typeof parsed.error === "string" ? parsed.error : text;
113
+ }
114
+ catch (_b) {
115
+ return text;
116
+ }
117
+ };
118
+ var executeTool = function (_a) { return __awaiter(void 0, [_a], void 0, function (_b) {
119
+ var userId, log, startedAt, result, durationMs, cause, message, error_1, durationMs;
120
+ var _c;
121
+ var args = _b.args, entry = _b.entry, handler = _b.handler, method = _b.method, toolName = _b.toolName, user = _b.user;
122
+ return __generator(this, function (_d) {
123
+ switch (_d.label) {
124
+ case 0:
125
+ userId = (_c = user === null || user === void 0 ? void 0 : user.id) !== null && _c !== void 0 ? _c : ((user === null || user === void 0 ? void 0 : user._id) ? String(user._id) : undefined);
126
+ if (userId) {
127
+ (0, requestContext_1.setRequestContext)({ userId: userId });
128
+ }
129
+ log = (0, logger_1.createScopedLogger)({
130
+ labels: {
131
+ mcpMethod: method,
132
+ mcpModel: entry.modelName,
133
+ mcpTool: toolName,
134
+ },
135
+ prefix: "[MCPTool]",
136
+ });
137
+ startedAt = performance.now();
138
+ _d.label = 1;
139
+ case 1:
140
+ _d.trys.push([1, 3, , 4]);
141
+ return [4 /*yield*/, handler(entry, args, user)];
142
+ case 2:
143
+ result = _d.sent();
144
+ durationMs = Math.round(performance.now() - startedAt);
145
+ if (!result.isError) {
146
+ log.info("MCP tool call succeeded", { durationMs: durationMs });
147
+ return [2 /*return*/, result];
148
+ }
149
+ cause = (0, handlers_1.getMCPErrorCause)(result);
150
+ message = getToolErrorMessage(result);
151
+ if (cause !== undefined) {
152
+ // ScopedLogger.catch records the original exception and captures it in Sentry when enabled.
153
+ log.catch(cause);
154
+ log.error("MCP tool call failed", { durationMs: durationMs, message: message });
155
+ }
156
+ else {
157
+ // Permission, not-found, and input errors are expected failures: retain an audit trail
158
+ // and Sentry log without reporting them as exceptions.
159
+ log.warn("MCP tool call refused", { durationMs: durationMs, message: message });
160
+ }
161
+ return [2 /*return*/, result];
162
+ case 3:
163
+ error_1 = _d.sent();
164
+ durationMs = Math.round(performance.now() - startedAt);
165
+ log.catch(error_1);
166
+ log.error("MCP tool call crashed", { durationMs: durationMs });
167
+ throw error_1;
168
+ case 4: return [2 /*return*/];
169
+ }
170
+ });
171
+ }); };
172
+ var generateToolsForEntry = function (entry) {
173
+ var e_1, _a;
174
+ var _b, _c;
175
+ var methods = (_b = entry.config.methods) !== null && _b !== void 0 ? _b : ["list", "read"];
176
+ var prefix = getToolPrefix(entry);
177
+ var tools = [];
178
+ var _loop_1 = function (method) {
179
+ // Skip methods with empty permission arrays (disabled)
180
+ if (((_c = entry.options.permissions[method]) === null || _c === void 0 ? void 0 : _c.length) === 0) {
181
+ return "continue";
182
+ }
183
+ var restExcludeFields = (0, schemaGenerator_1.restWriteExcludeFields)(method, entry.options.validation);
184
+ var zodSchema = (0, schemaGenerator_1.generateInputSchema)(entry.model, method, entry.config, entry.options.queryFields, entry.options.populatePaths, restExcludeFields);
185
+ var inputSchema = (0, zod_1.toJSONSchema)(zodSchema);
186
+ var handler = METHOD_HANDLERS[method];
187
+ var toolName = "".concat(prefix, "_").concat(method);
188
+ tools.push({
189
+ description: (0, schemaGenerator_1.generateToolDescription)(entry.model, method, entry.config, entry.options.queryFields, entry.options.populatePaths, restExcludeFields),
190
+ handler: function (args, user) {
191
+ return executeTool({ args: args, entry: entry, handler: handler, method: method, toolName: toolName, user: user });
192
+ },
193
+ inputSchema: inputSchema,
194
+ name: toolName,
195
+ zodSchema: zodSchema,
196
+ });
197
+ };
198
+ try {
199
+ for (var methods_1 = __values(methods), methods_1_1 = methods_1.next(); !methods_1_1.done; methods_1_1 = methods_1.next()) {
200
+ var method = methods_1_1.value;
201
+ _loop_1(method);
202
+ }
203
+ }
204
+ catch (e_1_1) { e_1 = { error: e_1_1 }; }
205
+ finally {
206
+ try {
207
+ if (methods_1_1 && !methods_1_1.done && (_a = methods_1.return)) _a.call(methods_1);
208
+ }
209
+ finally { if (e_1) throw e_1.error; }
210
+ }
211
+ return tools;
212
+ };
213
+ exports.generateToolsForEntry = generateToolsForEntry;
214
+ var generateAllTools = function (entries) {
215
+ var e_2, _a;
216
+ var tools = [];
217
+ try {
218
+ for (var entries_1 = __values(entries), entries_1_1 = entries_1.next(); !entries_1_1.done; entries_1_1 = entries_1.next()) {
219
+ var entry = entries_1_1.value;
220
+ tools.push.apply(tools, __spreadArray([], __read((0, exports.generateToolsForEntry)(entry)), false));
221
+ }
222
+ }
223
+ catch (e_2_1) { e_2 = { error: e_2_1 }; }
224
+ finally {
225
+ try {
226
+ if (entries_1_1 && !entries_1_1.done && (_a = entries_1.return)) _a.call(entries_1);
227
+ }
228
+ finally { if (e_2) throw e_2.error; }
229
+ }
230
+ return tools;
231
+ };
232
+ exports.generateAllTools = generateAllTools;
233
+ /** Model-router tools plus any custom tools registered with `registerMCPTool`. */
234
+ var getAllMCPTools = function () {
235
+ var customTools = (0, registry_1.getMCPCustomTools)().map(function (tool) {
236
+ return {
237
+ description: tool.description,
238
+ handler: tool.handler,
239
+ inputSchema: (0, zod_1.toJSONSchema)(tool.zodSchema),
240
+ name: tool.name,
241
+ zodSchema: tool.zodSchema,
242
+ };
243
+ });
244
+ return __spreadArray(__spreadArray([], __read((0, exports.generateAllTools)((0, registry_1.getMCPRegistry)())), false), __read(customTools), false);
245
+ };
246
+ exports.getAllMCPTools = getAllMCPTools;
@@ -0,0 +1,85 @@
1
+ import type { HydratedDocument, Model } from "mongoose";
2
+ import type { JSONValue, ModelRouterOptions } from "../api";
3
+ import type { User } from "../auth";
4
+ export type MCPMethod = "create" | "list" | "read" | "update" | "delete";
5
+ /** Arguments an MCP client sends for a tool call, validated against the tool's Zod schema. */
6
+ export type MCPToolArgs = Record<string, unknown>;
7
+ /**
8
+ * The MCP content payload returned by every tool handler. The index signature keeps this
9
+ * structurally compatible with the MCP SDK's CallToolResult, which allows extra fields.
10
+ */
11
+ export interface MCPToolResult {
12
+ content: Array<{
13
+ type: "text";
14
+ text: string;
15
+ }>;
16
+ isError?: boolean;
17
+ [key: string]: unknown;
18
+ }
19
+ /** JSON Schema emitted for a tool's inputs, as sent to MCP clients. */
20
+ export interface MCPToolInputSchema {
21
+ type?: string;
22
+ properties?: Record<string, unknown>;
23
+ required?: string[];
24
+ [key: string]: unknown;
25
+ }
26
+ /**
27
+ * A hydrated document from a consumer's model. The concrete field types are only known
28
+ * at runtime, so handlers work against the Mongoose document API plus an index signature.
29
+ */
30
+ export type MCPDocument = HydratedDocument<Record<string, unknown>>;
31
+ /**
32
+ * Express-shaped request handed to modelRouter lifecycle hooks and response handlers
33
+ * during an MCP tool call. Built by `createMCPRequest` as a stub: only `user`
34
+ * and `body` are populated. `headers`, `query`, and `params` are always empty
35
+ * objects — MCP does not forward HTTP request fields.
36
+ */
37
+ export interface MCPRequest {
38
+ body: MCPToolArgs;
39
+ /** Always `{}` on MCP paths — not forwarded from HTTP. */
40
+ headers: Record<string, string>;
41
+ /** Lets hooks detect an MCP tool call rather than an HTTP request. */
42
+ isMCPRequest: true;
43
+ method: "MCP";
44
+ params: Record<string, string>;
45
+ query: Record<string, unknown>;
46
+ user?: User;
47
+ }
48
+ export interface MCPConfig {
49
+ /** Which CRUD methods to expose as MCP tools. Default: ['list', 'read'] */
50
+ methods?: MCPMethod[];
51
+ /** Override auto-generated model description */
52
+ description?: string;
53
+ /**
54
+ * Override the tool name prefix. Tools are named `{prefix}_{method}`, e.g. `todos_list`.
55
+ *
56
+ * Defaults to the lowercase model name run through a simple English pluralizer, which
57
+ * gets common cases right (`Todo` -> `todos`, `Category` -> `categories`, `Status` ->
58
+ * `statuses`) but not irregular nouns. Set this explicitly whenever the default reads
59
+ * wrong, or to namespace tools that would otherwise collide.
60
+ *
61
+ * @example
62
+ * ```typescript
63
+ * mcp: {toolPrefix: "people"} // person_list -> people_list
64
+ * ```
65
+ */
66
+ toolPrefix?: string;
67
+ /**
68
+ * Fields to hide from MCP tool schemas, responses, and create/update persist bodies.
69
+ *
70
+ * A bare field name (`"hash"`) is removed at every depth of the response, including
71
+ * inside arrays and populated refs, so a redacted name cannot leak through a nested
72
+ * document. Use dot notation (`"metadata.secretKey"`) to remove one specific location.
73
+ */
74
+ excludeFields?: string[];
75
+ /** Max items returned by list tool (default: 50) */
76
+ maxLimit?: number;
77
+ /** MCP-specific serialization (separate from REST responseHandler) */
78
+ mcpResponseHandler?: (value: unknown, method: MCPMethod, user?: User) => Promise<JSONValue>;
79
+ }
80
+ export interface MCPRegistryEntry {
81
+ modelName: string;
82
+ model: Model<any>;
83
+ config: MCPConfig;
84
+ options: ModelRouterOptions<any>;
85
+ }
@@ -0,0 +1,2 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
package/dist/openApi.d.ts CHANGED
@@ -54,7 +54,7 @@ export declare const defaultOpenApiErrorResponses: {
54
54
  };
55
55
  };
56
56
  export declare const getOpenApiMiddleware: <T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>) => express.RequestHandler;
57
- export declare const listOpenApiMiddleware: <T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>) => express.RequestHandler;
57
+ export declare const listOpenApiMiddleware: <T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>, routePath?: string) => express.RequestHandler;
58
58
  export declare const createOpenApiMiddleware: <T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>) => express.RequestHandler;
59
59
  export declare const patchOpenApiMiddleware: <T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>) => express.RequestHandler;
60
60
  export declare const deleteOpenApiMiddleware: <T>(model: Model<T>, options: Partial<ModelRouterOptions<T>>) => express.RequestHandler;
package/dist/openApi.js CHANGED
@@ -171,7 +171,29 @@ var getOpenApiMiddleware = function (model, options) {
171
171
  }, (_g = (_f = options.openApiOverwrite) === null || _f === void 0 ? void 0 : _f.get) !== null && _g !== void 0 ? _g : {}));
172
172
  };
173
173
  exports.getOpenApiMiddleware = getOpenApiMiddleware;
174
- var listOpenApiMiddleware = function (model, options) {
174
+ var resolveSyncScopeLabel = function (scope) {
175
+ if (typeof scope === "function") {
176
+ return "custom";
177
+ }
178
+ return scope.type;
179
+ };
180
+ var buildTerrenoSyncExtension = function (sync, routePath, fallbackCollection) {
181
+ if (!sync) {
182
+ return {};
183
+ }
184
+ var rawPath = routePath !== null && routePath !== void 0 ? routePath : (fallbackCollection ? "/".concat(fallbackCollection) : undefined);
185
+ if (!rawPath) {
186
+ return {};
187
+ }
188
+ var collection = rawPath.replace(/^\//, "");
189
+ return {
190
+ "x-terreno-sync": {
191
+ collection: collection,
192
+ scope: resolveSyncScopeLabel(sync.scope),
193
+ },
194
+ };
195
+ };
196
+ var listOpenApiMiddleware = function (model, options, routePath) {
175
197
  var _c, _d, _e, _f, _g, _h;
176
198
  if (!((_c = options.openApi) === null || _c === void 0 ? void 0 : _c.path)) {
177
199
  return noop;
@@ -252,8 +274,7 @@ var listOpenApiMiddleware = function (model, options) {
252
274
  extraModelProperties: options.openApiExtraModelProperties,
253
275
  populatePaths: options.populatePaths,
254
276
  }), properties = _j.properties, required = _j.required;
255
- return options.openApi.path((0, merge_1.default)({
256
- parameters: __spreadArray(__spreadArray(__spreadArray([], __read(defaultQueryParams), false), __read((modelQueryParams !== null && modelQueryParams !== void 0 ? modelQueryParams : [])), false), [
277
+ return options.openApi.path((0, merge_1.default)(__assign(__assign({}, buildTerrenoSyncExtension(options.sync, routePath, model.collection.collectionName)), { parameters: __spreadArray(__spreadArray(__spreadArray([], __read(defaultQueryParams), false), __read((modelQueryParams !== null && modelQueryParams !== void 0 ? modelQueryParams : [])), false), [
257
278
  // pagination
258
279
  {
259
280
  in: "query",
@@ -276,8 +297,7 @@ var listOpenApiMiddleware = function (model, options) {
276
297
  type: "number",
277
298
  },
278
299
  },
279
- ], false),
280
- responses: __assign({ 200: {
300
+ ], false), responses: __assign({ 200: {
281
301
  content: {
282
302
  "application/json": {
283
303
  schema: {
@@ -308,9 +328,7 @@ var listOpenApiMiddleware = function (model, options) {
308
328
  },
309
329
  },
310
330
  description: "Successful list",
311
- } }, exports.defaultOpenApiErrorResponses),
312
- tags: [model.collection.collectionName],
313
- }, (_h = (_g = options.openApiOverwrite) === null || _g === void 0 ? void 0 : _g.list) !== null && _h !== void 0 ? _h : {}));
331
+ } }, exports.defaultOpenApiErrorResponses), tags: [model.collection.collectionName] }), (_h = (_g = options.openApiOverwrite) === null || _g === void 0 ? void 0 : _g.list) !== null && _h !== void 0 ? _h : {}));
314
332
  };
315
333
  exports.listOpenApiMiddleware = listOpenApiMiddleware;
316
334
  var createOpenApiMiddleware = function (model, options) {
@@ -195,17 +195,17 @@ exports.checkPermissions = checkPermissions;
195
195
  // req.obj.
196
196
  var permissionMiddleware = function (model, options) {
197
197
  return function (req, _res, next) { return __awaiter(void 0, void 0, void 0, function () {
198
- var method, reqMethod, data, error_1;
199
- var _a, _b;
200
- return __generator(this, function (_c) {
201
- switch (_c.label) {
198
+ var method, reqMethod, methodPermissions, data, error_1;
199
+ var _a, _b, _c, _d;
200
+ return __generator(this, function (_e) {
201
+ switch (_e.label) {
202
202
  case 0:
203
203
  if (req.method === "OPTIONS") {
204
204
  return [2 /*return*/, next()];
205
205
  }
206
- _c.label = 1;
206
+ _e.label = 1;
207
207
  case 1:
208
- _c.trys.push([1, 5, , 6]);
208
+ _e.trys.push([1, 5, , 6]);
209
209
  method = void 0;
210
210
  reqMethod = req.method.toLowerCase();
211
211
  if (reqMethod === "post") {
@@ -231,14 +231,14 @@ var permissionMiddleware = function (model, options) {
231
231
  title: "Method ".concat(req.method, " not allowed"),
232
232
  });
233
233
  }
234
- return [4 /*yield*/, (0, exports.checkPermissions)(method, options.permissions[method], req.user)];
234
+ methodPermissions = (_b = (_a = options.permissions) === null || _a === void 0 ? void 0 : _a[method]) !== null && _b !== void 0 ? _b : [];
235
+ return [4 /*yield*/, (0, exports.checkPermissions)(method, methodPermissions, req.user)];
235
236
  case 2:
236
- // All methods check for permissions.
237
- if (!(_c.sent())) {
237
+ if (!(_e.sent())) {
238
238
  throw new errors_1.APIError({
239
239
  status: 405,
240
240
  title: "Access to ".concat(method.toUpperCase(), " on ").concat(model.modelName, " ") +
241
- "denied for ".concat((_a = req.user) === null || _a === void 0 ? void 0 : _a.id),
241
+ "denied for ".concat((_c = req.user) === null || _c === void 0 ? void 0 : _c.id),
242
242
  });
243
243
  }
244
244
  if (method === "create" || method === "list") {
@@ -246,19 +246,19 @@ var permissionMiddleware = function (model, options) {
246
246
  }
247
247
  return [4 /*yield*/, (0, docLoader_1.loadDocOr404)(model, req.params.id, options.populatePaths)];
248
248
  case 3:
249
- data = _c.sent();
250
- return [4 /*yield*/, (0, exports.checkPermissions)(method, options.permissions[method], req.user, data)];
249
+ data = _e.sent();
250
+ return [4 /*yield*/, (0, exports.checkPermissions)(method, methodPermissions, req.user, data)];
251
251
  case 4:
252
- if (!(_c.sent())) {
252
+ if (!(_e.sent())) {
253
253
  throw new errors_1.APIError({
254
254
  status: 403,
255
- title: "Access to GET on ".concat(model.modelName, ":").concat(req.params.id, " denied for ").concat((_b = req.user) === null || _b === void 0 ? void 0 : _b.id),
255
+ title: "Access to GET on ".concat(model.modelName, ":").concat(req.params.id, " denied for ").concat((_d = req.user) === null || _d === void 0 ? void 0 : _d.id),
256
256
  });
257
257
  }
258
258
  req.obj = data;
259
259
  return [2 /*return*/, next()];
260
260
  case 5:
261
- error_1 = _c.sent();
261
+ error_1 = _e.sent();
262
262
  return [2 /*return*/, next(error_1)];
263
263
  case 6: return [2 /*return*/];
264
264
  }
@@ -0,0 +1,3 @@
1
+ import { type Statements } from "./statements";
2
+ import type { AccessOptions, TerrenoAccess } from "./types";
3
+ export declare const createAccess: <S extends Statements>(options: AccessOptions<S>) => TerrenoAccess<S>;