@objectstack/rest 4.0.3 → 4.0.5

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { IHttpServer, RouteHandler, Plugin } from '@objectstack/core';
-import { Shared, System } from '@objectstack/spec';
+import * as System from '@objectstack/spec/system';
+import * as Shared from '@objectstack/spec/shared';
 import { z } from 'zod';
 import { ObjectStackProtocol, RestServerConfig } from '@objectstack/spec/api';
 
@@ -154,6 +155,17 @@ declare class RouteGroupBuilder {
     private resolvePath;
 }
 
+/**
+ * Structural subset of `KernelManager` that RestServer needs in order to
+ * resolve a per-project protocol at request time. Typed locally to avoid
+ * an @objectstack/runtime → @objectstack/rest → @objectstack/runtime
+ * package cycle.
+ */
+interface RestKernelManager {
+    getOrCreate(projectId: string): Promise<{
+        getServiceAsync<T = unknown>(name: string): Promise<T>;
+    }>;
+}
 /**
  * RestServer
  *
@@ -181,11 +193,113 @@ declare class RouteGroupBuilder {
  *
  * restServer.registerRoutes();
  */
+/**
+ * Minimal env registry shape consumed by the REST server for hostname →
+ * projectId resolution and `X-Project-Id` header validation on unscoped
+ * routes. Mirrors the surface of `EnvironmentDriverRegistry` defined in
+ * `@objectstack/service-cloud`.
+ */
+interface RestEnvRegistry {
+    resolveByHostname(hostname: string): Promise<{
+        projectId: 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)`).
+     */
+    resolveById?(projectId: string): Promise<unknown | null>;
+}
 declare class RestServer {
     private protocol;
     private config;
     private routeManager;
-    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig);
+    private kernelManager?;
+    private envRegistry?;
+    private defaultProjectIdProvider?;
+    private authServiceProvider?;
+    private objectQLProvider?;
+    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>);
+    /**
+     * Resolve the protocol for a given request. When `projectId` 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`
+     * 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`)
+     *   4. Control-plane protocol captured at boot.
+     *
+     * Special case: `projectId === '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')`.
+     * Instead, return the control-plane protocol directly. This lets Studio
+     * (and any other client) speak a single, uniform URL family without
+     * duplicating route logic for the platform surface.
+     */
+    private resolveProtocol;
+    /**
+     * Resolve the i18n service for the request's project (or control plane
+     * when no project id is in scope). Returns `undefined` when no service is
+     * registered, so callers can short-circuit and skip translation rather
+     * than failing.
+     *
+     * Mirrors `resolveProtocol`'s lookup chain: explicit `projectId` 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.
+     */
+    private resolveI18nService;
+    /**
+     * Resolve the request's execution context (RBAC/RLS/FLS) by looking up
+     * the better-auth session via the project's `auth` service. Returns
+     * `undefined` for anonymous requests so callers can pass `context` as-is
+     * to the protocol layer (the SecurityPlugin treats undefined as anon).
+     */
+    private resolveExecCtx;
+    /**
+     * Build a `TranslationBundle` (`Record<locale, TranslationData>`) from an
+     * `II18nService` instance. Returns `undefined` when no locales are
+     * registered so callers can avoid translation work.
+     */
+    private buildTranslationBundle;
+    /**
+     * Parse the highest-priority locale from an `Accept-Language` header.
+     * Falls back to a `?locale=` query parameter, then to the i18n service's
+     * default locale. Returns `undefined` when no preference is expressed
+     * (callers will then return untranslated metadata).
+     */
+    private extractLocale;
+    /**
+     * Translate a single metadata document (view or action) when an i18n
+     * service is registered for the request's project and the requested
+     * locale yields a match. Falls through unchanged for unsupported types
+     * or missing translations.
+     */
+    private translateMetaItem;
+    /**
+     * Translate a list of metadata documents using `translateMetaItem`.
+     */
+    private translateMetaItems;
+    /**
+     * Pull the request hostname (without port) from a Node-style `req` or
+     * a Fetch-style request wrapper. Returns undefined when no Host header
+     * is available.
+     */
+    private extractHostname;
+    /**
+     * Pull the `X-Project-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).
+     */
+    private extractProjectIdHeader;
     /**
      * Normalize configuration with defaults
      */
@@ -194,8 +308,19 @@ declare class RestServer {
      * Get the full API base path
      */
     private getApiBasePath;
+    /**
+     * Get the project-scoped base path for a given unscoped base.
+     * Example: `/api/v1` → `/api/v1/projects/:projectId`.
+     */
+    private getScopedBasePath;
     /**
      * Register all REST API routes
+     *
+     * When `enableProjectScoping` is true, routes are registered under
+     * `/api/v1/projects/:projectId/...`. The `projectResolution` strategy
+     * controls whether unscoped legacy routes remain available:
+     *   - `required` → only scoped routes registered.
+     *   - `optional` / `auto` → both scoped and unscoped routes registered.
      */
     registerRoutes(): void;
     /**
@@ -231,6 +356,12 @@ declare class RestServer {
 interface RestApiPluginConfig {
     serverServiceName?: string;
     protocolServiceName?: string;
+    /**
+     * 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.
+     */
+    kernelManagerServiceName?: string;
     api?: RestServerConfig;
 }
 /**