@terreno/admin-backend 56.0.0-beta.0 → 57.0.0-beta.1

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Flourish Health, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,5 +1,60 @@
1
1
  # @terreno/admin-backend
2
2
 
3
- Admin panel backend plugin for `@terreno/api` that auto-generates admin CRUD endpoints for Mongoose models.
3
+ Admin panel backend plugin for `@terreno/api` that auto-generates admin CRUD endpoints and metadata for Mongoose models.
4
4
 
5
- See the [full documentation](../.claude/rules/admin-backend/00-admin-backend.md) for usage, configuration, and integration details.
5
+ ## Install
6
+
7
+ ```bash
8
+ bun add @terreno/admin-backend @terreno/api mongoose
9
+ ```
10
+
11
+ ## Quick start
12
+
13
+ ```typescript
14
+ import {TerrenoApp} from "@terreno/api";
15
+ import {AdminApp} from "@terreno/admin-backend";
16
+ import {User, Todo} from "./models";
17
+
18
+ new TerrenoApp({userModel: User})
19
+ .register(
20
+ new AdminApp({
21
+ basePath: "/admin",
22
+ models: [
23
+ {
24
+ model: User,
25
+ routePath: "/users",
26
+ displayName: "Users",
27
+ listFields: ["email", "name", "admin"],
28
+ defaultSort: "-created",
29
+ },
30
+ {
31
+ model: Todo,
32
+ routePath: "/todos",
33
+ displayName: "Todos",
34
+ listFields: ["title", "completed", "ownerId"],
35
+ },
36
+ ],
37
+ })
38
+ )
39
+ .start();
40
+ ```
41
+
42
+ This creates `GET /admin/config` plus full CRUD at `/admin/users` and `/admin/todos`, all protected with `Permissions.IsAdmin`.
43
+
44
+ ## What's included
45
+
46
+ - `AdminApp` — registers admin routes and the config metadata endpoint
47
+ - `DocumentStorageApp` — optional GCS document browser routes for admins
48
+ - `runScriptCli` — CLI helper for admin script execution
49
+ - Auto-generated CRUD via `modelRouter` with `IsAdmin` on every route
50
+ - `GET /admin/config` — field metadata extracted from Mongoose schemas and OpenAPI
51
+ - Admin UI v2 route helpers (`adminUiV2` exports)
52
+ - TypeScript types: `AdminModelConfig`, `AdminOptions`, `AdminFieldOverride`, and more
53
+
54
+ ## Documentation
55
+
56
+ Full API reference: [docs/reference/admin-backend.md](https://github.com/flourishhealth/terreno/blob/master/docs/reference/admin-backend.md)
57
+
58
+ ## License and Contributing
59
+
60
+ Licensed under the [MIT License](https://github.com/flourishhealth/terreno/blob/master/LICENSE). See [CONTRIBUTING.md](https://github.com/flourishhealth/terreno/blob/master/CONTRIBUTING.md) for contribution guidelines.
@@ -1,6 +1,7 @@
1
1
  import { type PopulatePath, type ScriptArgDef, type ScriptRunner, type User } from "@terreno/api";
2
2
  import express from "express";
3
3
  import type { Model } from "mongoose";
4
+ import mongoose from "mongoose";
4
5
  import { type AdminActionInput, type AdminFieldsetInput, type AdminHomeInput, type AdminListFilter, type AdminModelPermissionsInput } from "./adminUiV2";
5
6
  /**
6
7
  * Configuration for a single model in the admin panel.
@@ -127,6 +128,7 @@ export interface AdminOptions {
127
128
  */
128
129
  onAdminAudit?: (event: AdminAuditEvent, req: express.Request) => void | Promise<void>;
129
130
  }
131
+ export declare const getArrayEmbeddedSchemaType: (schemaPath: mongoose.SchemaType) => mongoose.SchemaType | undefined;
130
132
  /**
131
133
  * TerrenoPlugin that auto-generates admin CRUD endpoints for Mongoose models.
132
134
  *
package/dist/adminApp.js CHANGED
@@ -86,7 +86,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
86
86
  return (mod && mod.__esModule) ? mod : { "default": mod };
87
87
  };
88
88
  Object.defineProperty(exports, "__esModule", { value: true });
89
- exports.AdminApp = void 0;
89
+ exports.AdminApp = exports.getArrayEmbeddedSchemaType = void 0;
90
90
  var api_1 = require("@terreno/api");
91
91
  var express_1 = __importDefault(require("express"));
92
92
  var luxon_1 = require("luxon");
@@ -167,6 +167,14 @@ var auditActorId = function (request) {
167
167
  }
168
168
  return String(user._id);
169
169
  };
170
+ var getArrayEmbeddedSchemaType = function (schemaPath) {
171
+ var compatiblePath = schemaPath;
172
+ if (typeof compatiblePath.getEmbeddedSchemaType === "function") {
173
+ return compatiblePath.getEmbeddedSchemaType();
174
+ }
175
+ return compatiblePath.caster;
176
+ };
177
+ exports.getArrayEmbeddedSchemaType = getArrayEmbeddedSchemaType;
170
178
  var extractFieldMeta = function (properties, required) {
171
179
  var e_3, _a;
172
180
  var _b, _c, _d;
@@ -349,11 +357,10 @@ var AdminApp = /** @class */ (function () {
349
357
  if (Array.isArray(pathOptions === null || pathOptions === void 0 ? void 0 : pathOptions.type) && ((_d = pathOptions.type[0]) === null || _d === void 0 ? void 0 : _d.ref)) {
350
358
  field.ref = pathOptions.type[0].ref;
351
359
  }
352
- // For arrays, use the caster to infer the primitive item type/ref.
353
- // Mongoose caster.instance is "String" | "Number" | "Boolean" | "ObjectID".
360
+ // For arrays, use the public embedded schema type to infer the primitive item type/ref.
354
361
  if (schemaPath.instance === "Array") {
355
- var caster = schemaPath.caster;
356
- if ((caster === null || caster === void 0 ? void 0 : caster.instance) && !field.items) {
362
+ var embeddedSchemaType = (0, exports.getArrayEmbeddedSchemaType)(schemaPath);
363
+ if ((embeddedSchemaType === null || embeddedSchemaType === void 0 ? void 0 : embeddedSchemaType.instance) && !field.items) {
357
364
  var instanceToType = {
358
365
  Boolean: "boolean",
359
366
  Number: "number",
@@ -362,15 +369,15 @@ var AdminApp = /** @class */ (function () {
362
369
  SchemaObjectId: "objectid",
363
370
  String: "string",
364
371
  };
365
- var mapped = instanceToType[caster.instance];
372
+ var mapped = instanceToType[embeddedSchemaType.instance];
366
373
  if (mapped) {
367
374
  field.itemType = mapped;
368
375
  }
369
- if ((_e = caster.options) === null || _e === void 0 ? void 0 : _e.ref) {
370
- field.itemRef = caster.options.ref;
376
+ if ((_e = embeddedSchemaType.options) === null || _e === void 0 ? void 0 : _e.ref) {
377
+ field.itemRef = embeddedSchemaType.options.ref;
371
378
  }
372
- if ((_f = caster.options) === null || _f === void 0 ? void 0 : _f.enum) {
373
- field.itemEnum = caster.options.enum;
379
+ if (Array.isArray((_f = embeddedSchemaType.options) === null || _f === void 0 ? void 0 : _f.enum)) {
380
+ field.itemEnum = embeddedSchemaType.options.enum;
374
381
  }
375
382
  }
376
383
  }
@@ -664,7 +671,7 @@ var AdminApp = /** @class */ (function () {
664
671
  updateOp.$unset = unsetFields;
665
672
  }
666
673
  return [4 /*yield*/, api_1.VersionConfig.findOneAndUpdate({ _singleton: "config" }, updateOp, {
667
- new: true,
674
+ returnDocument: "after",
668
675
  runValidators: true,
669
676
  setDefaultsOnInsert: true,
670
677
  upsert: true,
@@ -1413,7 +1420,7 @@ var AdminApp = /** @class */ (function () {
1413
1420
  completedAt: luxon_1.DateTime.now().toJSDate(),
1414
1421
  status: "cancelled",
1415
1422
  },
1416
- }, { new: true })];
1423
+ }, { returnDocument: "after" })];
1417
1424
  case 5:
1418
1425
  cancelled = _b.sent();
1419
1426
  if (!cancelled) {
package/package.json CHANGED
@@ -5,7 +5,7 @@
5
5
  },
6
6
  "dependencies": {
7
7
  "@google-cloud/storage": "^7.15.0",
8
- "@terreno/api": "56.0.0-beta.0",
8
+ "@terreno/api": "57.0.0-beta.1",
9
9
  "express": "^5.2.1",
10
10
  "luxon": "^3.7.2",
11
11
  "multer": "2.2.0"
@@ -13,7 +13,7 @@
13
13
  "description": "Admin panel backend plugin for @terreno/api",
14
14
  "devDependencies": {
15
15
  "@biomejs/biome": "^2.3.6",
16
- "@terreno/test": "56.0.0-beta.0",
16
+ "@terreno/test": "57.0.0-beta.1",
17
17
  "@types/bun": "^1.3.8",
18
18
  "@types/express": "^5.0.6",
19
19
  "@types/luxon": "^3.7.1",
@@ -30,9 +30,9 @@
30
30
  "express",
31
31
  "terreno"
32
32
  ],
33
- "license": "Apache-2.0",
33
+ "license": "MIT",
34
34
  "peerDependencies": {
35
- "mongoose": ">=8.0.0"
35
+ "mongoose": "^8.0.0 || ^9.0.0"
36
36
  },
37
37
  "main": "dist/index.js",
38
38
  "name": "@terreno/admin-backend",
@@ -54,5 +54,5 @@
54
54
  "test:coverage": "bun run ../scripts/check-coverage.ts"
55
55
  },
56
56
  "types": "dist/index.d.ts",
57
- "version": "56.0.0-beta.0"
57
+ "version": "57.0.0-beta.1"
58
58
  }
@@ -17,11 +17,12 @@ import {
17
17
  UserModel,
18
18
  } from "@terreno/api/testing";
19
19
  import type express from "express";
20
+ import mongoose from "mongoose";
20
21
  import supertest from "supertest";
21
22
  import type TestAgent from "supertest/lib/agent";
22
23
 
23
24
  import type {AdminAuditEvent, AdminModelConfig, AdminOptions} from "./adminApp";
24
- import {AdminApp} from "./adminApp";
25
+ import {AdminApp, getArrayEmbeddedSchemaType} from "./adminApp";
25
26
 
26
27
  const buildApp = (
27
28
  models: AdminModelConfig[] = [],
@@ -51,6 +52,24 @@ const foodModelConfig: AdminModelConfig = {
51
52
  routePath: "/foods",
52
53
  };
53
54
 
55
+ const enumArraySchema = new mongoose.Schema({
56
+ values: {
57
+ description: "Allowed enum values",
58
+ type: [{enum: ["alpha", "beta"], type: String}],
59
+ },
60
+ });
61
+ const EnumArrayModel =
62
+ mongoose.models.AdminEnumArray ?? mongoose.model("AdminEnumArray", enumArraySchema);
63
+
64
+ describe("getArrayEmbeddedSchemaType", () => {
65
+ it("supports the legacy Mongoose 8 caster property", () => {
66
+ const embeddedSchemaType = new mongoose.Schema({value: String}).path("value");
67
+ const legacyArrayPath = {caster: embeddedSchemaType} as unknown as mongoose.SchemaType;
68
+
69
+ expect(getArrayEmbeddedSchemaType(legacyArrayPath)).toBe(embeddedSchemaType);
70
+ });
71
+ });
72
+
54
73
  describe("AdminApp /admin/config", () => {
55
74
  let app: express.Application;
56
75
  let adminAgent: TestAgent;
@@ -150,6 +169,20 @@ describe("AdminApp /admin/config", () => {
150
169
  expect(foodMeta.fields.tags.items).toBeUndefined();
151
170
  });
152
171
 
172
+ it("extracts itemEnum for enum arrays", async () => {
173
+ const enumApp = buildApp([
174
+ {
175
+ displayName: "Enum arrays",
176
+ listFields: ["values"],
177
+ model: EnumArrayModel,
178
+ routePath: "/enum-arrays",
179
+ },
180
+ ]);
181
+ const enumAgent = await authAsUser(enumApp, "admin");
182
+ const res = await enumAgent.get("/admin/config").expect(200);
183
+ expect(res.body.models[0].fields.values.itemEnum).toEqual(["alpha", "beta"]);
184
+ });
185
+
153
186
  it("extracts itemType and itemRef for arrays of ObjectId references", async () => {
154
187
  const res = await adminAgent.get("/admin/config").expect(200);
155
188
  const [foodMeta] = res.body.models;
package/src/adminApp.ts CHANGED
@@ -319,6 +319,21 @@ interface OpenApiProperty {
319
319
  };
320
320
  }
321
321
 
322
+ interface ArraySchemaTypeCompatibility {
323
+ caster?: mongoose.SchemaType;
324
+ getEmbeddedSchemaType?: () => mongoose.SchemaType | undefined;
325
+ }
326
+
327
+ export const getArrayEmbeddedSchemaType = (
328
+ schemaPath: mongoose.SchemaType
329
+ ): mongoose.SchemaType | undefined => {
330
+ const compatiblePath = schemaPath as mongoose.SchemaType & ArraySchemaTypeCompatibility;
331
+ if (typeof compatiblePath.getEmbeddedSchemaType === "function") {
332
+ return compatiblePath.getEmbeddedSchemaType();
333
+ }
334
+ return compatiblePath.caster;
335
+ };
336
+
322
337
  const extractFieldMeta = (
323
338
  properties: Record<string, OpenApiProperty>,
324
339
  required: string[]
@@ -493,15 +508,10 @@ export class AdminApp {
493
508
  if (Array.isArray(pathOptions?.type) && pathOptions.type[0]?.ref) {
494
509
  field.ref = pathOptions.type[0].ref;
495
510
  }
496
- // For arrays, use the caster to infer the primitive item type/ref.
497
- // Mongoose caster.instance is "String" | "Number" | "Boolean" | "ObjectID".
511
+ // For arrays, use the public embedded schema type to infer the primitive item type/ref.
498
512
  if (schemaPath.instance === "Array") {
499
- const caster = (
500
- schemaPath as unknown as {
501
- caster?: {instance?: string; options?: {ref?: string; enum?: string[]}};
502
- }
503
- ).caster;
504
- if (caster?.instance && !field.items) {
513
+ const embeddedSchemaType = getArrayEmbeddedSchemaType(schemaPath);
514
+ if (embeddedSchemaType?.instance && !field.items) {
505
515
  const instanceToType: Record<string, string> = {
506
516
  Boolean: "boolean",
507
517
  Number: "number",
@@ -510,15 +520,15 @@ export class AdminApp {
510
520
  SchemaObjectId: "objectid",
511
521
  String: "string",
512
522
  };
513
- const mapped = instanceToType[caster.instance];
523
+ const mapped = instanceToType[embeddedSchemaType.instance];
514
524
  if (mapped) {
515
525
  field.itemType = mapped;
516
526
  }
517
- if (caster.options?.ref) {
518
- field.itemRef = caster.options.ref;
527
+ if (embeddedSchemaType.options?.ref) {
528
+ field.itemRef = embeddedSchemaType.options.ref;
519
529
  }
520
- if (caster.options?.enum) {
521
- field.itemEnum = caster.options.enum;
530
+ if (Array.isArray(embeddedSchemaType.options?.enum)) {
531
+ field.itemEnum = embeddedSchemaType.options.enum;
522
532
  }
523
533
  }
524
534
  }
@@ -797,7 +807,7 @@ export class AdminApp {
797
807
  updateOp.$unset = unsetFields;
798
808
  }
799
809
  const doc = await VersionConfig.findOneAndUpdate({_singleton: "config"}, updateOp, {
800
- new: true,
810
+ returnDocument: "after",
801
811
  runValidators: true,
802
812
  setDefaultsOnInsert: true,
803
813
  upsert: true,
@@ -1383,7 +1393,7 @@ export class AdminApp {
1383
1393
  status: "cancelled",
1384
1394
  },
1385
1395
  },
1386
- {new: true}
1396
+ {returnDocument: "after"}
1387
1397
  );
1388
1398
 
1389
1399
  if (!cancelled) {