@objectstack/objectql 9.7.0 → 9.9.0

package/dist/index.d.mts

@@ -636,6 +636,8 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 variant?: "link" | "primary" | "secondary" | "danger" | "ghost" | undefined;
                 confirmText?: string | undefined;
                 successMessage?: string | undefined;
+                errorMessage?: string | undefined;
+                undoable?: boolean | undefined;
                 resultDialog?: {
                     title?: string | undefined;
                     description?: string | undefined;
@@ -1065,6 +1067,30 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         id: any;
         record: any;
     }>;
+    /**
+     * Clone a record — read the source, drop engine-owned columns, and
+     * insert a fresh copy. Gated by the object's `enable.clone` capability
+     * (default `true`; only an explicit `enable.clone === false` disables it).
+     *
+     * Shallow by design: it duplicates the record's own scalar/business field
+     * values, not its related child records. The insert path re-stamps audit
+     * columns, regenerates `autonumber` fields, and recomputes derived
+     * (`formula`/`summary`) fields, so the copy is a valid new row rather than
+     * a byte-identical twin. Caller-supplied `overrides` are applied last and
+     * win over the copied values — the natural place to set a new `name`,
+     * clear a unique field, or reset status before insert.
+     */
+    cloneData(request: {
+        object: string;
+        id: string;
+        overrides?: Record<string, any>;
+        context?: any;
+    }): Promise<{
+        object: string;
+        id: any;
+        sourceId: string;
+        record: any;
+    }>;
     updateData(request: {
         object: string;
         id: string;
@@ -1137,49 +1163,6 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         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;
@@ -1999,6 +1982,23 @@ interface OperationContext {
     context?: ExecutionContext;
     result?: any;
 }
+/**
+ * Trailing options for the READ methods (find / findOne / count / aggregate).
+ *
+ * Historically the read methods took their execution context INSIDE the query
+ * (`query.context`), while the WRITE methods (insert / update) took it in a
+ * trailing `options.context`. That split was a footgun: the same `{ context }`
+ * object is correct as the 3rd arg to `insert` but was SILENTLY DROPPED as the
+ * 3rd arg to `find` — a class of bugs where an intended `isSystem` bypass just
+ * vanished (e.g. control-plane reads coming back empty once org-scoping hooks
+ * were added). We now ALSO accept `context` via this trailing options arg on the
+ * read methods, so "execution context goes in the trailing options argument" is
+ * one rule across reads and writes. `query.context` remains supported; when both
+ * are given, `options.context` wins (it is the explicit channel).
+ */
+interface EngineReadOptions {
+    context?: ExecutionContext;
+}
 /**
  * Engine Middleware (Onion model)
  */
@@ -2418,8 +2418,8 @@ declare class ObjectQL implements IDataEngine {
      * @returns Records with expanded lookup fields (IDs replaced by full objects)
      */
     private expandRelatedRecords;
-    find(object: string, query?: EngineQueryOptions): Promise<any[]>;
-    findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
+    find(object: string, query?: EngineQueryOptions, options?: EngineReadOptions): Promise<any[]>;
+    findOne(objectName: string, query?: EngineQueryOptions, options?: EngineReadOptions): Promise<any>;
     insert(object: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
     update(object: string, data: any, options?: EngineUpdateOptions): Promise<any>;
     /**
@@ -2431,13 +2431,16 @@ declare class ObjectQL implements IDataEngine {
      *   - `set_null` → clear the foreign key,
      *   - `restrict` → refuse the delete when dependents exist.
      * `master_detail` defaults to `cascade` (the parent owns the child
-     * lifecycle); `lookup` defaults to `set_null`. Only runs for single-id
+     * lifecycle); `lookup` defaults to `set_null` — except a `set_null` default
+     * on a REQUIRED lookup escalates to `restrict` (you can't null a NOT NULL
+     * FK; restricting with a clear dependent-count message beats a misleading
+     * "<field> is required" 400 from the child). Only runs for single-id
      * deletes — multi/predicate deletes skip cascade (logged).
      */
     private cascadeDeleteRelations;
     delete(object: string, options?: EngineDeleteOptions): Promise<any>;
-    count(object: string, query?: EngineCountOptions): Promise<number>;
-    aggregate(object: string, query: EngineAggregateOptions): Promise<any[]>;
+    count(object: string, query?: EngineCountOptions, options?: EngineReadOptions): Promise<number>;
+    aggregate(object: string, query: EngineAggregateOptions, options?: EngineReadOptions): Promise<any[]>;
     /**
      * Run raw driver-specific commands (SQL for SqlDriver, REST for RestDriver, …).
      *
@@ -2674,13 +2677,25 @@ declare class ScopedContext {
 /**
  * Group + aggregate raw rows according to the AST's `groupBy` /
  * `aggregations`. When neither is present, returns the rows unchanged.
+ *
+ * `timezone` (ADR-0053 Phase 2) shifts date bucketing to a reference timezone
+ * so a row near a tz day-boundary lands in the right day/week/month/quarter.
+ * It is only consulted by `groupBy` items carrying a `dateGranularity`; an
+ * unset or `'UTC'` value keeps the historical UTC bucketing.
  */
-declare function applyInMemoryAggregation(rows: any[], ast: Pick<QueryAST, 'groupBy' | 'aggregations'>): any[];
+declare function applyInMemoryAggregation(rows: any[], ast: Pick<QueryAST, 'groupBy' | 'aggregations'>, timezone?: string): any[];
 /**
  * Bucket a date-like value into an ISO-formatted period label. Weeks start
  * Monday and use ISO week numbering.
+ *
+ * `timezone` (ADR-0053 Phase 2) resolves the calendar day in a reference zone
+ * so an instant near a tz day-boundary buckets where a user in that zone would
+ * expect. An unset / `'UTC'` / invalid zone keeps the historical UTC bucketing.
+ * The y/m/d are taken in the reference zone and the ISO-week math then runs on
+ * a UTC date built from those parts — the parts already carry the zone shift,
+ * so the week boundary lands correctly without re-applying any offset.
  */
-declare function bucketDateValue(value: unknown, granularity: DateGranularityValue): string;
+declare function bucketDateValue(value: unknown, granularity: DateGranularityValue, timezone?: string): string;
 
 /**
  * Hook Execution Metrics
@@ -2876,7 +2891,7 @@ declare function wrapDeclarativeHook(meta: Hook, handler: HookHandler, opts?: Wr
 
 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' | 'invalid_transition' | 'rule_violation' | 'invalid_format' | 'invalid_json' | 'json_schema_violation';
+    code: 'required' | 'min_length' | 'max_length' | 'min_value' | 'max_value' | 'invalid_email' | 'invalid_url' | 'invalid_phone' | 'invalid_number' | 'invalid_boolean' | 'invalid_date' | 'invalid_time' | 'invalid_option' | 'invalid_transition' | 'rule_violation' | 'invalid_format' | 'invalid_json' | 'json_schema_violation';
     message: string;
     /** Allowed values for select/multiselect, when applicable. */
     options?: string[];

package/dist/index.d.ts

@@ -636,6 +636,8 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
                 variant?: "link" | "primary" | "secondary" | "danger" | "ghost" | undefined;
                 confirmText?: string | undefined;
                 successMessage?: string | undefined;
+                errorMessage?: string | undefined;
+                undoable?: boolean | undefined;
                 resultDialog?: {
                     title?: string | undefined;
                     description?: string | undefined;
@@ -1065,6 +1067,30 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         id: any;
         record: any;
     }>;
+    /**
+     * Clone a record — read the source, drop engine-owned columns, and
+     * insert a fresh copy. Gated by the object's `enable.clone` capability
+     * (default `true`; only an explicit `enable.clone === false` disables it).
+     *
+     * Shallow by design: it duplicates the record's own scalar/business field
+     * values, not its related child records. The insert path re-stamps audit
+     * columns, regenerates `autonumber` fields, and recomputes derived
+     * (`formula`/`summary`) fields, so the copy is a valid new row rather than
+     * a byte-identical twin. Caller-supplied `overrides` are applied last and
+     * win over the copied values — the natural place to set a new `name`,
+     * clear a unique field, or reset status before insert.
+     */
+    cloneData(request: {
+        object: string;
+        id: string;
+        overrides?: Record<string, any>;
+        context?: any;
+    }): Promise<{
+        object: string;
+        id: any;
+        sourceId: string;
+        record: any;
+    }>;
     updateData(request: {
         object: string;
         id: string;
@@ -1137,49 +1163,6 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         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;
@@ -1999,6 +1982,23 @@ interface OperationContext {
     context?: ExecutionContext;
     result?: any;
 }
+/**
+ * Trailing options for the READ methods (find / findOne / count / aggregate).
+ *
+ * Historically the read methods took their execution context INSIDE the query
+ * (`query.context`), while the WRITE methods (insert / update) took it in a
+ * trailing `options.context`. That split was a footgun: the same `{ context }`
+ * object is correct as the 3rd arg to `insert` but was SILENTLY DROPPED as the
+ * 3rd arg to `find` — a class of bugs where an intended `isSystem` bypass just
+ * vanished (e.g. control-plane reads coming back empty once org-scoping hooks
+ * were added). We now ALSO accept `context` via this trailing options arg on the
+ * read methods, so "execution context goes in the trailing options argument" is
+ * one rule across reads and writes. `query.context` remains supported; when both
+ * are given, `options.context` wins (it is the explicit channel).
+ */
+interface EngineReadOptions {
+    context?: ExecutionContext;
+}
 /**
  * Engine Middleware (Onion model)
  */
@@ -2418,8 +2418,8 @@ declare class ObjectQL implements IDataEngine {
      * @returns Records with expanded lookup fields (IDs replaced by full objects)
      */
     private expandRelatedRecords;
-    find(object: string, query?: EngineQueryOptions): Promise<any[]>;
-    findOne(objectName: string, query?: EngineQueryOptions): Promise<any>;
+    find(object: string, query?: EngineQueryOptions, options?: EngineReadOptions): Promise<any[]>;
+    findOne(objectName: string, query?: EngineQueryOptions, options?: EngineReadOptions): Promise<any>;
     insert(object: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
     update(object: string, data: any, options?: EngineUpdateOptions): Promise<any>;
     /**
@@ -2431,13 +2431,16 @@ declare class ObjectQL implements IDataEngine {
      *   - `set_null` → clear the foreign key,
      *   - `restrict` → refuse the delete when dependents exist.
      * `master_detail` defaults to `cascade` (the parent owns the child
-     * lifecycle); `lookup` defaults to `set_null`. Only runs for single-id
+     * lifecycle); `lookup` defaults to `set_null` — except a `set_null` default
+     * on a REQUIRED lookup escalates to `restrict` (you can't null a NOT NULL
+     * FK; restricting with a clear dependent-count message beats a misleading
+     * "<field> is required" 400 from the child). Only runs for single-id
      * deletes — multi/predicate deletes skip cascade (logged).
      */
     private cascadeDeleteRelations;
     delete(object: string, options?: EngineDeleteOptions): Promise<any>;
-    count(object: string, query?: EngineCountOptions): Promise<number>;
-    aggregate(object: string, query: EngineAggregateOptions): Promise<any[]>;
+    count(object: string, query?: EngineCountOptions, options?: EngineReadOptions): Promise<number>;
+    aggregate(object: string, query: EngineAggregateOptions, options?: EngineReadOptions): Promise<any[]>;
     /**
      * Run raw driver-specific commands (SQL for SqlDriver, REST for RestDriver, …).
      *
@@ -2674,13 +2677,25 @@ declare class ScopedContext {
 /**
  * Group + aggregate raw rows according to the AST's `groupBy` /
  * `aggregations`. When neither is present, returns the rows unchanged.
+ *
+ * `timezone` (ADR-0053 Phase 2) shifts date bucketing to a reference timezone
+ * so a row near a tz day-boundary lands in the right day/week/month/quarter.
+ * It is only consulted by `groupBy` items carrying a `dateGranularity`; an
+ * unset or `'UTC'` value keeps the historical UTC bucketing.
  */
-declare function applyInMemoryAggregation(rows: any[], ast: Pick<QueryAST, 'groupBy' | 'aggregations'>): any[];
+declare function applyInMemoryAggregation(rows: any[], ast: Pick<QueryAST, 'groupBy' | 'aggregations'>, timezone?: string): any[];
 /**
  * Bucket a date-like value into an ISO-formatted period label. Weeks start
  * Monday and use ISO week numbering.
+ *
+ * `timezone` (ADR-0053 Phase 2) resolves the calendar day in a reference zone
+ * so an instant near a tz day-boundary buckets where a user in that zone would
+ * expect. An unset / `'UTC'` / invalid zone keeps the historical UTC bucketing.
+ * The y/m/d are taken in the reference zone and the ISO-week math then runs on
+ * a UTC date built from those parts — the parts already carry the zone shift,
+ * so the week boundary lands correctly without re-applying any offset.
  */
-declare function bucketDateValue(value: unknown, granularity: DateGranularityValue): string;
+declare function bucketDateValue(value: unknown, granularity: DateGranularityValue, timezone?: string): string;
 
 /**
  * Hook Execution Metrics
@@ -2876,7 +2891,7 @@ declare function wrapDeclarativeHook(meta: Hook, handler: HookHandler, opts?: Wr
 
 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' | 'invalid_transition' | 'rule_violation' | 'invalid_format' | 'invalid_json' | 'json_schema_violation';
+    code: 'required' | 'min_length' | 'max_length' | 'min_value' | 'max_value' | 'invalid_email' | 'invalid_url' | 'invalid_phone' | 'invalid_number' | 'invalid_boolean' | 'invalid_date' | 'invalid_time' | 'invalid_option' | 'invalid_transition' | 'rule_violation' | 'invalid_format' | 'invalid_json' | 'json_schema_violation';
     message: string;
     /** Allowed values for select/multiselect, when applicable. */
     options?: string[];