@objectstack/rest 4.0.5 → 4.1.1

package/dist/index.d.cts

@@ -221,7 +221,13 @@ declare class RestServer {
     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>);
+    private emailServiceProvider?;
+    private sharingServiceProvider?;
+    private reportsServiceProvider?;
+    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>);
     /**
      * Resolve the protocol for a given request. When `projectId` is present
      * and a KernelManager is wired, fetch the per-project kernel's
@@ -257,6 +263,16 @@ declare class RestServer {
      * 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
@@ -339,6 +355,142 @@ 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 public (anonymous) form endpoints.
+     *
+     * Public forms are opt-in: a `FormView` becomes accessible to anonymous
+     * visitors only when `sharing.allowAnonymous === true` AND a
+     * `sharing.publicLink` slug is configured. Two routes are registered:
+     *
+     *   GET  {basePath}/forms/:slug          → resolved form spec
+     *   POST {basePath}/forms/:slug/submit   → INSERT record (no auth required)
+     *
+     * Both routes bypass `enforceAuth` even when `requireAuth=true` on the
+     * deployment (e.g. ObjectOS multi-tenant). Security is delegated to the
+     * `guest_portal` permission set carried on the execution context — the
+     * SecurityPlugin enforces INSERT-only access to the target object. If
+     * the deployment hasn't registered a `guest_portal` profile, the
+     * security middleware falls open with `permissions: []` (no userId),
+     * matching the existing anonymous-access semantics; deployers must
+     * keep `requireAuth=true` deployments paired with a `guest_portal`
+     * profile (the CRM example does this) to enforce the INSERT-only
+     * contract.
+     *
+     * The matched FormView's parent ViewSchema is found by scanning
+     * `protocol.getMetaItems({ type: 'view' })`. For each entry we inspect
+     * `form.sharing` and every entry in `formViews`; the first FormView
+     * whose `sharing.publicLink` matches `/forms/:slug` (or just `:slug`)
+     * wins. The response carries the matched form view under `form` and
+     * the inferred target object, matching what the frontend's
+     * `mapViewSpecToEmbeddableConfig` expects.
+     */
+    private registerFormEndpoints;
+    /**
+     * 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
      */

package/dist/index.d.ts

@@ -221,7 +221,13 @@ declare class RestServer {
     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>);
+    private emailServiceProvider?;
+    private sharingServiceProvider?;
+    private reportsServiceProvider?;
+    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>);
     /**
      * Resolve the protocol for a given request. When `projectId` is present
      * and a KernelManager is wired, fetch the per-project kernel's
@@ -257,6 +263,16 @@ declare class RestServer {
      * 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
@@ -339,6 +355,142 @@ 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 public (anonymous) form endpoints.
+     *
+     * Public forms are opt-in: a `FormView` becomes accessible to anonymous
+     * visitors only when `sharing.allowAnonymous === true` AND a
+     * `sharing.publicLink` slug is configured. Two routes are registered:
+     *
+     *   GET  {basePath}/forms/:slug          → resolved form spec
+     *   POST {basePath}/forms/:slug/submit   → INSERT record (no auth required)
+     *
+     * Both routes bypass `enforceAuth` even when `requireAuth=true` on the
+     * deployment (e.g. ObjectOS multi-tenant). Security is delegated to the
+     * `guest_portal` permission set carried on the execution context — the
+     * SecurityPlugin enforces INSERT-only access to the target object. If
+     * the deployment hasn't registered a `guest_portal` profile, the
+     * security middleware falls open with `permissions: []` (no userId),
+     * matching the existing anonymous-access semantics; deployers must
+     * keep `requireAuth=true` deployments paired with a `guest_portal`
+     * profile (the CRM example does this) to enforce the INSERT-only
+     * contract.
+     *
+     * The matched FormView's parent ViewSchema is found by scanning
+     * `protocol.getMetaItems({ type: 'view' })`. For each entry we inspect
+     * `form.sharing` and every entry in `formViews`; the first FormView
+     * whose `sharing.publicLink` matches `/forms/:slug` (or just `:slug`)
+     * wins. The response carries the matched form view under `form` and
+     * the inferred target object, matching what the frontend's
+     * `mapViewSpecToEmbeddableConfig` expects.
+     */
+    private registerFormEndpoints;
+    /**
+     * 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
      */