@objectstack/rest 6.9.0 → 7.1.0

package/dist/index.d.cts

@@ -280,6 +280,20 @@ declare class RestServer {
      * to the protocol layer (the SecurityPlugin treats undefined as anon).
      */
     private resolveExecCtx;
+    /**
+     * Filter an `App` metadata item by the current user's `systemPermissions`.
+     *
+     * - Drops the app entirely if its top-level `requiredPermissions` are not
+     *   a subset of the user's system permissions.
+     * - Recursively strips child navigation entries (groups, items) whose
+     *   `requiredPermissions` are not satisfied. Empty groups collapse so
+     *   the sidebar doesn't render a label with no children.
+     *
+     * Returns `null` when the app should be hidden from the user. Returns a
+     * shallow copy with a filtered `navigation` tree otherwise — the original
+     * is never mutated so cached metadata stays clean.
+     */
+    private filterAppForUser;
     /**
      * Build a `TranslationBundle` (`Record<locale, TranslationData>`) from an
      * `II18nService` instance. Returns `undefined` when no locales are
@@ -304,6 +318,16 @@ declare class RestServer {
      * Translate a list of metadata documents using `translateMetaItem`.
      */
     private translateMetaItems;
+    /**
+     * Translate the `entries` payload returned by `getMetaTypes()` — applies
+     * the active locale to each entry's `label`, `description`, and the
+     * nested `form` layout (section labels, field labels, helpText,
+     * placeholders) via `metadataForms.<type>` translation namespace.
+     *
+     * No-ops when no i18n service / locale / matching bundle entry exists,
+     * so this is safe to call unconditionally from the `/meta` handler.
+     */
+    private translateMetaTypesResponse;
     /**
      * Pull the request hostname (without port) from a Node-style `req` or
      * a Fetch-style request wrapper. Returns undefined when no Host header

package/dist/index.d.ts

@@ -280,6 +280,20 @@ declare class RestServer {
      * to the protocol layer (the SecurityPlugin treats undefined as anon).
      */
     private resolveExecCtx;
+    /**
+     * Filter an `App` metadata item by the current user's `systemPermissions`.
+     *
+     * - Drops the app entirely if its top-level `requiredPermissions` are not
+     *   a subset of the user's system permissions.
+     * - Recursively strips child navigation entries (groups, items) whose
+     *   `requiredPermissions` are not satisfied. Empty groups collapse so
+     *   the sidebar doesn't render a label with no children.
+     *
+     * Returns `null` when the app should be hidden from the user. Returns a
+     * shallow copy with a filtered `navigation` tree otherwise — the original
+     * is never mutated so cached metadata stays clean.
+     */
+    private filterAppForUser;
     /**
      * Build a `TranslationBundle` (`Record<locale, TranslationData>`) from an
      * `II18nService` instance. Returns `undefined` when no locales are
@@ -304,6 +318,16 @@ declare class RestServer {
      * Translate a list of metadata documents using `translateMetaItem`.
      */
     private translateMetaItems;
+    /**
+     * Translate the `entries` payload returned by `getMetaTypes()` — applies
+     * the active locale to each entry's `label`, `description`, and the
+     * nested `form` layout (section labels, field labels, helpText,
+     * placeholders) via `metadataForms.<type>` translation namespace.
+     *
+     * No-ops when no i18n service / locale / matching bundle entry exists,
+     * so this is safe to call unconditionally from the `/meta` handler.
+     */
+    private translateMetaTypesResponse;
     /**
      * Pull the request hostname (without port) from a Node-style `req` or
      * a Fetch-style request wrapper. Returns undefined when no Host header

package/dist/index.js

@@ -628,6 +628,7 @@ var RestServer = class {
       const userId = session.user.id;
       const tenantId = session.session?.activeOrganizationId ?? void 0;
       const permissions = [];
+      const systemPermissions = [];
       const roles = [];
       try {
         let ql;
@@ -672,6 +673,20 @@ var RestServer = class {
             }).catch(() => []);
             for (const ps of psRows ?? []) {
               if (ps.name && !permissions.includes(ps.name)) permissions.push(ps.name);
+              const rawSys = typeof ps.system_permissions === "string" ? (() => {
+                try {
+                  return JSON.parse(ps.system_permissions);
+                } catch {
+                  return [];
+                }
+              })() : ps.system_permissions ?? ps.systemPermissions;
+              if (Array.isArray(rawSys)) {
+                for (const sp of rawSys) {
+                  if (typeof sp === "string" && !systemPermissions.includes(sp)) {
+                    systemPermissions.push(sp);
+                  }
+                }
+              }
             }
           }
         }
@@ -709,6 +724,7 @@ var RestServer = class {
         tenantId,
         roles,
         permissions,
+        systemPermissions,
         isSystem: false,
         org_user_ids
       };
@@ -716,6 +732,45 @@ var RestServer = class {
       return void 0;
     }
   }
+  /**
+   * Filter an `App` metadata item by the current user's `systemPermissions`.
+   *
+   * - Drops the app entirely if its top-level `requiredPermissions` are not
+   *   a subset of the user's system permissions.
+   * - Recursively strips child navigation entries (groups, items) whose
+   *   `requiredPermissions` are not satisfied. Empty groups collapse so
+   *   the sidebar doesn't render a label with no children.
+   *
+   * Returns `null` when the app should be hidden from the user. Returns a
+   * shallow copy with a filtered `navigation` tree otherwise — the original
+   * is never mutated so cached metadata stays clean.
+   */
+  filterAppForUser(item, sysPerms) {
+    if (!item || typeof item !== "object") return item;
+    const reqApp = Array.isArray(item.requiredPermissions) ? item.requiredPermissions : [];
+    if (reqApp.length > 0 && !reqApp.every((p) => sysPerms.has(p))) {
+      return null;
+    }
+    const nav = Array.isArray(item.navigation) ? item.navigation : null;
+    if (!nav) return item;
+    const filterNav = (entries) => {
+      const out = [];
+      for (const e of entries) {
+        if (!e || typeof e !== "object") continue;
+        const req = Array.isArray(e.requiredPermissions) ? e.requiredPermissions : [];
+        if (req.length > 0 && !req.every((p) => sysPerms.has(p))) continue;
+        if (Array.isArray(e.children) && e.children.length > 0) {
+          const kids = filterNav(e.children);
+          if (e.type === "group" && kids.length === 0) continue;
+          out.push({ ...e, children: kids });
+        } else {
+          out.push(e);
+        }
+      }
+      return out;
+    };
+    return { ...item, navigation: filterNav(nav) };
+  }
   /**
    * Build a `TranslationBundle` (`Record<locale, TranslationData>`) from an
    * `II18nService` instance. Returns `undefined` when no locales are
@@ -789,6 +844,41 @@ var RestServer = class {
     const { translateMetadataDocument } = await import("@objectstack/spec/system");
     return items.map((item) => translateMetadataDocument(type, item, bundle, { locale }));
   }
+  /**
+   * Translate the `entries` payload returned by `getMetaTypes()` — applies
+   * the active locale to each entry's `label`, `description`, and the
+   * nested `form` layout (section labels, field labels, helpText,
+   * placeholders) via `metadataForms.<type>` translation namespace.
+   *
+   * No-ops when no i18n service / locale / matching bundle entry exists,
+   * so this is safe to call unconditionally from the `/meta` handler.
+   */
+  async translateMetaTypesResponse(req, environmentId, payload) {
+    if (!payload || typeof payload !== "object" || !Array.isArray(payload.entries)) return payload;
+    const i18n = await this.resolveI18nService(environmentId, req);
+    const bundle = this.buildTranslationBundle(i18n);
+    if (!bundle) return payload;
+    const locale = this.extractLocale(req, i18n);
+    if (!locale) return payload;
+    const {
+      resolveMetadataTypeLabel,
+      resolveMetadataTypeDescription,
+      resolveMetadataFormLabels
+    } = await import("@objectstack/spec/system");
+    const opts = { locale };
+    const entries = payload.entries.map((entry) => {
+      if (!entry || typeof entry !== "object" || typeof entry.type !== "string") return entry;
+      const next = { ...entry };
+      next.label = resolveMetadataTypeLabel(bundle, entry.type, entry.label ?? entry.type, opts);
+      const desc = resolveMetadataTypeDescription(bundle, entry.type, entry.description, opts);
+      if (desc !== void 0) next.description = desc;
+      if (entry.form) {
+        next.form = resolveMetadataFormLabels(entry.form, entry.type, bundle, opts);
+      }
+      return next;
+    });
+    return { ...payload, entries };
+  }
   /**
    * Pull the request hostname (without port) from a Node-style `req` or
    * a Fetch-style request wrapper. Returns undefined when no Host header
@@ -1171,7 +1261,9 @@ var RestServer = class {
             const environmentId = isScoped ? req.params?.environmentId : void 0;
             const p = await this.resolveProtocol(environmentId, req);
             const types = await p.getMetaTypes();
-            res.json(types);
+            const translated = await this.translateMetaTypesResponse(req, environmentId, types);
+            res.header("Vary", "Accept-Language");
+            res.json(translated);
           } catch (error) {
             logError("[REST] Unhandled error:", error);
             sendError(res, error);
@@ -1183,6 +1275,40 @@ var RestServer = class {
         }
       });
     }
+    if (metadata.endpoints.items !== false) {
+      this.routeManager.register({
+        method: "GET",
+        path: `${metaPath}/diagnostics`,
+        handler: async (req, res) => {
+          try {
+            const environmentId = isScoped ? req.params?.environmentId : void 0;
+            const p = await this.resolveProtocol(environmentId, req);
+            if (typeof p.getMetaDiagnostics !== "function") {
+              res.status(501).json({
+                error: "not_implemented",
+                message: "protocol.getMetaDiagnostics() is not available in this kernel"
+              });
+              return;
+            }
+            const severityParam = req.query?.severity ?? "error";
+            const severity = severityParam === "warning" ? "warning" : "error";
+            const result = await p.getMetaDiagnostics({
+              type: req.query?.type || void 0,
+              severity,
+              packageId: req.query?.package || void 0
+            });
+            res.json(result);
+          } catch (error) {
+            logError("[REST] Unhandled error:", error);
+            sendError(res, error);
+          }
+        },
+        metadata: {
+          summary: "List metadata entries that fail spec validation",
+          tags: ["metadata"]
+        }
+      });
+    }
     if (metadata.endpoints.items !== false) {
       this.routeManager.register({
         method: "GET",
@@ -1197,7 +1323,22 @@ var RestServer = class {
               packageId,
               ...environmentId ? { environmentId } : {}
             });
-            const translated = await this.translateMetaItems(req, req.params.type, environmentId, items);
+            let visible = items;
+            if (req.params.type === "app") {
+              const raw = items;
+              const list = Array.isArray(raw) ? raw : raw && typeof raw === "object" && Array.isArray(raw.items) ? raw.items : null;
+              if (list) {
+                const ctx = await this.resolveExecCtx(environmentId, req).catch(() => void 0);
+                if (ctx?.userId) {
+                  const sysPerms = new Set(
+                    Array.isArray(ctx.systemPermissions) ? ctx.systemPermissions : []
+                  );
+                  const filtered = list.map((it) => this.filterAppForUser(it, sysPerms)).filter((it) => it != null);
+                  visible = Array.isArray(raw) ? filtered : { ...raw, items: filtered };
+                }
+              }
+            }
+            const translated = await this.translateMetaItems(req, req.params.type, environmentId, visible);
             res.header("Vary", "Accept-Language");
             res.json(translated);
           } catch (error) {
@@ -1256,7 +1397,9 @@ var RestServer = class {
               res.json(layered);
               return;
             }
-            if (metadata.enableCache && p.getMetaItemCached) {
+            const isAppType = req.params.type === "app";
+            const isDraftRead = typeof req.query?.state === "string" && req.query.state.toLowerCase() === "draft";
+            if (metadata.enableCache && p.getMetaItemCached && !isAppType && !isDraftRead) {
               const cacheRequest = {
                 ifNoneMatch: req.headers["if-none-match"],
                 ifModifiedSince: req.headers["if-modified-since"]
@@ -1287,13 +1430,32 @@ var RestServer = class {
               res.json(await this.translateMetaItem(req, req.params.type, environmentId, result.data));
             } else {
               const packageId = req.query?.package || void 0;
+              const stateParam = typeof req.query?.state === "string" ? req.query.state.toLowerCase() : void 0;
               const item = await p.getMetaItem({
                 type: req.params.type,
                 name: req.params.name,
-                packageId
+                packageId,
+                ...stateParam === "draft" ? { state: "draft" } : {}
               });
+              let visible = item;
+              if (isAppType && item) {
+                const ctx = await this.resolveExecCtx(environmentId, req).catch(() => void 0);
+                if (ctx?.userId) {
+                  const sysPerms = new Set(
+                    Array.isArray(ctx.systemPermissions) ? ctx.systemPermissions : []
+                  );
+                  visible = this.filterAppForUser(item, sysPerms);
+                  if (visible == null) {
+                    res.status(404).json({
+                      error: "not_found",
+                      message: "Metadata item not found or access denied."
+                    });
+                    return;
+                  }
+                }
+              }
               res.header("Vary", "Accept-Language");
-              res.json(await this.translateMetaItem(req, req.params.type, environmentId, item));
+              res.json(await this.translateMetaItem(req, req.params.type, environmentId, visible));
             }
           } catch (error) {
             logError("[REST] Unhandled error:", error);
@@ -1332,7 +1494,8 @@ var RestServer = class {
             ...environmentId ? { environmentId } : {},
             ...parentVersion !== void 0 ? { parentVersion } : {},
             ...actor ? { actor } : {},
-            ...force ? { force: true } : {}
+            ...force ? { force: true } : {},
+            ...typeof req.query?.mode === "string" && req.query.mode.toLowerCase() === "draft" ? { mode: "draft" } : {}
           });
           res.json(result);
         } catch (error) {
@@ -1362,12 +1525,14 @@ var RestServer = class {
           const parentVersion = typeof ifMatchHeader === "string" ? ifMatchHeader.replace(/^"|"$/g, "") : void 0;
           const actorHeader = req.headers?.["x-actor"] ?? req.headers?.["X-Actor"] ?? req.user?.id ?? req.userId;
           const actor = typeof actorHeader === "string" ? actorHeader : void 0;
+          const stateParam = typeof req.query?.state === "string" && req.query.state.toLowerCase() === "draft" ? "draft" : void 0;
           const result = await p.deleteMetaItem({
             type: req.params.type,
             name: req.params.name,
             ...environmentId ? { environmentId } : {},
             ...parentVersion !== void 0 ? { parentVersion } : {},
-            ...actor ? { actor } : {}
+            ...actor ? { actor } : {},
+            ...stateParam ? { state: stateParam } : {}
           });
           res.json(result);
         } catch (error) {
@@ -1413,6 +1578,124 @@ var RestServer = class {
         tags: ["metadata"]
       }
     });
+    this.routeManager.register({
+      method: "POST",
+      path: `${metaPath}/:type/:name/publish`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const p = await this.resolveProtocol(environmentId, req);
+          if (!p.publishMetaItem) {
+            res.status(501).json({
+              error: "Publish operation not supported by protocol implementation"
+            });
+            return;
+          }
+          const actorHeader = req.headers?.["x-actor"] ?? req.headers?.["X-Actor"] ?? req.user?.id ?? req.userId;
+          const actor = typeof actorHeader === "string" ? actorHeader : void 0;
+          const body = req.body && typeof req.body === "object" ? req.body : {};
+          const message = typeof body.message === "string" ? body.message : void 0;
+          const result = await p.publishMetaItem({
+            type: req.params.type,
+            name: req.params.name,
+            ...environmentId ? { environmentId } : {},
+            ...actor ? { actor } : {},
+            ...message ? { message } : {}
+          });
+          res.json(result);
+        } catch (error) {
+          logError("[REST] Unhandled error:", error);
+          sendError(res, error);
+        }
+      },
+      metadata: {
+        summary: "Publish the pending draft overlay (promotes draft \u2192 active)",
+        tags: ["metadata"]
+      }
+    });
+    this.routeManager.register({
+      method: "POST",
+      path: `${metaPath}/:type/:name/rollback`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const p = await this.resolveProtocol(environmentId, req);
+          if (!p.rollbackMetaItem) {
+            res.status(501).json({
+              error: "Rollback operation not supported by protocol implementation"
+            });
+            return;
+          }
+          const body = req.body && typeof req.body === "object" ? req.body : {};
+          const toVersionRaw = body.toVersion ?? body.version ?? req.query?.toVersion;
+          const toVersion = Number(toVersionRaw);
+          if (!Number.isFinite(toVersion) || toVersion < 1) {
+            res.status(400).json({
+              error: `'toVersion' (positive integer) is required`,
+              code: "invalid_request"
+            });
+            return;
+          }
+          const actorHeader = req.headers?.["x-actor"] ?? req.headers?.["X-Actor"] ?? req.user?.id ?? req.userId;
+          const actor = typeof actorHeader === "string" ? actorHeader : void 0;
+          const message = typeof body.message === "string" ? body.message : void 0;
+          const result = await p.rollbackMetaItem({
+            type: req.params.type,
+            name: req.params.name,
+            toVersion,
+            ...environmentId ? { environmentId } : {},
+            ...actor ? { actor } : {},
+            ...message ? { message } : {}
+          });
+          res.json(result);
+        } catch (error) {
+          logError("[REST] Unhandled error:", error);
+          sendError(res, error);
+        }
+      },
+      metadata: {
+        summary: "Restore the body at the given history version as the new live row",
+        tags: ["metadata"]
+      }
+    });
+    this.routeManager.register({
+      method: "GET",
+      path: `${metaPath}/:type/:name/diff`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const p = await this.resolveProtocol(environmentId, req);
+          if (!p.diffMetaItem) {
+            res.status(501).json({
+              error: "Diff operation not supported by protocol implementation"
+            });
+            return;
+          }
+          const parseV = (raw) => {
+            if (raw === void 0 || raw === null || raw === "") return void 0;
+            const n = Number(raw);
+            return Number.isFinite(n) ? n : void 0;
+          };
+          const fromVersion = parseV(req.query?.from ?? req.query?.fromVersion);
+          const toVersion = parseV(req.query?.to ?? req.query?.toVersion);
+          const result = await p.diffMetaItem({
+            type: req.params.type,
+            name: req.params.name,
+            ...environmentId ? { environmentId } : {},
+            ...fromVersion !== void 0 ? { fromVersion } : {},
+            ...toVersion !== void 0 ? { toVersion } : {}
+          });
+          res.json(result);
+        } catch (error) {
+          logError("[REST] Unhandled error:", error);
+          sendError(res, error);
+        }
+      },
+      metadata: {
+        summary: "Diff two metadata versions (from/to query params; omit for previous-vs-current)",
+        tags: ["metadata"]
+      }
+    });
     if (metadata.endpoints.item !== false) {
       this.routeManager.register({
         method: "GET",