@objectstack/rest 7.8.0 → 8.0.0

package/dist/index.cjs

@@ -37,6 +37,9 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/rest-server.ts
+var import_core = require("@objectstack/core");
+
 // src/route-manager.ts
 var RouteManager = class {
   constructor(server) {
@@ -308,6 +311,32 @@ function mapDataError(error, object) {
       }
     };
   }
+  const unknownColumn = /has no column named\s+["'`]?([a-z0-9_]+)/i.exec(raw) || /no such column:\s*["'`]?([a-z0-9_.]+)/i.exec(raw) || /unknown column\s+["'`]([a-z0-9_]+)["'`]/i.exec(raw) || /column\s+["'`]([a-z0-9_]+)["'`]\s+of relation\s+\S+\s+does not exist/i.exec(raw);
+  if (unknownColumn) {
+    const field = unknownColumn[1]?.split(".").pop();
+    return {
+      status: 400,
+      body: {
+        error: field ? `Unknown field '${field}'${object ? ` on object '${object}'` : ""}` : "Request references a field that does not exist",
+        code: "INVALID_FIELD",
+        ...field ? { field } : {},
+        ...object ? { object } : {}
+      }
+    };
+  }
+  const notNull = /not null constraint failed:\s*\S*?\.([a-z0-9_]+)/i.exec(raw) || /null value in column\s+["'`]([a-z0-9_]+)["'`]/i.exec(raw) || /column\s+["'`]([a-z0-9_]+)["'`]\s+cannot be null/i.exec(raw);
+  if (notNull) {
+    const field = notNull[1];
+    return {
+      status: 400,
+      body: {
+        error: `${field} is required`,
+        code: "VALIDATION_FAILED",
+        fields: [{ field, code: "required", message: `${field} is required` }],
+        ...object ? { object } : {}
+      }
+    };
+  }
   const looksLikeUnknownObject = lower.includes("no such table") || lower.includes("relation") && lower.includes("does not exist") || lower.includes("table not found") || lower.includes("unknown object") || lower.includes("object not found") || lower.includes("no driver available") || object !== void 0 && lower.includes(`'${object.toLowerCase()}'`) && lower.includes("not");
   if (looksLikeUnknownObject) {
     return {
@@ -445,7 +474,16 @@ function rowsToCsv(fields, rows, includeHeader) {
   return lines.join("\r\n") + (lines.length > 0 ? "\r\n" : "");
 }
 var RestServer = class {
-  constructor(server, protocol, config = {}, kernelManager, envRegistry, defaultEnvironmentIdProvider, authServiceProvider, objectQLProvider, emailServiceProvider, sharingServiceProvider, reportsServiceProvider, approvalsServiceProvider, sharingRulesServiceProvider, i18nServiceProvider) {
+  constructor(server, protocol, config = {}, kernelManager, envRegistry, defaultEnvironmentIdProvider, authServiceProvider, objectQLProvider, emailServiceProvider, sharingServiceProvider, reportsServiceProvider, approvalsServiceProvider, sharingRulesServiceProvider, i18nServiceProvider, analyticsServiceProvider) {
+    /**
+     * Short-TTL cache for `hostname → environmentId` (P1-4). `resolveByHostname`
+     * is a control-plane lookup (typically a DB query) that otherwise runs on
+     * *every* unscoped request; caching it — including negative results, so
+     * unknown hosts don't hammer the registry — removes that per-request cost.
+     * The TTL is short so a newly-bound hostname becomes routable quickly.
+     */
+    this.hostnameCache = /* @__PURE__ */ new Map();
+    this.hostnameCacheTtlMs = 3e4;
     /**
      * Lazily load the OpenAPI spec JSON shipped by @objectstack/spec.
      * Cached after first read. Resilient to missing files / parse errors
@@ -466,6 +504,7 @@ var RestServer = class {
     this.approvalsServiceProvider = approvalsServiceProvider;
     this.sharingRulesServiceProvider = sharingRulesServiceProvider;
     this.i18nServiceProvider = i18nServiceProvider;
+    this.analyticsServiceProvider = analyticsServiceProvider;
   }
   /**
    * Resolve the protocol for a given request. When `environmentId` is present
@@ -489,13 +528,28 @@ var RestServer = class {
    * (and any other client) speak a single, uniform URL family without
    * duplicating route logic for the platform surface.
    */
+  /**
+   * Cached wrapper around `envRegistry.resolveByHostname` (P1-4). Returns the
+   * cached result while fresh; on a miss it queries the registry and caches the
+   * outcome (positive *and* negative) for {@link hostnameCacheTtlMs}. Registry
+   * errors are not cached so a transient control-plane blip self-heals on the
+   * next request.
+   */
+  async resolveHostnameCached(host) {
+    const now = Date.now();
+    const hit = this.hostnameCache.get(host);
+    if (hit && hit.expiresAt > now) return hit.value;
+    const result = await this.envRegistry.resolveByHostname(host) ?? null;
+    this.hostnameCache.set(host, { value: result, expiresAt: now + this.hostnameCacheTtlMs });
+    return result;
+  }
   async resolveProtocol(environmentId, req) {
     if (environmentId === "platform") return this.protocol;
     if (!environmentId && req && this.envRegistry && this.kernelManager) {
       const host = this.extractHostname(req);
       if (host) {
         try {
-          const result = await this.envRegistry.resolveByHostname(host);
+          const result = await this.resolveHostnameCached(host);
           if (result?.environmentId) environmentId = result.environmentId;
         } catch {
         }
@@ -539,7 +593,7 @@ var RestServer = class {
       const host = this.extractHostname(req);
       if (host) {
         try {
-          const result = await this.envRegistry.resolveByHostname(host);
+          const result = await this.resolveHostnameCached(host);
           if (result?.environmentId) environmentId = result.environmentId;
         } catch {
         }
@@ -610,7 +664,7 @@ var RestServer = class {
         const host = this.extractHostname(req);
         if (host) {
           try {
-            const result = await this.envRegistry.resolveByHostname(host);
+            const result = await this.resolveHostnameCached(host);
             if (result?.environmentId) environmentId = result.environmentId;
           } catch {
           }
@@ -664,13 +718,27 @@ var RestServer = class {
       } else {
         return void 0;
       }
-      const session = await api.getSession({ headers });
-      if (!session?.user?.id) return void 0;
-      const userId = session.user.id;
-      const tenantId = session.session?.activeOrganizationId ?? void 0;
       const permissions = [];
       const systemPermissions = [];
       const roles = [];
+      let identityQl;
+      if (kernel) identityQl = await kernel.getServiceAsync("objectql").catch(() => void 0);
+      if (!identityQl && this.objectQLProvider) {
+        identityQl = await this.objectQLProvider(environmentId).catch(() => void 0);
+      }
+      let userId;
+      let tenantId;
+      const keyPrincipal = await (0, import_core.resolveApiKeyPrincipal)(identityQl, headers).catch(() => void 0);
+      if (keyPrincipal) {
+        userId = keyPrincipal.userId;
+        tenantId = keyPrincipal.tenantId;
+        for (const s of keyPrincipal.scopes) if (!permissions.includes(s)) permissions.push(s);
+      } else {
+        const session = await api.getSession({ headers });
+        if (!session?.user?.id) return void 0;
+        userId = session.user.id;
+        tenantId = session.session?.activeOrganizationId ?? void 0;
+      }
       try {
         let ql;
         if (kernel) {
@@ -1081,6 +1149,7 @@ var RestServer = class {
       this.registerSharingRuleEndpoints(bp);
       this.registerReportsEndpoints(bp);
       this.registerApprovalsEndpoints(bp);
+      this.registerAnalyticsEndpoints(bp);
       if (this.config.api.enableCrud) {
         this.registerCrudEndpoints(bp);
       }
@@ -1121,6 +1190,13 @@ var RestServer = class {
           if (this.config.api.enableUi) {
             discovery.routes.ui = `${realBase}/ui`;
           }
+          const mcpEnabled = globalThis?.process?.env?.OS_MCP_SERVER_ENABLED === "true";
+          if (mcpEnabled) {
+            const unscopedBase = isScoped ? basePath.replace(/\/(environments|projects)\/:environmentId$/, "") : basePath;
+            discovery.routes.mcp = `${unscopedBase}/mcp`;
+          } else {
+            delete discovery.routes.mcp;
+          }
           if (discovery.routes.auth) {
             const unscopedBase = isScoped ? basePath.replace(/\/projects\/:environmentId$/, "") : basePath;
             discovery.routes.auth = `${unscopedBase}/auth`;
@@ -1613,13 +1689,15 @@ var RestServer = class {
           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 dropStorage = req.query?.dropStorage === "true" || req.query?.dropStorage === "1";
           const result = await p.deleteMetaItem({
             type: req.params.type,
             name: req.params.name,
             ...environmentId ? { environmentId } : {},
             ...parentVersion !== void 0 ? { parentVersion } : {},
             ...actor ? { actor } : {},
-            ...stateParam ? { state: stateParam } : {}
+            ...stateParam ? { state: stateParam } : {},
+            ...dropStorage ? { dropStorage: true } : {}
           });
           res.json(result);
         } catch (error) {
@@ -2868,6 +2946,89 @@ var RestServer = class {
    * when no sharing service is configured so a deployment without the
    * `@objectstack/plugin-sharing` plugin fails cleanly.
    */
+  /**
+   * ADR-0021 — analytics dataset preview/query endpoint.
+   *
+   *   POST {basePath}/analytics/dataset/query
+   *   body: { dataset?: <inline Dataset>, datasetName?: string, selection: DatasetSelection }
+   *
+   * Compiles the dataset (an inline draft for Studio preview, or a saved one
+   * by name) and runs the selection through the analytics service's
+   * `queryDataset`, threading the request ExecutionContext so tenant/RLS
+   * scoping (ADR-0021 D-C) applies. Returns 501 when no analytics service
+   * (or one without `queryDataset`) is configured, so a deployment without
+   * `@objectstack/service-analytics` fails cleanly.
+   */
+  registerAnalyticsEndpoints(basePath) {
+    const isScoped = basePath.includes("/environments/:environmentId");
+    const resolveService = async (environmentId) => {
+      if (!this.analyticsServiceProvider) return void 0;
+      try {
+        return await this.analyticsServiceProvider(environmentId);
+      } catch {
+        return void 0;
+      }
+    };
+    this.routeManager.register({
+      method: "POST",
+      path: `${basePath}/analytics/dataset/query`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const svc = await resolveService(environmentId);
+          if (!svc || typeof svc.queryDataset !== "function") {
+            return res.status(501).json({
+              code: "NOT_IMPLEMENTED",
+              message: "Analytics dataset query is not available on this deployment (no analytics service with queryDataset)."
+            });
+          }
+          const body = req.body ?? {};
+          const selection = body.selection;
+          if (!selection || !Array.isArray(selection.measures) || selection.measures.length === 0) {
+            return res.status(400).json({
+              code: "VALIDATION_FAILED",
+              message: "body.selection.measures must be a non-empty array of measure names."
+            });
+          }
+          let dataset = body.dataset;
+          if (!dataset && body.datasetName) {
+            const p = await this.resolveProtocol(environmentId, req);
+            const items = await p.getMetaItems?.({ type: "dataset" }).catch(() => null);
+            const list = Array.isArray(items?.items) ? items.items : Array.isArray(items) ? items : [];
+            dataset = list.find((d) => d?.name === body.datasetName);
+            if (!dataset) {
+              return res.status(404).json({ code: "NOT_FOUND", message: `Dataset "${body.datasetName}" not found.` });
+            }
+          }
+          if (!dataset) {
+            return res.status(400).json({ code: "VALIDATION_FAILED", message: "Provide body.dataset (inline) or body.datasetName." });
+          }
+          try {
+            const { DatasetSchema } = await import("@objectstack/spec/ui");
+            dataset = DatasetSchema.parse(dataset);
+          } catch (verr) {
+            return res.status(400).json({
+              code: "VALIDATION_FAILED",
+              message: "Invalid dataset definition.",
+              detail: String(verr?.message ?? verr).slice(0, 1e3)
+            });
+          }
+          const result = await svc.queryDataset(dataset, selection, context ?? void 0);
+          res.json(result);
+        } catch (error) {
+          const msg = String(error?.message ?? error ?? "");
+          if (/not declared in the dataset|not backed by a declared relationship|not supported by the v1 dataset runtime|read-scope-sql/.test(msg)) {
+            return res.status(400).json({ code: "DATASET_INVALID", message: msg.slice(0, 1e3) });
+          }
+          logError("[REST] Analytics dataset query error:", error);
+          res.status(500).json({ code: "ANALYTICS_QUERY_FAILED", error: msg.slice(0, 500) });
+        }
+      },
+      metadata: { summary: "Run a semantic-layer dataset (preview/query)", tags: ["analytics"] }
+    });
+  }
   registerSharingEndpoints(basePath) {
     const { crud } = this.config;
     const dataPath = `${basePath}${crud.dataPrefix}`;
@@ -3409,11 +3570,13 @@ var RestServer = class {
             return;
           }
           const q = req.query ?? {};
+          const rawApprover = q.approverId ?? q.approver_id;
+          const approverIds = (Array.isArray(rawApprover) ? rawApprover : rawApprover != null ? [rawApprover] : []).flatMap((s) => String(s).split(",")).map((s) => s.trim()).filter(Boolean);
           const rows = await svc.listRequests({
             object: q.object,
             recordId: q.recordId ?? q.record_id,
             status: q.status,
-            approverId: q.approverId ?? q.approver_id,
+            approverId: approverIds.length ? approverIds : void 0,
             submitterId: q.submitterId ?? q.submitter_id
           }, context ?? {});
           res.json({ data: rows });
@@ -3508,6 +3671,73 @@ var RestServer = class {
     const dataPath = `${basePath}${crud.dataPrefix}`;
     const isScoped = basePath.includes("/environments/:environmentId");
     const operations = batch.operations;
+    this.routeManager.register({
+      method: "POST",
+      path: `${basePath}/batch`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const ql = this.objectQLProvider ? await this.objectQLProvider(environmentId) : void 0;
+          if (!ql || typeof ql.transaction !== "function") {
+            res.status(501).json({ error: "Transactional batch not supported by this runtime" });
+            return;
+          }
+          const ops = Array.isArray(req.body?.operations) ? req.body.operations : [];
+          const max = batch.maxBatchSize ?? 200;
+          if (ops.length === 0) {
+            res.json({ results: [] });
+            return;
+          }
+          if (ops.length > max) {
+            res.status(400).json({ error: `Batch too large (max ${max})` });
+            return;
+          }
+          const resolveRefs = (data, out) => {
+            if (!data || typeof data !== "object") return data;
+            const result = Array.isArray(data) ? [] : {};
+            for (const [k, v] of Object.entries(data)) {
+              if (v && typeof v === "object" && "$ref" in v) {
+                const ref = out[v.$ref];
+                result[k] = (ref && (ref.id ?? ref._id)) ?? null;
+              } else {
+                result[k] = v;
+              }
+            }
+            return result;
+          };
+          const results = await ql.transaction(async (trxCtx) => {
+            const out = [];
+            for (const op of ops) {
+              const action = String(op?.action || "create");
+              const object = String(op?.object || "");
+              if (!object) throw new Error("Each operation requires an `object`");
+              const data = resolveRefs(op.data, out);
+              if (action === "create") {
+                out.push(await ql.insert(object, data, { context: trxCtx }));
+              } else if (action === "update") {
+                const id = op.id ?? data?.id;
+                out.push(await ql.update(object, { ...data, id }, { context: trxCtx }));
+              } else if (action === "delete") {
+                out.push(await ql.delete(object, { where: { id: op.id }, context: trxCtx }));
+              } else {
+                throw new Error(`Unknown batch action: ${action}`);
+              }
+            }
+            return out;
+          }, context);
+          res.json({ results });
+        } catch (error) {
+          logError("[REST] Unhandled error:", error);
+          sendError(res, error);
+        }
+      },
+      metadata: {
+        summary: "Cross-object transactional batch (atomic create/update/delete across objects)",
+        tags: ["data", "batch"]
+      }
+    });
     if (batch.enableBatchEndpoint && this.protocol.batchData) {
       this.routeManager.register({
         method: "POST",
@@ -3907,6 +4137,13 @@ function createRestApiPlugin(config = {}) {
           return void 0;
         }
       };
+      const analyticsServiceProvider = async (_environmentId) => {
+        try {
+          return ctx.getService("analytics");
+        } catch {
+          return void 0;
+        }
+      };
       if (!server) {
         ctx.logger.warn(`RestApiPlugin: HTTP Server service '${serverService}' not found. REST routes skipped.`);
         return;
@@ -3917,7 +4154,7 @@ function createRestApiPlugin(config = {}) {
       }
       ctx.logger.info("Hydrating REST API from Protocol...");
       try {
-        const restServer = new RestServer(server, protocol, config.api, kernelManager, envRegistry, defaultEnvironmentIdProvider, authServiceProvider, objectQLProvider, emailServiceProvider, sharingServiceProvider, reportsServiceProvider, approvalsServiceProvider, sharingRulesServiceProvider, i18nServiceProvider);
+        const restServer = new RestServer(server, protocol, config.api, kernelManager, envRegistry, defaultEnvironmentIdProvider, authServiceProvider, objectQLProvider, emailServiceProvider, sharingServiceProvider, reportsServiceProvider, approvalsServiceProvider, sharingRulesServiceProvider, i18nServiceProvider, analyticsServiceProvider);
         restServer.registerRoutes();
         ctx.logger.info("REST API successfully registered");
       } catch (err) {