@objectstack/rest 5.1.0 → 5.2.0

package/dist/index.d.cts

@@ -343,6 +343,31 @@ declare class RestServer {
      * Register discovery endpoints
      */
     private registerDiscoveryEndpoints;
+    /**
+     * Register OpenAPI 3.1 spec + interactive docs viewer.
+     *
+     *   GET <basePath>/openapi.json   → enriched OpenAPI document
+     *   GET <basePath>/docs           → Scalar-rendered HTML (CDN, no dep)
+     *
+     * Enrichment at request time:
+     *   - servers[0].url           — derived from the request's Host header
+     *   - paths                    — `{object}` placeholders expanded into
+     *                                one concrete path per registered object
+     *                                from the protocol's discovery metadata
+     *
+     * The base spec is loaded lazily from @objectstack/spec/openapi.json
+     * (shipped pre-generated by spec's build pipeline) so we don't pay
+     * the cost of regenerating on every request, and a missing or
+     * malformed file degrades to a stub instead of crashing.
+     */
+    private registerOpenApiEndpoints;
+    /**
+     * Lazily load the OpenAPI spec JSON shipped by @objectstack/spec.
+     * Cached after first read. Resilient to missing files / parse errors
+     * so a degraded environment still boots.
+     */
+    private _openApiSpecCache;
+    private loadOpenApiSpec;
     /**
      * Register metadata endpoints
      */

package/dist/index.d.ts

@@ -343,6 +343,31 @@ declare class RestServer {
      * Register discovery endpoints
      */
     private registerDiscoveryEndpoints;
+    /**
+     * Register OpenAPI 3.1 spec + interactive docs viewer.
+     *
+     *   GET <basePath>/openapi.json   → enriched OpenAPI document
+     *   GET <basePath>/docs           → Scalar-rendered HTML (CDN, no dep)
+     *
+     * Enrichment at request time:
+     *   - servers[0].url           — derived from the request's Host header
+     *   - paths                    — `{object}` placeholders expanded into
+     *                                one concrete path per registered object
+     *                                from the protocol's discovery metadata
+     *
+     * The base spec is loaded lazily from @objectstack/spec/openapi.json
+     * (shipped pre-generated by spec's build pipeline) so we don't pay
+     * the cost of regenerating on every request, and a missing or
+     * malformed file degrades to a stub instead of crashing.
+     */
+    private registerOpenApiEndpoints;
+    /**
+     * Lazily load the OpenAPI spec JSON shipped by @objectstack/spec.
+     * Cached after first read. Resilient to missing files / parse errors
+     * so a degraded environment still boots.
+     */
+    private _openApiSpecCache;
+    private loadOpenApiSpec;
     /**
      * Register metadata endpoints
      */

package/dist/index.js

@@ -404,6 +404,12 @@ function rowsToCsv(fields, rows, includeHeader) {
 }
 var RestServer = class {
   constructor(server, protocol, config = {}, kernelManager, envRegistry, defaultProjectIdProvider, authServiceProvider, objectQLProvider, emailServiceProvider, sharingServiceProvider, reportsServiceProvider, approvalsServiceProvider, sharingRulesServiceProvider, i18nServiceProvider) {
+    /**
+     * Lazily load the OpenAPI spec JSON shipped by @objectstack/spec.
+     * Cached after first read. Resilient to missing files / parse errors
+     * so a degraded environment still boots.
+     */
+    this._openApiSpecCache = void 0;
     this.protocol = protocol;
     this.config = this.normalizeConfig(config);
     this.routeManager = new RouteManager(server);
@@ -670,12 +676,40 @@ var RestServer = class {
         }
       } catch {
       }
+      let org_user_ids = [userId];
+      if (tenantId) {
+        try {
+          let ql;
+          if (kernel) {
+            ql = await kernel.getServiceAsync("objectql").catch(() => void 0);
+          }
+          if (!ql && this.objectQLProvider) {
+            ql = await this.objectQLProvider(projectId).catch(() => void 0);
+          }
+          if (ql && typeof ql.find === "function") {
+            const sysOpts = { context: { isSystem: true } };
+            const memberRows = await ql.find("sys_member", {
+              where: { organization_id: tenantId },
+              limit: 1e3,
+              ...sysOpts
+            }).catch(() => []);
+            const ids = /* @__PURE__ */ new Set([userId]);
+            for (const m of memberRows ?? []) {
+              const uid = m.user_id ?? m.userId;
+              if (typeof uid === "string" && uid.length > 0) ids.add(uid);
+            }
+            org_user_ids = Array.from(ids);
+          }
+        } catch {
+        }
+      }
       return {
         userId,
         tenantId,
         roles,
         permissions,
-        isSystem: false
+        isSystem: false,
+        org_user_ids
       };
     } catch {
       return void 0;
@@ -817,6 +851,7 @@ var RestServer = class {
         enableUi: api.enableUi ?? true,
         enableBatch: api.enableBatch ?? true,
         enableDiscovery: api.enableDiscovery ?? true,
+        enableOpenApi: api.enableOpenApi ?? true,
         enableSearch: api.enableSearch ?? true,
         enableProjectScoping: api.enableProjectScoping ?? false,
         projectResolution: api.projectResolution ?? "auto",
@@ -896,6 +931,9 @@ var RestServer = class {
       if (this.config.api.enableDiscovery) {
         this.registerDiscoveryEndpoints(bp);
       }
+      if (this.config.api.enableOpenApi ?? true) {
+        this.registerOpenApiEndpoints(bp);
+      }
       if (this.config.api.enableMetadata) {
         this.registerMetadataEndpoints(bp);
       }
@@ -987,6 +1025,135 @@ var RestServer = class {
       }
     });
   }
+  /**
+   * Register OpenAPI 3.1 spec + interactive docs viewer.
+   *
+   *   GET <basePath>/openapi.json   → enriched OpenAPI document
+   *   GET <basePath>/docs           → Scalar-rendered HTML (CDN, no dep)
+   *
+   * Enrichment at request time:
+   *   - servers[0].url           — derived from the request's Host header
+   *   - paths                    — `{object}` placeholders expanded into
+   *                                one concrete path per registered object
+   *                                from the protocol's discovery metadata
+   *
+   * The base spec is loaded lazily from @objectstack/spec/openapi.json
+   * (shipped pre-generated by spec's build pipeline) so we don't pay
+   * the cost of regenerating on every request, and a missing or
+   * malformed file degrades to a stub instead of crashing.
+   */
+  registerOpenApiEndpoints(basePath) {
+    const isScoped = basePath.includes("/projects/:projectId");
+    const openApiHandler = async (req, res) => {
+      try {
+        const spec = await this.loadOpenApiSpec();
+        if (!spec) {
+          res.status?.(503);
+          res.json({
+            error: "openapi_unavailable",
+            message: "OpenAPI spec is not bundled with this runtime."
+          });
+          return;
+        }
+        const enriched = { ...spec, servers: [...spec.servers ?? []] };
+        const host = req.headers?.host ?? req.headers?.["host"];
+        const proto = req.headers?.["x-forwarded-proto"] || req.protocol || "http";
+        if (host) {
+          enriched.servers = [
+            { url: `${proto}://${host}`, description: "Current server" },
+            ...spec.servers ?? []
+          ];
+        }
+        try {
+          const projectId = isScoped ? req.params?.projectId : void 0;
+          const protocol = await this.resolveProtocol(projectId, req);
+          const items = await protocol?.getMetaItems?.({ type: "object" }).catch(() => null);
+          const objects = Array.isArray(items?.items) ? items.items.map((i) => i?.name).filter(Boolean) : Array.isArray(items) ? items.map((i) => i?.name).filter(Boolean) : [];
+          if (objects.length > 0 && enriched.paths) {
+            const expanded = {};
+            for (const [p, def] of Object.entries(enriched.paths)) {
+              if (p.includes("{object}")) {
+                expanded[p] = { ...def, "x-template": true };
+                for (const obj of objects) {
+                  expanded[p.replace("{object}", obj)] = def;
+                }
+              } else {
+                expanded[p] = def;
+              }
+            }
+            enriched.paths = expanded;
+          }
+        } catch {
+        }
+        if (enriched.info) {
+          enriched.info = {
+            ...enriched.info,
+            version: this.config.api.version || enriched.info.version
+          };
+        }
+        res.json(enriched);
+      } catch (error) {
+        logError("[REST] openapi.json error:", error);
+        sendError(res, error);
+      }
+    };
+    this.routeManager.register({
+      method: "GET",
+      path: `${basePath}/openapi.json`,
+      handler: openApiHandler,
+      metadata: {
+        summary: "OpenAPI 3.1 specification (machine-readable)",
+        tags: ["openapi"]
+      }
+    });
+    this.routeManager.register({
+      method: "GET",
+      path: `${basePath}/docs`,
+      handler: async (req, res) => {
+        const reqPath = req.path || req.url || `${basePath}/docs`;
+        const apiBase = reqPath.replace(/\/docs\/?$/, "");
+        const specUrl = `${apiBase}/openapi.json`;
+        const html = `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>ObjectStack API Docs</title>
+</head>
+<body>
+<script id="api-reference" data-url="${specUrl}"></script>
+<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>`;
+        if (res.setHeader) res.setHeader("content-type", "text/html; charset=utf-8");
+        if (res.send) res.send(html);
+        else if (res.body) res.body = html;
+        else res.json?.(html);
+      },
+      metadata: {
+        summary: "Interactive API docs (Scalar viewer)",
+        tags: ["openapi"]
+      }
+    });
+  }
+  async loadOpenApiSpec() {
+    if (this._openApiSpecCache !== void 0) return this._openApiSpecCache;
+    try {
+      const mod = await import("module");
+      const requireFn = mod.createRequire(import.meta.url);
+      const pkgJsonPath = requireFn.resolve("@objectstack/spec/package.json");
+      const pathMod = await import("path");
+      const fsMod = await import("fs");
+      const specPath = pathMod.join(pathMod.dirname(pkgJsonPath), "json-schema", "openapi.json");
+      const raw = await fsMod.promises.readFile(specPath, "utf-8");
+      this._openApiSpecCache = JSON.parse(raw);
+      return this._openApiSpecCache;
+    } catch (err) {
+      logError("[REST] Failed to load OpenAPI spec:", err?.message ?? err);
+      this._openApiSpecCache = null;
+      return null;
+    }
+  }
   /**
    * Register metadata endpoints
    */