@objectstack/rest 5.1.0 → 6.0.0

package/dist/index.d.cts

@@ -162,7 +162,7 @@ declare class RouteGroupBuilder {
  * package cycle.
  */
 interface RestKernelManager {
-    getOrCreate(projectId: string): Promise<{
+    getOrCreate(environmentId: string): Promise<{
         getServiceAsync<T = unknown>(name: string): Promise<T>;
     }>;
 }
@@ -195,22 +195,22 @@ interface RestKernelManager {
  */
 /**
  * Minimal env registry shape consumed by the REST server for hostname →
- * projectId resolution and `X-Project-Id` header validation on unscoped
+ * environmentId resolution and `X-Environment-Id` header validation on unscoped
  * routes. Mirrors the surface of `EnvironmentDriverRegistry` defined in
  * `@objectstack/service-cloud`.
  */
 interface RestEnvRegistry {
     resolveByHostname(hostname: string): Promise<{
-        projectId: string;
+        environmentId: string;
     } | null | undefined>;
     /**
      * Look up a project by id. Returns a truthy value (typically an
      * `IDataDriver`) when the project exists and is bound, `null` when
      * unknown. The REST server only uses the truthiness; it does not
      * touch the driver itself (the actual driver is loaded later via
-     * `KernelManager.getOrCreate(projectId)`).
+     * `KernelManager.getOrCreate(environmentId)`).
      */
-    resolveById?(projectId: string): Promise<unknown | null>;
+    resolveById?(environmentId: string): Promise<unknown | null>;
 }
 declare class RestServer {
     private protocol;
@@ -218,7 +218,7 @@ declare class RestServer {
     private routeManager;
     private kernelManager?;
     private envRegistry?;
-    private defaultProjectIdProvider?;
+    private defaultEnvironmentIdProvider?;
     private authServiceProvider?;
     private objectQLProvider?;
     private emailServiceProvider?;
@@ -227,22 +227,22 @@ declare class RestServer {
     private approvalsServiceProvider?;
     private sharingRulesServiceProvider?;
     private i18nServiceProvider?;
-    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig, kernelManager?: RestKernelManager, envRegistry?: RestEnvRegistry, defaultProjectIdProvider?: () => string | undefined, authServiceProvider?: (projectId?: string) => Promise<any | undefined>, objectQLProvider?: (projectId?: string) => Promise<any | undefined>, emailServiceProvider?: (projectId?: string) => Promise<any | undefined>, sharingServiceProvider?: (projectId?: string) => Promise<any | undefined>, reportsServiceProvider?: (projectId?: string) => Promise<any | undefined>, approvalsServiceProvider?: (projectId?: string) => Promise<any | undefined>, sharingRulesServiceProvider?: (projectId?: string) => Promise<any | undefined>, i18nServiceProvider?: (projectId?: string) => Promise<any | undefined>);
+    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig, kernelManager?: RestKernelManager, envRegistry?: RestEnvRegistry, defaultEnvironmentIdProvider?: () => string | undefined, authServiceProvider?: (environmentId?: string) => Promise<any | undefined>, objectQLProvider?: (environmentId?: string) => Promise<any | undefined>, emailServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingServiceProvider?: (environmentId?: string) => Promise<any | undefined>, reportsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, approvalsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingRulesServiceProvider?: (environmentId?: string) => Promise<any | undefined>, i18nServiceProvider?: (environmentId?: string) => Promise<any | undefined>);
     /**
-     * Resolve the protocol for a given request. When `projectId` is present
+     * Resolve the protocol for a given request. When `environmentId` is present
      * and a KernelManager is wired, fetch the per-project kernel's
      * `protocol` service so metadata / data / UI reads hit the project's
      * own registry and datastore.
      *
-     * When `projectId` is absent on an unscoped route and an `envRegistry`
+     * When `environmentId` is absent on an unscoped route and an `envRegistry`
      * is wired (runtime mode), the resolution chain is:
-     *   1. Hostname → projectId (`envRegistry.resolveByHostname`)
-     *   2. `X-Project-Id` header → projectId (`envRegistry.resolveById`)
-     *   3. Default-project fallback (`defaultProjectIdProvider`, set by
-     *      `createSingleProjectPlugin`)
+     *   1. Hostname → environmentId (`envRegistry.resolveByHostname`)
+     *   2. `X-Environment-Id` header → environmentId (`envRegistry.resolveById`)
+     *   3. Default-project fallback (`defaultEnvironmentIdProvider`, set by
+     *      `createSingleEnvironmentPlugin`)
      *   4. Control-plane protocol captured at boot.
      *
-     * Special case: `projectId === 'platform'` is a reserved virtual id used
+     * Special case: `environmentId === 'platform'` is a reserved virtual id used
      * by Studio to address the control plane through the regular project
      * URL shape (`/projects/platform/...`). It is NOT a row in the projects
      * table, so we must never call `KernelManager.getOrCreate('platform')`.
@@ -257,7 +257,7 @@ declare class RestServer {
      * registered, so callers can short-circuit and skip translation rather
      * than failing.
      *
-     * Mirrors `resolveProtocol`'s lookup chain: explicit `projectId` from the
+     * Mirrors `resolveProtocol`'s lookup chain: explicit `environmentId` from the
      * route → kernel-managed `i18n` service. Control-plane / unscoped
      * requests intentionally return `undefined` because the platform kernel
      * does not own per-app translation bundles.
@@ -311,7 +311,7 @@ declare class RestServer {
      */
     private extractHostname;
     /**
-     * Pull the `X-Project-Id` header from a Node- or Fetch-style request.
+     * Pull the `X-Environment-Id` header from a Node- or Fetch-style request.
      * Header names are case-insensitive; we probe both casings to cover
      * adapters that don't normalize headers (e.g. raw Node http).
      */
@@ -326,14 +326,14 @@ declare class RestServer {
     private getApiBasePath;
     /**
      * Get the project-scoped base path for a given unscoped base.
-     * Example: `/api/v1` → `/api/v1/projects/:projectId`.
+     * Example: `/api/v1` → `/api/v1/environments/:environmentId`.
      */
     private getScopedBasePath;
     /**
      * Register all REST API routes
      *
      * When `enableProjectScoping` is true, routes are registered under
-     * `/api/v1/projects/:projectId/...`. The `projectResolution` strategy
+     * `/api/v1/environments/:environmentId/...`. The `projectResolution` strategy
      * controls whether unscoped legacy routes remain available:
      *   - `required` → only scoped routes registered.
      *   - `optional` / `auto` → both scoped and unscoped routes registered.
@@ -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
      */
@@ -511,7 +536,7 @@ interface RestApiPluginConfig {
     /**
      * Optional override for the kernel-manager service name. When the service
      * is registered (by @objectstack/runtime's MultiProjectPlugin), scoped
-     * routes resolve per-project protocols at request time.
+     * routes resolve per-environment protocols at request time.
      */
     kernelManagerServiceName?: string;
     api?: RestServerConfig;

package/dist/index.d.ts

@@ -162,7 +162,7 @@ declare class RouteGroupBuilder {
  * package cycle.
  */
 interface RestKernelManager {
-    getOrCreate(projectId: string): Promise<{
+    getOrCreate(environmentId: string): Promise<{
         getServiceAsync<T = unknown>(name: string): Promise<T>;
     }>;
 }
@@ -195,22 +195,22 @@ interface RestKernelManager {
  */
 /**
  * Minimal env registry shape consumed by the REST server for hostname →
- * projectId resolution and `X-Project-Id` header validation on unscoped
+ * environmentId resolution and `X-Environment-Id` header validation on unscoped
  * routes. Mirrors the surface of `EnvironmentDriverRegistry` defined in
  * `@objectstack/service-cloud`.
  */
 interface RestEnvRegistry {
     resolveByHostname(hostname: string): Promise<{
-        projectId: string;
+        environmentId: string;
     } | null | undefined>;
     /**
      * Look up a project by id. Returns a truthy value (typically an
      * `IDataDriver`) when the project exists and is bound, `null` when
      * unknown. The REST server only uses the truthiness; it does not
      * touch the driver itself (the actual driver is loaded later via
-     * `KernelManager.getOrCreate(projectId)`).
+     * `KernelManager.getOrCreate(environmentId)`).
      */
-    resolveById?(projectId: string): Promise<unknown | null>;
+    resolveById?(environmentId: string): Promise<unknown | null>;
 }
 declare class RestServer {
     private protocol;
@@ -218,7 +218,7 @@ declare class RestServer {
     private routeManager;
     private kernelManager?;
     private envRegistry?;
-    private defaultProjectIdProvider?;
+    private defaultEnvironmentIdProvider?;
     private authServiceProvider?;
     private objectQLProvider?;
     private emailServiceProvider?;
@@ -227,22 +227,22 @@ declare class RestServer {
     private approvalsServiceProvider?;
     private sharingRulesServiceProvider?;
     private i18nServiceProvider?;
-    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig, kernelManager?: RestKernelManager, envRegistry?: RestEnvRegistry, defaultProjectIdProvider?: () => string | undefined, authServiceProvider?: (projectId?: string) => Promise<any | undefined>, objectQLProvider?: (projectId?: string) => Promise<any | undefined>, emailServiceProvider?: (projectId?: string) => Promise<any | undefined>, sharingServiceProvider?: (projectId?: string) => Promise<any | undefined>, reportsServiceProvider?: (projectId?: string) => Promise<any | undefined>, approvalsServiceProvider?: (projectId?: string) => Promise<any | undefined>, sharingRulesServiceProvider?: (projectId?: string) => Promise<any | undefined>, i18nServiceProvider?: (projectId?: string) => Promise<any | undefined>);
+    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig, kernelManager?: RestKernelManager, envRegistry?: RestEnvRegistry, defaultEnvironmentIdProvider?: () => string | undefined, authServiceProvider?: (environmentId?: string) => Promise<any | undefined>, objectQLProvider?: (environmentId?: string) => Promise<any | undefined>, emailServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingServiceProvider?: (environmentId?: string) => Promise<any | undefined>, reportsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, approvalsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingRulesServiceProvider?: (environmentId?: string) => Promise<any | undefined>, i18nServiceProvider?: (environmentId?: string) => Promise<any | undefined>);
     /**
-     * Resolve the protocol for a given request. When `projectId` is present
+     * Resolve the protocol for a given request. When `environmentId` is present
      * and a KernelManager is wired, fetch the per-project kernel's
      * `protocol` service so metadata / data / UI reads hit the project's
      * own registry and datastore.
      *
-     * When `projectId` is absent on an unscoped route and an `envRegistry`
+     * When `environmentId` is absent on an unscoped route and an `envRegistry`
      * is wired (runtime mode), the resolution chain is:
-     *   1. Hostname → projectId (`envRegistry.resolveByHostname`)
-     *   2. `X-Project-Id` header → projectId (`envRegistry.resolveById`)
-     *   3. Default-project fallback (`defaultProjectIdProvider`, set by
-     *      `createSingleProjectPlugin`)
+     *   1. Hostname → environmentId (`envRegistry.resolveByHostname`)
+     *   2. `X-Environment-Id` header → environmentId (`envRegistry.resolveById`)
+     *   3. Default-project fallback (`defaultEnvironmentIdProvider`, set by
+     *      `createSingleEnvironmentPlugin`)
      *   4. Control-plane protocol captured at boot.
      *
-     * Special case: `projectId === 'platform'` is a reserved virtual id used
+     * Special case: `environmentId === 'platform'` is a reserved virtual id used
      * by Studio to address the control plane through the regular project
      * URL shape (`/projects/platform/...`). It is NOT a row in the projects
      * table, so we must never call `KernelManager.getOrCreate('platform')`.
@@ -257,7 +257,7 @@ declare class RestServer {
      * registered, so callers can short-circuit and skip translation rather
      * than failing.
      *
-     * Mirrors `resolveProtocol`'s lookup chain: explicit `projectId` from the
+     * Mirrors `resolveProtocol`'s lookup chain: explicit `environmentId` from the
      * route → kernel-managed `i18n` service. Control-plane / unscoped
      * requests intentionally return `undefined` because the platform kernel
      * does not own per-app translation bundles.
@@ -311,7 +311,7 @@ declare class RestServer {
      */
     private extractHostname;
     /**
-     * Pull the `X-Project-Id` header from a Node- or Fetch-style request.
+     * Pull the `X-Environment-Id` header from a Node- or Fetch-style request.
      * Header names are case-insensitive; we probe both casings to cover
      * adapters that don't normalize headers (e.g. raw Node http).
      */
@@ -326,14 +326,14 @@ declare class RestServer {
     private getApiBasePath;
     /**
      * Get the project-scoped base path for a given unscoped base.
-     * Example: `/api/v1` → `/api/v1/projects/:projectId`.
+     * Example: `/api/v1` → `/api/v1/environments/:environmentId`.
      */
     private getScopedBasePath;
     /**
      * Register all REST API routes
      *
      * When `enableProjectScoping` is true, routes are registered under
-     * `/api/v1/projects/:projectId/...`. The `projectResolution` strategy
+     * `/api/v1/environments/:environmentId/...`. The `projectResolution` strategy
      * controls whether unscoped legacy routes remain available:
      *   - `required` → only scoped routes registered.
      *   - `optional` / `auto` → both scoped and unscoped routes registered.
@@ -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
      */
@@ -511,7 +536,7 @@ interface RestApiPluginConfig {
     /**
      * Optional override for the kernel-manager service name. When the service
      * is registered (by @objectstack/runtime's MultiProjectPlugin), scoped
-     * routes resolve per-project protocols at request time.
+     * routes resolve per-environment protocols at request time.
      */
     kernelManagerServiceName?: string;
     api?: RestServerConfig;