@objectstack/objectql 4.0.5 → 4.1.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, Hook } from '@objectstack/spec/data';
+import { ServiceObject, ObjectOwnership, HookContext, QueryAST, EngineQueryOptions, DataEngineInsertOptions, EngineUpdateOptions, EngineDeleteOptions, EngineCountOptions, EngineAggregateOptions, DateGranularityValue, Hook } from '@objectstack/spec/data';
 import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
@@ -105,6 +105,13 @@ interface SchemaRegistryOptions {
  *   - `organization_id` — multi-tenant deployments. Required-false (the
  *     SecurityPlugin populates it on insert; nullable rows are still
  *     filtered out by the `tenant_isolation` RLS USING clause).
+ *   - `created_at` / `created_by` / `updated_at` / `updated_by` — audit
+ *     fields. Marked `system: true, readonly: true` so detail views can
+ *     surface them in a dedicated "System Information" section while
+ *     edit forms / drawers filter them out. The driver populates the
+ *     timestamps; the `*_by` lookups are filled by the runtime when an
+ *     authenticated session is present (NULL otherwise — e.g. seeded
+ *     rows).
  */
 declare function applySystemFields(schema: ServiceObject, opts: {
     multiTenant: boolean;
@@ -257,6 +264,17 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      */
     private projectId?;
     constructor(engine: IDataEngine, getServicesRegistry?: () => Map<string, any>, getFeedService?: () => IFeedService | undefined, projectId?: string);
+    /**
+     * One-time guard for ensuring the overlay-uniqueness UNIQUE INDEX exists
+     * on `sys_metadata`. ADR-0005: scopes overlays by
+     * `(type, name, organization_id, project_id, scope)` for active rows only.
+     * Idempotent SQL — safe to attempt on every protocol instance.
+     *
+     * Inlined here (rather than importing from @objectstack/metadata/migrations)
+     * to avoid a circular dependency: metadata already depends on objectql.
+     */
+    private overlayIndexEnsured;
+    private ensureOverlayIndex;
     /**
      * Exposes the project scope the protocol is bound to. Consumers like
      * the HTTP dispatcher use this to decide whether to trust the process-
@@ -312,6 +330,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     getMetaItems(request: {
         type: string;
         packageId?: string;
+        organizationId?: string;
     }): Promise<{
         type: string;
         items: unknown[];
@@ -320,6 +339,7 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         type: string;
         name: string;
         packageId?: string;
+        organizationId?: string;
     }): Promise<{
         type: string;
         name: string;
@@ -413,6 +433,80 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         id: string;
         success: boolean;
     }>;
+    /**
+     * Cross-object substring search across all registered objects that opt in
+     * via `enable.searchable !== false` and `enable.apiEnabled !== false`.
+     * Searches text-like fields (text/textarea/email/url/phone/markdown/html/string)
+     * whose `searchable: true` flag is set, falling back to the object's
+     * `displayNameField` (or `name`) when no fields are explicitly searchable.
+     *
+     * The query is split into whitespace-separated terms; each term must match
+     * (case-insensitive LIKE) at least one searchable field. RBAC/RLS is
+     * enforced by forwarding the caller's `context` to `engine.find` so users
+     * only see records they are entitled to read.
+     */
+    searchAll(request: {
+        q: string;
+        objects?: string[];
+        limit?: number;
+        perObject?: number;
+        context?: any;
+    }): Promise<{
+        query: string;
+        hits: Array<{
+            object: string;
+            id: string;
+            title: string;
+            snippet?: string;
+            record: any;
+        }>;
+        totalObjects: number;
+        totalHits: number;
+        truncated: boolean;
+    }>;
+    /**
+     * Convert a qualified Lead into an Account + Contact (+ optional
+     * Opportunity) and mark the Lead as converted. Mirrors the Salesforce
+     * lead-conversion model:
+     *
+     *   - If `accountId` is provided, the lead's company info is NOT used
+     *     to create a new account; the new contact and opportunity link to
+     *     the existing account instead.
+     *   - If `contactId` is provided, no new contact is created either —
+     *     useful when the lead is a new contact at an existing account.
+     *   - `createOpportunity` defaults to true; pass `false` to convert
+     *     without producing an opportunity (some teams convert "logos
+     *     only" first).
+     *   - Lead is updated atomically: `is_converted=true`,
+     *     `converted_account`/`converted_contact`/`converted_opportunity`
+     *     pointers, `converted_date`, and `status='converted'`.
+     *
+     * Atomicity is enforced via the default driver's transaction support
+     * when available; otherwise a best-effort compensation (delete
+     * already-created child records on failure) is attempted. Permission
+     * checks on each child object are inherited from the caller's
+     * execution context so SecurityPlugin still gates account/contact/
+     * opportunity creates.
+     */
+    convertLead(request: {
+        leadId: string;
+        accountId?: string;
+        contactId?: string;
+        createOpportunity?: boolean;
+        opportunity?: {
+            name?: string;
+            amount?: number;
+            close_date?: string;
+            stage?: string;
+        };
+        convertedStatus?: string;
+        context?: any;
+    }): Promise<{
+        lead: any;
+        account: any;
+        contact: any;
+        opportunity: any | null;
+    }>;
     getMetaItemCached(request: {
         type: string;
         name: string;
@@ -432,23 +526,51 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private mapAnalyticsOperator;
     triggerAutomation(_request: any): Promise<any>;
     deleteManyData(request: DeleteManyDataRequest): Promise<any>;
+    /**
+     * Metadata types that are customer-overridable via {@link saveMetaItem}/
+     * {@link deleteMetaItem} in project-kernel mode. Derived from the canonical
+     * registry in {@link DEFAULT_METADATA_TYPE_REGISTRY}: a type opts in by
+     * setting `allowOrgOverride: true` on its registry entry. The set is
+     * augmented with the plural form of every singular so callers using REST
+     * conventions (`/api/v1/meta/views/...`) get the same gate. See ADR-0005
+     * §"Whitelist enforcement" for the rationale and the per-type rollout
+     * checklist.
+     */
+    private static readonly OVERLAY_ALLOWED_TYPES;
+    /** Normalize plural→singular before consulting the allow-list. */
+    private static isOverlayAllowed;
     saveMetaItem(request: {
         type: string;
         name: string;
         item?: any;
+        organizationId?: string;
     }): Promise<{
         success: boolean;
         message: string;
-        warning?: undefined;
-    } | {
+    }>;
+    /**
+     * Remove a customization overlay row for the given metadata item, so the
+     * next read falls through to the artifact-loaded default. Implements the
+     * "Reset to factory default" semantic from ADR-0005. Whitelist is shared
+     * with {@link saveMetaItem}.
+     */
+    deleteMetaItem(request: {
+        type: string;
+        name: string;
+        organizationId?: string;
+    }): Promise<{
         success: boolean;
-        message: string;
-        warning: any;
+        message?: string;
+        reset?: boolean;
     }>;
     /**
      * Hydrate SchemaRegistry from the database on startup.
      * Loads all active metadata records and registers them in the in-memory registry.
      * Safe to call repeatedly — idempotent (latest DB record wins).
+     *
+     * Per ADR-0005, project-kernel mode ALSO hydrates from sys_metadata —
+     * customization overlay rows must survive restart. Scope filter
+     * (`project_id = this.projectId ?? null`) keeps tenants isolated.
      */
     loadMetaFromDb(): Promise<{
         loaded: number;
@@ -662,6 +784,20 @@ declare class ObjectQL implements IDataEngine {
      * Build a HookContext.session from ExecutionContext
      */
     private buildSession;
+    /**
+     * Build the DriverOptions blob passed to every IDataDriver call.
+     *
+     * Always carries `tenantId` from the active ExecutionContext so the
+     * driver can enforce per-tenant isolation (SQL driver auto-scopes reads
+     * and auto-injects the tenant column on writes). Existing user-supplied
+     * shapes (transactions, AST extras) are preserved by spreading them
+     * first.
+     *
+     * System / isSystem callers may still cross tenants by clearing
+     * `tenantId` themselves on the resulting object; this helper does not
+     * mask the system path.
+     */
+    private buildDriverOptions;
     /**
      * Build a HookContext.api: a ScopedContext that hooks can use to
      * read/write other objects within the same execution context.
@@ -795,7 +931,40 @@ declare class ObjectQL implements IDataEngine {
     delete(object: string, options?: EngineDeleteOptions): Promise<any>;
     count(object: string, query?: EngineCountOptions): Promise<number>;
     aggregate(object: string, query: EngineAggregateOptions): Promise<any[]>;
+    /**
+     * Run raw driver-specific commands (SQL for SqlDriver, REST for RestDriver, …).
+     *
+     * ⚠️ **Tenant isolation bypass.** Raw `execute()` does NOT thread the
+     * caller's `ExecutionContext.tenantId` into a `WHERE organization_id`
+     * predicate — drivers see the command verbatim. Callers MUST inline the
+     * tenant filter themselves, or restrict raw execution to genuinely global
+     * statements (schema migrations, sys_* / control-plane tables).
+     *
+     * Prefer the typed entry points (`find`, `update`, `delete`, `count`, …)
+     * whenever feasible — they auto-apply tenancy + soft-delete + audit warnings.
+     */
     execute(command: any, options?: Record<string, any>): Promise<any>;
+    /**
+     * Execute a callback inside a database transaction.
+     *
+     * The callback receives a context object that should be passed to all
+     * downstream `engine.insert/update/delete/find/findOne` calls (as
+     * `{ context: trxCtx }`). The transaction handle threads through
+     * `OperationContext.context.transaction` and the SQL driver's per-builder
+     * `.transacting(trx)` call.
+     *
+     * - If the default driver does not support `beginTransaction`, the callback
+     *   runs directly with the supplied base context (no rollback). This keeps
+     *   the API safe to call on drivers without ACID support (e.g. the
+     *   in-memory driver in tests).
+     * - On callback success the transaction is committed; on any thrown error
+     *   it is rolled back and the original error is re-thrown.
+     *
+     * Use case: multi-step operations that must be atomic (e.g. CRM
+     * `convertLead`, which creates an account + contact + opportunity + flips
+     * the lead in a single unit of work).
+     */
+    transaction<T>(callback: (trxCtx: any) => Promise<T>, baseContext?: any): Promise<T>;
     /**
      * Register a single object definition.
      *
@@ -964,6 +1133,17 @@ declare class ScopedContext {
     get transactionHandle(): unknown;
 }
 
+/**
+ * Group + aggregate raw rows according to the AST's `groupBy` /
+ * `aggregations`. When neither is present, returns the rows unchanged.
+ */
+declare function applyInMemoryAggregation(rows: any[], ast: Pick<QueryAST, 'groupBy' | 'aggregations'>): any[];
+/**
+ * Bucket a date-like value into an ISO-formatted period label. Weeks start
+ * Monday and use ISO week numbering.
+ */
+declare function bucketDateValue(value: unknown, granularity: DateGranularityValue): string;
+
 /**
  * Hook Execution Metrics
  *
@@ -1156,6 +1336,46 @@ interface WrapDeclarativeOptions {
  */
 declare function wrapDeclarativeHook(meta: Hook, handler: HookHandler, opts?: WrapDeclarativeOptions): HookHandler;
 
+interface FieldValidationError {
+    field: string;
+    code: 'required' | 'min_length' | 'max_length' | 'min_value' | 'max_value' | 'invalid_email' | 'invalid_url' | 'invalid_phone' | 'invalid_number' | 'invalid_boolean' | 'invalid_date' | 'invalid_option';
+    message: string;
+    /** Allowed values for select/multiselect, when applicable. */
+    options?: string[];
+}
+declare class ValidationError extends Error {
+    readonly code = "VALIDATION_FAILED";
+    readonly fields: FieldValidationError[];
+    constructor(fields: FieldValidationError[]);
+}
+type Mode = 'insert' | 'update';
+interface FieldDef {
+    name?: string;
+    type: string;
+    required?: boolean;
+    readonly?: boolean;
+    system?: boolean;
+    multiple?: boolean;
+    maxLength?: number;
+    minLength?: number;
+    min?: number;
+    max?: number;
+    options?: Array<{
+        value: string | number;
+        label?: string;
+    } | string | number>;
+}
+/**
+ * Validate a payload against a list of declared fields. `objectSchema`
+ * comes from `ObjectQL.getRegistry().getObject(name)` and exposes a
+ * `fields` map of `{ [fieldName]: FieldDef }`.
+ *
+ * Returns void on success; throws `ValidationError` on failure.
+ */
+declare function validateRecord(objectSchema: {
+    fields?: Record<string, FieldDef>;
+} | undefined | null, data: Record<string, unknown> | undefined | null, mode: Mode): void;
+
 /**
  * MetadataFacade
  *
@@ -1231,14 +1451,48 @@ interface ObjectQLPluginOptions {
     hostContext?: Record<string, any>;
     /** Scope sys_metadata reads/writes to this project. */
     projectId?: string;
+    /**
+     * Override the kernel's default plugin-start timeout for this plugin.
+     * Defaults to 120000 (120s). Schema sync to a remote SQL backend
+     * (Neon/Postgres/Turso) is latency-bound — the SQL driver currently
+     * does NOT support `batchSchemaSync`, so it issues one round-trip per
+     * registered object × twice (Phase 1 + Phase 3 in `start()`). On a
+     * cold remote DB with N tables this can blow past the kernel's
+     * default 30s easily, even though everything is healthy.
+     */
+    startupTimeout?: number;
+    /**
+     * Skip both `syncRegisteredSchemas()` calls inside `start()` and
+     * assume DDL is managed out-of-band (e.g. an `apps/cloud/scripts/migrate.ts`
+     * run before deploy that connects directly to the database and creates
+     * all `sys_*` + custom tables once).
+     *
+     * Use this on cold-start-sensitive runtimes (Cloudflare Containers,
+     * Lambda) where the platform's inbound-request budget is shorter than
+     * a fresh remote-DB schema sync. The plugin still hydrates the
+     * SchemaRegistry from `sys_metadata` (Phase 2), so custom user
+     * objects come up — they just aren't re-DDL'd on every cold boot.
+     *
+     * Falls back to `process.env.OS_SKIP_SCHEMA_SYNC === '1'` when the
+     * option is unset, so containers can flip it via their env without a
+     * code change.
+     */
+    skipSchemaSync?: boolean;
 }
 declare class ObjectQLPlugin implements Plugin {
     name: string;
     type: string;
     version: string;
+    /**
+     * Schema sync to remote SQL DBs is latency-bound (one round-trip per
+     * table × 2 phases). Default to 120s instead of the kernel's 30s so
+     * cold Neon/Turso starts don't get killed mid-sync.
+     */
+    startupTimeout: number;
     private ql;
     private hostContext?;
     private projectId?;
+    private skipSchemaSync;
     constructor(qlOrOptions?: ObjectQL | ObjectQLPluginOptions, hostContext?: Record<string, any>);
     init: (ctx: PluginContext) => Promise<void>;
     start: (ctx: PluginContext) => Promise<void>;
@@ -1422,4 +1676,4 @@ declare function convertIntrospectedSchemaToObjects(introspectedSchema: Introspe
     skipSystemColumns?: boolean;
 }): ServiceObject[];
 
-export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, type WrapDeclarativeOptions, applySystemFields, bindHooksToEngine, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, noopHookMetricsRecorder, parseFQN, toTitleCase, wrapDeclarativeHook };
+export { type BindHooksOptions, type BindHooksResult, DEFAULT_EXTENDER_PRIORITY, DEFAULT_OWNER_PRIORITY, type EngineMiddleware, type FieldValidationError, type HookEntry, type HookHandler, type HookMetricLabel, type HookMetricOutcome, type HookMetricsRecorder, type HookSkipReason, InMemoryHookMetricsRecorder, type IntrospectedColumn, type IntrospectedForeignKey, type IntrospectedSchema, type IntrospectedTable, MetadataFacade, type ObjectContributor, ObjectQL, type ObjectQLHostContext, type ObjectQLKernelOptions, ObjectQLPlugin, ObjectRepository, ObjectStackProtocolImplementation, type OperationContext, RESERVED_NAMESPACES, SchemaRegistry, type SchemaRegistryOptions, ScopedContext, ValidationError, type WrapDeclarativeOptions, applyInMemoryAggregation, applySystemFields, bindHooksToEngine, bucketDateValue, computeFQN, convertIntrospectedSchemaToObjects, createObjectQLKernel, noopHookMetricsRecorder, parseFQN, toTitleCase, validateRecord, wrapDeclarativeHook };