@terreno/api 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.16.0
+
+### Added
+
+- **modelRouter actions** — Declare `instanceActions` and `collectionActions` on `ModelRouterOptions` for named operations at `/resource/:id/action` and `/resource/action`. Handlers receive `{req, res, user, doc?, body, query}`; return values are wrapped in `{data: ...}`. OpenAPI operations are emitted automatically when `openApi` is configured.
+- **`loadDocOr404`** — Shared document loader used by permission middleware and instance actions (soft-delete-aware 404 metadata preserved).
+
+### Changed
+
+- Permission middleware doc loading now delegates to `loadDocOr404` (behavior-preserving).
+
+### Dependencies
+
+- Added `@asteasolutions/zod-to-openapi` ^8.5.0 (direct dependency).
+- Added **`zod` ^4.3.6 as a peer dependency** — backends that define action Zod schemas must install `zod`.
+
+### Migration
+
+- Regenerate frontend SDKs after adding actions; `operationId` values follow `{tag}_{actionName}` (e.g. `todos_markComplete`).

package/dist/actions.d.ts

@@ -0,0 +1,55 @@
+import type express from "express";
+import type { Request, Response } from "express";
+import type { Model } from "mongoose";
+import type { ZodSchema } from "zod";
+import { type ModelRouterOptions } from "./api";
+import { type User } from "./auth";
+import { type PermissionMethod } from "./permissions";
+export declare const ACTION_NAME_PATTERN: RegExp;
+export interface ActionContext<TDoc, TBody, TQuery> {
+    req: Request;
+    res: Response;
+    user: User | undefined;
+    body: TBody;
+    query: TQuery;
+    doc: TDoc;
+}
+interface BaseActionConfig<TBody, TQuery, TResponse> {
+    method: "GET" | "POST";
+    permissions: PermissionMethod<unknown>[];
+    body?: ZodSchema<TBody>;
+    query?: ZodSchema<TQuery>;
+    response?: ZodSchema<TResponse>;
+    summary?: string;
+    description?: string;
+    tag?: string;
+    status?: number;
+}
+export interface InstanceActionConfig<TDoc, TBody, TQuery, TResponse> extends BaseActionConfig<TBody, TQuery, TResponse> {
+    handler: (ctx: ActionContext<TDoc, TBody, TQuery>) => TResponse | Promise<TResponse>;
+}
+export interface CollectionActionConfig<TBody, TQuery, TResponse> extends BaseActionConfig<TBody, TQuery, TResponse> {
+    handler: (ctx: Omit<ActionContext<never, TBody, TQuery>, "doc">) => TResponse | Promise<TResponse>;
+}
+export declare const defineInstanceAction: <TDoc, TBody = unknown, TQuery = unknown, TResponse = unknown>(config: InstanceActionConfig<TDoc, TBody, TQuery, TResponse>) => InstanceActionConfig<TDoc, TBody, TQuery, TResponse>;
+export declare const defineCollectionAction: <TBody = unknown, TQuery = unknown, TResponse = unknown>(config: CollectionActionConfig<TBody, TQuery, TResponse>) => CollectionActionConfig<TBody, TQuery, TResponse>;
+type ActionScope = "instance" | "collection";
+export declare const runActionPermissions: <T>(action: BaseActionConfig<unknown, unknown, unknown>, scope: ActionScope, model: Model<T>, req: Request, doc?: T) => Promise<void>;
+export declare const validateActionRequest: <TBody, TQuery>({ action, req, }: {
+    action: BaseActionConfig<TBody, TQuery, unknown>;
+    req: Request;
+}) => {
+    body: TBody | undefined;
+    query: TQuery | undefined;
+};
+export declare const wrapActionResponse: (handlerResult: unknown, action: BaseActionConfig<unknown, unknown, unknown>, res: Response) => void;
+export declare const createActionOpenApiMiddleware: <T>({ action, scope, actionName, model, options, }: {
+    action: BaseActionConfig<unknown, unknown, unknown>;
+    scope: ActionScope;
+    actionName: string;
+    model: Model<T>;
+    options: Partial<ModelRouterOptions<T>>;
+}) => express.RequestHandler;
+export declare const assertNoActionCollisions: <T>(model: Model<T>, options: Pick<ModelRouterOptions<T>, "instanceActions" | "collectionActions">) => void;
+export declare const registerActionRoutes: <T>(router: express.Router, model: Model<T>, options: Partial<ModelRouterOptions<T>>) => void;
+export {};

package/dist/actions.js

