@objectstack/rest 4.0.4 → 4.1.0

package/dist/index.d.cts

@@ -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,128 @@ 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?;
+    private emailServiceProvider?;
+    private sharingServiceProvider?;
+    private reportsServiceProvider?;
+    private approvalsServiceProvider?;
+    private sharingRulesServiceProvider?;
+    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>);
+    /**
+     * 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;
+    /**
+     * Reject anonymous requests with HTTP 401 when `api.requireAuth` is set.
+     * Returns `true` if the response was sent and the caller should stop
+     * processing. Returns `false` to continue.
+     *
+     * The check is intentionally narrow: only `context?.userId` counts as
+     * "authenticated". `isSystem` flags are never set on inbound HTTP
+     * requests (they're internal-only), so they cannot bypass this gate.
+     */
+    private enforceAuth;
+    /**
+     * 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 +323,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;
     /**
@@ -214,6 +354,112 @@ declare class RestServer {
      * Register CRUD endpoints for data operations
      */
     private registerCrudEndpoints;
+    /**
+     * Register object-specific action endpoints that don't fit the
+     * generic CRUD shape. These are domain operations (Salesforce
+     * convertLead, etc.) where the protocol implementation does its own
+     * multi-record orchestration and we just need a thin HTTP route.
+     *
+     * POST {basePath}/data/lead/:id/convert — M10.6 lead conversion.
+     */
+    private registerDataActionEndpoints;
+    /**
+     * Register global cross-object search endpoint (M10.5).
+     * GET {basePath}/search?q=acme&objects=lead,account&limit=20&perObject=5
+     */
+    private registerSearchEndpoints;
+    /**
+     * Register email endpoints (M11.B1 / M10.7).
+     *
+     * POST {basePath}/email/send — send a transactional email via the
+     * `IEmailService` provider registered by EmailServicePlugin. Returns
+     * 501 when no provider is wired so deployments without email
+     * configured fail cleanly.
+     *
+     * Request body:
+     *   {
+     *     to: "a@b.com" | ["a@b.com", { name, address }],
+     *     from?: ..., cc?: ..., bcc?: ..., replyTo?: ...,
+     *     subject: string,
+     *     text?: string, html?: string,  // at least one required
+     *     attachments?: [{ filename, content, contentType?, cid? }],
+     *     headers?: { [name]: value },
+     *     relatedObject?: string, relatedId?: string,
+     *   }
+     */
+    private registerEmailEndpoints;
+    /**
+     * Register record-level sharing endpoints (M11.C17).
+     *
+     * Surfaces `ISharingService` over HTTP so the UI can list, create
+     * and revoke per-record grants without going through ObjectQL. The
+     * three routes mirror the share-management drawer in Salesforce /
+     * ServiceNow:
+     *
+     *   GET    {basePath}/data/:object/:id/shares
+     *   POST   {basePath}/data/:object/:id/shares
+     *   DELETE {basePath}/data/:object/:id/shares/:shareId
+     *
+     * All three resolve via `sharingServiceProvider`; routes return 501
+     * when no sharing service is configured so a deployment without the
+     * `@objectstack/plugin-sharing` plugin fails cleanly.
+     */
+    private registerSharingEndpoints;
+    /**
+     * Register sharing-rule endpoints (M10.17). Mirrors the existing
+     * sharing endpoints but operates on `sys_sharing_rule` rows.
+     *
+     *   GET    {basePath}/sharing/rules?object=&activeOnly=
+     *   POST   {basePath}/sharing/rules
+     *   GET    {basePath}/sharing/rules/:idOrName
+     *   DELETE {basePath}/sharing/rules/:idOrName
+     *   POST   {basePath}/sharing/rules/:idOrName/evaluate
+     *
+     * Returns 501 when no sharing-rule service is configured.
+     */
+    private registerSharingRuleEndpoints;
+    /**
+     * Register saved-report + scheduled-digest endpoints (M11.C16).
+     *
+     * Surfaces `IReportService` over HTTP so the UI can build,
+     * run, and schedule reports without dropping to ObjectQL. Routes
+     * live at the top of the API surface (alongside `/approvals` and
+     * `/sharing`) — reports are a tenant-wide capability, not a record
+     * on a specific CRUD object:
+     *
+     *   GET    {basePath}/reports?object=&ownerId=
+     *   POST   {basePath}/reports
+     *   GET    {basePath}/reports/:id
+     *   DELETE {basePath}/reports/:id
+     *   POST   {basePath}/reports/:id/run
+     *   POST   {basePath}/reports/:id/schedule
+     *   GET    {basePath}/reports/:id/schedules
+     *   DELETE {basePath}/reports/schedules/:scheduleId
+     *
+     * All routes return 501 when `reportsServiceProvider` is unset so
+     * a deployment without `@objectstack/plugin-reports` fails cleanly.
+     */
+    private registerReportsEndpoints;
+    /**
+     * Register approval engine endpoints.
+     *
+     * Routes (all under {basePath}/approvals):
+     *   GET    /processes                       — list approval processes
+     *   POST   /processes                       — upsert (defineProcess)
+     *   GET    /processes/:id                   — get by id or name
+     *   DELETE /processes/:id                   — delete process
+     *   POST   /requests                        — submit
+     *   GET    /requests                        — list (filters: status, object, recordId, approverId, submitterId)
+     *   GET    /requests/:id                    — get request
+     *   POST   /requests/:id/approve            — approve current step
+     *   POST   /requests/:id/reject             — reject current step
+     *   POST   /requests/:id/recall             — recall (submitter only)
+     *   GET    /requests/:id/actions            — audit trail
+     *
+     * Returns 501 when `approvalsServiceProvider` is unset so deployments
+     * without `@objectstack/plugin-approvals` fail cleanly.
+     */
+    private registerApprovalsEndpoints;
     /**
      * Register batch operation endpoints
      */
@@ -231,6 +477,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;
 }
 /**

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,128 @@ 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?;
+    private emailServiceProvider?;
+    private sharingServiceProvider?;
+    private reportsServiceProvider?;
+    private approvalsServiceProvider?;
+    private sharingRulesServiceProvider?;
+    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>);
+    /**
+     * 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;
+    /**
+     * Reject anonymous requests with HTTP 401 when `api.requireAuth` is set.
+     * Returns `true` if the response was sent and the caller should stop
+     * processing. Returns `false` to continue.
+     *
+     * The check is intentionally narrow: only `context?.userId` counts as
+     * "authenticated". `isSystem` flags are never set on inbound HTTP
+     * requests (they're internal-only), so they cannot bypass this gate.
+     */
+    private enforceAuth;
+    /**
+     * 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 +323,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;
     /**
@@ -214,6 +354,112 @@ declare class RestServer {
      * Register CRUD endpoints for data operations
      */
     private registerCrudEndpoints;
+    /**
+     * Register object-specific action endpoints that don't fit the
+     * generic CRUD shape. These are domain operations (Salesforce
+     * convertLead, etc.) where the protocol implementation does its own
+     * multi-record orchestration and we just need a thin HTTP route.
+     *
+     * POST {basePath}/data/lead/:id/convert — M10.6 lead conversion.
+     */
+    private registerDataActionEndpoints;
+    /**
+     * Register global cross-object search endpoint (M10.5).
+     * GET {basePath}/search?q=acme&objects=lead,account&limit=20&perObject=5
+     */
+    private registerSearchEndpoints;
+    /**
+     * Register email endpoints (M11.B1 / M10.7).
+     *
+     * POST {basePath}/email/send — send a transactional email via the
+     * `IEmailService` provider registered by EmailServicePlugin. Returns
+     * 501 when no provider is wired so deployments without email
+     * configured fail cleanly.
+     *
+     * Request body:
+     *   {
+     *     to: "a@b.com" | ["a@b.com", { name, address }],
+     *     from?: ..., cc?: ..., bcc?: ..., replyTo?: ...,
+     *     subject: string,
+     *     text?: string, html?: string,  // at least one required
+     *     attachments?: [{ filename, content, contentType?, cid? }],
+     *     headers?: { [name]: value },
+     *     relatedObject?: string, relatedId?: string,
+     *   }
+     */
+    private registerEmailEndpoints;
+    /**
+     * Register record-level sharing endpoints (M11.C17).
+     *
+     * Surfaces `ISharingService` over HTTP so the UI can list, create
+     * and revoke per-record grants without going through ObjectQL. The
+     * three routes mirror the share-management drawer in Salesforce /
+     * ServiceNow:
+     *
+     *   GET    {basePath}/data/:object/:id/shares
+     *   POST   {basePath}/data/:object/:id/shares
+     *   DELETE {basePath}/data/:object/:id/shares/:shareId
+     *
+     * All three resolve via `sharingServiceProvider`; routes return 501
+     * when no sharing service is configured so a deployment without the
+     * `@objectstack/plugin-sharing` plugin fails cleanly.
+     */
+    private registerSharingEndpoints;
+    /**
+     * Register sharing-rule endpoints (M10.17). Mirrors the existing
+     * sharing endpoints but operates on `sys_sharing_rule` rows.
+     *
+     *   GET    {basePath}/sharing/rules?object=&activeOnly=
+     *   POST   {basePath}/sharing/rules
+     *   GET    {basePath}/sharing/rules/:idOrName
+     *   DELETE {basePath}/sharing/rules/:idOrName
+     *   POST   {basePath}/sharing/rules/:idOrName/evaluate
+     *
+     * Returns 501 when no sharing-rule service is configured.
+     */
+    private registerSharingRuleEndpoints;
+    /**
+     * Register saved-report + scheduled-digest endpoints (M11.C16).
+     *
+     * Surfaces `IReportService` over HTTP so the UI can build,
+     * run, and schedule reports without dropping to ObjectQL. Routes
+     * live at the top of the API surface (alongside `/approvals` and
+     * `/sharing`) — reports are a tenant-wide capability, not a record
+     * on a specific CRUD object:
+     *
+     *   GET    {basePath}/reports?object=&ownerId=
+     *   POST   {basePath}/reports
+     *   GET    {basePath}/reports/:id
+     *   DELETE {basePath}/reports/:id
+     *   POST   {basePath}/reports/:id/run
+     *   POST   {basePath}/reports/:id/schedule
+     *   GET    {basePath}/reports/:id/schedules
+     *   DELETE {basePath}/reports/schedules/:scheduleId
+     *
+     * All routes return 501 when `reportsServiceProvider` is unset so
+     * a deployment without `@objectstack/plugin-reports` fails cleanly.
+     */
+    private registerReportsEndpoints;
+    /**
+     * Register approval engine endpoints.
+     *
+     * Routes (all under {basePath}/approvals):
+     *   GET    /processes                       — list approval processes
+     *   POST   /processes                       — upsert (defineProcess)
+     *   GET    /processes/:id                   — get by id or name
+     *   DELETE /processes/:id                   — delete process
+     *   POST   /requests                        — submit
+     *   GET    /requests                        — list (filters: status, object, recordId, approverId, submitterId)
+     *   GET    /requests/:id                    — get request
+     *   POST   /requests/:id/approve            — approve current step
+     *   POST   /requests/:id/reject             — reject current step
+     *   POST   /requests/:id/recall             — recall (submitter only)
+     *   GET    /requests/:id/actions            — audit trail
+     *
+     * Returns 501 when `approvalsServiceProvider` is unset so deployments
+     * without `@objectstack/plugin-approvals` fail cleanly.
+     */
+    private registerApprovalsEndpoints;
     /**
      * Register batch operation endpoints
      */
@@ -231,6 +477,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;
 }
 /**