@@ -0,0 +1,472 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    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);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            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;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerActionRoutes = exports.assertNoActionCollisions = exports.createActionOpenApiMiddleware = exports.wrapActionResponse = exports.validateActionRequest = exports.runActionPermissions = exports.defineCollectionAction = exports.defineInstanceAction = exports.ACTION_NAME_PATTERN = void 0;
+var zod_to_openapi_1 = require("@asteasolutions/zod-to-openapi");
+var api_1 = require("./api");
+var auth_1 = require("./auth");
+var docLoader_1 = require("./docLoader");
+var errors_1 = require("./errors");
+var openApi_1 = require("./openApi");
+var permissions_1 = require("./permissions");
+// At least two characters: leading letter plus one or more alphanumeric/_/- chars.
+exports.ACTION_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9_-]+$/;
+var defineInstanceAction = function (config) {
+    return config;
+};
+exports.defineInstanceAction = defineInstanceAction;
+var defineCollectionAction = function (config) {
+    return config;
+};
+exports.defineCollectionAction = defineCollectionAction;
+var mapActionToCrudMethod = function (scope, httpMethod) {
+    if (scope === "instance") {
+        return httpMethod === "GET" ? "read" : "update";
+    }
+    return httpMethod === "GET" ? "list" : "create";
+};
+var runActionPermissions = function (action, scope, model, req, doc) { return __awaiter(void 0, void 0, void 0, function () {
+    var method, allowed;
+    var _a, _b;
+    return __generator(this, function (_c) {
+        switch (_c.label) {
+            case 0:
+                method = mapActionToCrudMethod(scope, action.method);
+                return [4 /*yield*/, (0, permissions_1.checkPermissions)(method, action.permissions, req.user, doc)];
+            case 1:
+                allowed = _c.sent();
+                if (allowed) {
+                    return [2 /*return*/];
+                }
+                if (!doc) {
+                    throw new errors_1.APIError({
+                        status: 405,
+                        title: "Access to ".concat(method.toUpperCase(), " on ").concat(model.modelName, " ") + "denied for ".concat((_a = req.user) === null || _a === void 0 ? void 0 : _a.id),
+                    });
+                }
+                throw new errors_1.APIError({
+                    status: 403,
+                    title: "Access to ".concat(method.toUpperCase(), " on ").concat(model.modelName, ":").concat(req.params.id, " ") +
+                        "denied for ".concat((_b = req.user) === null || _b === void 0 ? void 0 : _b.id),
+                });
+        }
+    });
+}); };
+exports.runActionPermissions = runActionPermissions;
+var flattenZodFieldErrors = function (fieldErrors) {
+    var e_1, _a;
+    var fields = {};
+    try {
+        for (var _b = __values(Object.entries(fieldErrors)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var _d = __read(_c.value, 2), key = _d[0], msgs = _d[1];
+            if (msgs && msgs.length > 0) {
+                fields[key] = msgs[0];
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return fields;
+};
+var validateActionRequest = function (_a) {
+    var action = _a.action, req = _a.req;
+    var body;
+    if (action.body) {
+        var parsedBody = action.body.safeParse(req.body);
+        if (!parsedBody.success) {
+            throw new errors_1.APIError({
+                fields: flattenZodFieldErrors(parsedBody.error.flatten().fieldErrors),
+                status: 400,
+                title: "Validation failed",
+            });
+        }
+        body = parsedBody.data;
+    }
+    else {
+        body = req.body;
+    }
+    var query;
+    if (action.query) {
+        var parsedQuery = action.query.safeParse(req.query);
+        if (!parsedQuery.success) {
+            throw new errors_1.APIError({
+                fields: flattenZodFieldErrors(parsedQuery.error.flatten().fieldErrors),
+                status: 400,
+                title: "Validation failed",
+            });
+        }
+        query = parsedQuery.data;
+    }
+    else {
+        query = req.query;
+    }
+    return { body: body, query: query };
+};
+exports.validateActionRequest = validateActionRequest;
+var wrapActionResponse = function (handlerResult, action, res) {
+    var _a;
+    if (res.headersSent) {
+        return;
+    }
+    res.status((_a = action.status) !== null && _a !== void 0 ? _a : 200).json({ data: handlerResult !== null && handlerResult !== void 0 ? handlerResult : null });
+};
+exports.wrapActionResponse = wrapActionResponse;
+var inlineOpenApiSchemaCounter = 0;
+var zodToJsonSchema = function (zodSchema) {
+    var _a;
+    var registry = new zod_to_openapi_1.OpenAPIRegistry();
+    var refId = "ActionInlineSchema".concat(inlineOpenApiSchemaCounter++);
+    registry.register(refId, zodSchema);
+    var generator = new zod_to_openapi_1.OpenApiGeneratorV3(registry.definitions);
+    var components = generator.generateComponents().components;
+    var schema = (_a = components === null || components === void 0 ? void 0 : components.schemas) === null || _a === void 0 ? void 0 : _a[refId];
+    if (schema && typeof schema === "object") {
+        return schema;
+    }
+    return { type: "object" };
+};
+var queryParametersFromSchema = function (querySchema) {
+    var _a;
+    var jsonSchema = zodToJsonSchema(querySchema);
+    var properties = jsonSchema.properties;
+    if (!properties) {
+        return [];
+    }
+    var requiredFields = (_a = jsonSchema.required) !== null && _a !== void 0 ? _a : [];
+    return Object.entries(properties).map(function (_a) {
+        var _b = __read(_a, 2), name = _b[0], schema = _b[1];
+        return ({
+            in: "query",
+            name: name,
+            required: requiredFields.includes(name),
+            schema: schema,
+        });
+    });
+};
+var createActionOpenApiMiddleware = function (_a) {
+    var _b;
+    var _c, _d, _e, _f;
+    var action = _a.action, scope = _a.scope, actionName = _a.actionName, model = _a.model, options = _a.options;
+    if (!((_c = options.openApi) === null || _c === void 0 ? void 0 : _c.path)) {
+        return function (_req, _res, next) { return next(); };
+    }
+    var tag = (_d = action.tag) !== null && _d !== void 0 ? _d : model.collection.collectionName;
+    var statusCode = String((_e = action.status) !== null && _e !== void 0 ? _e : 200);
+    var parameters = [];
+    if (scope === "instance") {
+        parameters.push({
+            in: "path",
+            name: "id",
+            required: true,
+            schema: { type: "string" },
+        });
+    }
+    if (action.query) {
+        parameters.push.apply(parameters, __spreadArray([], __read(queryParametersFromSchema(action.query)), false));
+    }
+    var operation = {
+        description: action.description,
+        operationId: "".concat(tag, "_").concat(actionName),
+        parameters: parameters,
+        responses: __assign((_b = {}, _b[statusCode] = {
+            content: {
+                "application/json": {
+                    schema: action.response
+                        ? {
+                            properties: {
+                                data: zodToJsonSchema(action.response),
+                            },
+                            required: ["data"],
+                            type: "object",
+                        }
+                        : {
+                            properties: {
+                                data: { type: "object" },
+                            },
+                            type: "object",
+                        },
+                },
+            },
+            description: "Successful response",
+        }, _b), openApi_1.defaultOpenApiErrorResponses),
+        summary: (_f = action.summary) !== null && _f !== void 0 ? _f : "".concat(actionName, " ").concat(scope, " action"),
+        tags: [tag],
+    };
+    if (action.body) {
+        operation.requestBody = {
+            content: {
+                "application/json": {
+                    schema: zodToJsonSchema(action.body),
+                },
+            },
+            required: true,
+        };
+    }
+    return options.openApi.path(operation);
+};
+exports.createActionOpenApiMiddleware = createActionOpenApiMiddleware;
+var getArrayFieldNames = function (model) {
+    return Object.values(model.schema.paths)
+        .filter(function (config) { return config.instance === "Array"; })
+        .map(function (config) { return config.path; });
+};
+// Registration-time validation throws plain Error so misconfiguration fails at app boot.
+var validateActionConfig = function (scope, name, config) {
+    if (!name) {
+        throw new Error("Action name cannot be empty");
+    }
+    if (!exports.ACTION_NAME_PATTERN.test(name)) {
+        throw new Error("Invalid action name \"".concat(name, "\". Action names must match ").concat(exports.ACTION_NAME_PATTERN.toString()));
+    }
+    if (config.permissions === undefined) {
+        throw new Error("Action \"".concat(name, "\" (").concat(scope, ") is missing required \"permissions\". ") +
+            "Provide at least one permission function, or [] to disable the action.");
+    }
+    if (config.method !== "GET" && config.method !== "POST") {
+        throw new Error("Action \"".concat(name, "\" (").concat(scope, ") only supports GET and POST methods"));
+    }
+};
+var assertNoActionCollisions = function (model, options) {
+    var arrayFields = new Set(getArrayFieldNames(model));
+    var validateMap = function (actions, scope) {
+        var e_2, _a;
+        if (!actions) {
+            return;
+        }
+        try {
+            for (var _b = __values(Object.entries(actions)), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var _d = __read(_c.value, 2), name_1 = _d[0], config = _d[1];
+                validateActionConfig(scope, name_1, config);
+                if (scope === "instance" && arrayFields.has(name_1)) {
+                    throw new Error("instanceAction '".concat(name_1, "' collides with array field operations on /:id/").concat(name_1));
+                }
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+    };
+    validateMap(options.instanceActions, "instance");
+    validateMap(options.collectionActions, "collection");
+};
+exports.assertNoActionCollisions = assertNoActionCollisions;
+var buildActionMiddleware = function (model, options, registered) {
+    var action = registered.config;
+    var scope = registered.scope;
+    var actionName = registered.name;
+    var preDocPermissions = function (req, _res, next) { return __awaiter(void 0, void 0, void 0, function () {
+        var error_1;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    _a.trys.push([0, 2, , 3]);
+                    return [4 /*yield*/, (0, exports.runActionPermissions)(action, scope, model, req)];
+                case 1:
+                    _a.sent();
+                    return [2 /*return*/, next()];
+                case 2:
+                    error_1 = _a.sent();
+                    return [2 /*return*/, next(error_1)];
+                case 3: return [2 /*return*/];
+            }
+        });
+    }); };
+    var loadDocAndPostPermissions = scope === "instance"
+        ? function (req, _res, next) { return __awaiter(void 0, void 0, void 0, function () {
+            var doc, error_2;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        _a.trys.push([0, 3, , 4]);
+                        return [4 /*yield*/, (0, docLoader_1.loadDocOr404)(model, req.params.id, options.populatePaths)];
+                    case 1:
+                        doc = _a.sent();
+                        req.obj = doc;
+                        return [4 /*yield*/, (0, exports.runActionPermissions)(action, scope, model, req, doc)];
+                    case 2:
+                        _a.sent();
+                        return [2 /*return*/, next()];
+                    case 3:
+                        error_2 = _a.sent();
+                        return [2 /*return*/, next(error_2)];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        }); }
+        : null;
+    var validateAndRun = (0, api_1.asyncHandler)(function (req, res) { return __awaiter(void 0, void 0, void 0, function () {
+        var _a, body, query, doc, ctx, result, _b;
+        return __generator(this, function (_c) {
+            switch (_c.label) {
+                case 0:
+                    _a = (0, exports.validateActionRequest)({ action: action, req: req }), body = _a.body, query = _a.query;
+                    doc = scope === "instance" ? req.obj : undefined;
+                    ctx = {
+                        body: body,
+                        doc: doc,
+                        query: query,
+                        req: req,
+                        res: res,
+                        user: req.user,
+                    };
+                    if (!(scope === "instance")) return [3 /*break*/, 2];
+                    return [4 /*yield*/, action.handler(ctx)];
+                case 1:
+                    _b = _c.sent();
+                    return [3 /*break*/, 4];
+                case 2: return [4 /*yield*/, action.handler(ctx)];
+                case 3:
+                    _b = _c.sent();
+                    _c.label = 4;
+                case 4:
+                    result = _b;
+                    (0, exports.wrapActionResponse)(result, action, res);
+                    return [2 /*return*/];
+            }
+        });
+    }); });
+    var chain = [
+        (0, auth_1.authenticateMiddleware)(options.allowAnonymous),
+        (0, exports.createActionOpenApiMiddleware)({ action: action, actionName: actionName, model: model, options: options, scope: scope }),
+        preDocPermissions,
+    ];
+    if (loadDocAndPostPermissions) {
+        chain.push(loadDocAndPostPermissions);
+    }
+    chain.push(validateAndRun);
+    return chain;
+};
+var registerActionRoutes = function (router, model, options) {
+    var e_3, _a;
+    var _b, _c;
+    var instanceActions = (_b = options.instanceActions) !== null && _b !== void 0 ? _b : {};
+    var collectionActions = (_c = options.collectionActions) !== null && _c !== void 0 ? _c : {};
+    var registeredActions = __spreadArray(__spreadArray([], __read(Object.entries(instanceActions).map(function (_a) {
+        var _b = __read(_a, 2), name = _b[0], config = _b[1];
+        return ({
+            config: config,
+            name: name,
+            scope: "instance",
+        });
+    })), false), __read(Object.entries(collectionActions).map(function (_a) {
+        var _b = __read(_a, 2), name = _b[0], config = _b[1];
+        return ({
+            config: config,
+            name: name,
+            scope: "collection",
+        });
+    })), false);
+    try {
+        for (var registeredActions_1 = __values(registeredActions), registeredActions_1_1 = registeredActions_1.next(); !registeredActions_1_1.done; registeredActions_1_1 = registeredActions_1.next()) {
+            var registered = registeredActions_1_1.value;
+            var config = registered.config, name_2 = registered.name, scope = registered.scope;
+            var middleware = buildActionMiddleware(model, options, registered);
+            var routePath = scope === "instance" ? "/:id/".concat(name_2) : "/".concat(name_2);
+            if (config.method === "GET") {
+                router.get(routePath, middleware);
+            }
+            else {
+                router.post(routePath, middleware);
+            }
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (registeredActions_1_1 && !registeredActions_1_1.done && (_a = registeredActions_1.return)) _a.call(registeredActions_1);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+};
+exports.registerActionRoutes = registerActionRoutes;

package/dist/actions.openApi.test.d.ts

@@ -0,0 +1 @@
+export {};