@objectstack/objectql 9.7.0 → 9.9.0

package/dist/index.js

@@ -2832,6 +2832,13 @@ function normaliseVersionToken(v) {
   }
   return s;
 }
+var CLONE_STRIP_FIELDS = [
+  "id",
+  "created_at",
+  "created_by",
+  "updated_at",
+  "updated_by"
+];
 var SERVICE_CONFIG = {
   auth: { route: "/api/v1/auth", plugin: "plugin-auth" },
   automation: { route: "/api/v1/automation", plugin: "plugin-automation" },
@@ -4087,6 +4094,68 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
       record: result
     };
   }
+  /**
+   * 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.
+   */
+  async cloneData(request) {
+    const schema = this.engine.registry.getObject(request.object);
+    if (!schema) {
+      const err = new Error(`Object '${request.object}' not found`);
+      err.code = "OBJECT_NOT_FOUND";
+      err.status = 404;
+      err.object = request.object;
+      throw err;
+    }
+    if (schema.enable?.clone === false) {
+      const err = new Error(`Cloning is disabled for object '${request.object}'`);
+      err.code = "CLONE_DISABLED";
+      err.status = 403;
+      err.object = request.object;
+      throw err;
+    }
+    const ctx = request.context;
+    const ctxOpt = ctx !== void 0 ? { context: ctx } : void 0;
+    const source = await this.engine.findOne(
+      request.object,
+      { where: { id: request.id }, ...ctxOpt }
+    );
+    if (!source) {
+      const err = new Error(`Record ${request.id} not found in ${request.object}`);
+      err.code = "RECORD_NOT_FOUND";
+      err.status = 404;
+      err.object = request.object;
+      throw err;
+    }
+    const data = { ...source };
+    for (const f of CLONE_STRIP_FIELDS) delete data[f];
+    const fields = schema.fields || {};
+    for (const [name, def] of Object.entries(fields)) {
+      if (!def) continue;
+      if (def.system === true || def.type === "autonumber" || def.type === "formula" || def.type === "summary") {
+        delete data[name];
+      }
+    }
+    if (request.overrides && typeof request.overrides === "object") {
+      Object.assign(data, request.overrides);
+    }
+    const result = await this.engine.insert(request.object, data, ctxOpt);
+    return {
+      object: request.object,
+      id: result.id,
+      sourceId: request.id,
+      record: result
+    };
+  }
   async updateData(request) {
     await this.assertVersionMatch(request.object, request.id, request.expectedVersion, request.context);
     const opts = { where: { id: request.id } };
@@ -4276,145 +4345,6 @@ var _ObjectStackProtocolImplementation = class _ObjectStackProtocolImplementatio
     };
   }
   // ==========================================
-  // Lead Convert (M10.6)
-  // ==========================================
-  /**
-   * 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.
-   */
-  async convertLead(request) {
-    const leadId = String(request.leadId || "").trim();
-    if (!leadId) {
-      const err = new Error("leadId is required");
-      err.status = 400;
-      err.code = "INVALID_REQUEST";
-      throw err;
-    }
-    const ctx = request.context;
-    const ctxOpt = ctx !== void 0 ? { context: ctx } : void 0;
-    const lead = await this.engine.findOne("lead", { where: { id: leadId }, ...ctxOpt });
-    if (!lead) {
-      const err = new Error(`Lead '${leadId}' not found`);
-      err.status = 404;
-      err.code = "LEAD_NOT_FOUND";
-      throw err;
-    }
-    if (lead.is_converted) {
-      const err = new Error(`Lead '${leadId}' is already converted`);
-      err.status = 409;
-      err.code = "LEAD_ALREADY_CONVERTED";
-      throw err;
-    }
-    const runConversion = async (trxCtx) => {
-      const opCtx = trxCtx ?? ctx;
-      const trxCtxOpt = opCtx !== void 0 ? { context: opCtx } : void 0;
-      let account;
-      if (request.accountId) {
-        account = await this.engine.findOne("account", { where: { id: request.accountId }, ...trxCtxOpt });
-        if (!account) {
-          const err = new Error(`Account '${request.accountId}' not found`);
-          err.status = 404;
-          err.code = "ACCOUNT_NOT_FOUND";
-          throw err;
-        }
-      } else {
-        const accountPayload = {
-          name: lead.company || `${lead.first_name ?? ""} ${lead.last_name ?? ""}`.trim() || "Untitled Account"
-        };
-        if (lead.industry) accountPayload.industry = lead.industry;
-        if (lead.annual_revenue) accountPayload.annual_revenue = lead.annual_revenue;
-        if (lead.number_of_employees) accountPayload.employees = lead.number_of_employees;
-        if (lead.website) accountPayload.website = lead.website;
-        if (lead.phone) accountPayload.phone = lead.phone;
-        if (lead.address) accountPayload.billing_address = lead.address;
-        if (lead.owner) accountPayload.owner = lead.owner;
-        account = await this.engine.insert("account", accountPayload, trxCtxOpt);
-      }
-      let contact;
-      if (request.contactId) {
-        contact = await this.engine.findOne("contact", { where: { id: request.contactId }, ...trxCtxOpt });
-        if (!contact) {
-          const err = new Error(`Contact '${request.contactId}' not found`);
-          err.status = 404;
-          err.code = "CONTACT_NOT_FOUND";
-          throw err;
-        }
-      } else {
-        const contactPayload = {
-          first_name: lead.first_name ?? "",
-          last_name: lead.last_name ?? lead.company ?? "Unknown"
-        };
-        if (lead.salutation) contactPayload.salutation = lead.salutation;
-        if (lead.email) contactPayload.email = lead.email;
-        if (lead.phone) contactPayload.phone = lead.phone;
-        if (lead.mobile) contactPayload.mobile = lead.mobile;
-        if (lead.title) contactPayload.title = lead.title;
-        if (lead.address) contactPayload.mailing_address = lead.address;
-        if (lead.owner) contactPayload.owner = lead.owner;
-        if (account?.id) contactPayload.account = account.id;
-        contact = await this.engine.insert("contact", contactPayload, trxCtxOpt);
-      }
-      let opportunity = null;
-      const shouldCreateOpp = request.createOpportunity !== false;
-      if (shouldCreateOpp) {
-        const oppOverrides = request.opportunity ?? {};
-        const defaultName = oppOverrides.name || `${account?.name ?? lead.company ?? "Lead"} - New Opportunity`;
-        const defaultClose = oppOverrides.close_date || new Date(Date.now() + 30 * 24 * 60 * 60 * 1e3).toISOString().slice(0, 10);
-        const oppPayload = {
-          name: defaultName,
-          stage: oppOverrides.stage ?? "qualification",
-          close_date: defaultClose
-        };
-        if (oppOverrides.amount !== void 0) oppPayload.amount = oppOverrides.amount;
-        else if (lead.annual_revenue) oppPayload.amount = lead.annual_revenue;
-        if (account?.id) oppPayload.account = account.id;
-        if (contact?.id) oppPayload.primary_contact = contact.id;
-        if (lead.owner) oppPayload.owner = lead.owner;
-        if (lead.lead_source) oppPayload.lead_source = lead.lead_source;
-        opportunity = await this.engine.insert("opportunity", oppPayload, trxCtxOpt);
-      }
-      const leadUpdate = {
-        is_converted: true,
-        status: request.convertedStatus ?? "converted",
-        converted_account: account?.id ?? null,
-        converted_contact: contact?.id ?? null,
-        converted_opportunity: opportunity?.id ?? null,
-        converted_date: (/* @__PURE__ */ new Date()).toISOString()
-      };
-      const updatedLead = await this.engine.update("lead", leadUpdate, {
-        where: { id: leadId },
-        ...trxCtxOpt
-      });
-      return {
-        lead: updatedLead ?? { ...lead, ...leadUpdate },
-        account,
-        contact,
-        opportunity
-      };
-    };
-    return this.engine.transaction(runConversion, ctx);
-  }
-  // ==========================================
   // Metadata Caching
   // ==========================================
   async getMetaItemCached(request) {
@@ -6247,7 +6177,7 @@ var ObjectStackProtocolImplementation = _ObjectStackProtocolImplementation;
 // src/engine.ts
 var import_node_async_hooks = require("async_hooks");
 var import_kernel6 = require("@objectstack/spec/kernel");
-var import_core = require("@objectstack/core");
+var import_core2 = require("@objectstack/core");
 var import_system2 = require("@objectstack/spec/system");
 
 // src/secret-fields.ts
@@ -6778,11 +6708,20 @@ function validateOne(name, def, value) {
     if (value === 0 || value === 1 || value === "0" || value === "1" || value === "true" || value === "false") return null;
     return { field: name, code: "invalid_boolean", message: `${name} must be true or false` };
   }
-  if (t === "date" || t === "datetime" || t === "time") {
+  if (t === "date" || t === "datetime") {
     if (value instanceof Date) return null;
     if (typeof value === "string" && !Number.isNaN(Date.parse(value))) return null;
     return { field: name, code: "invalid_date", message: `${name} must be a valid ${t} (ISO-8601)` };
   }
+  if (t === "time") {
+    if (value instanceof Date) return null;
+    if (typeof value === "string") {
+      const timeOfDay = /^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d(\.\d+)?)?(Z|[+-]([01]\d|2[0-3]):?[0-5]\d)?$/;
+      const hasDate = /\d{4}-\d{2}-\d{2}/.test(value);
+      if (timeOfDay.test(value.trim()) || hasDate && !Number.isNaN(Date.parse(value))) return null;
+    }
+    return { field: name, code: "invalid_time", message: `${name} must be a valid time (HH:MM or HH:MM:SS)` };
+  }
   if (t === "select" || t === "radio") {
     const allowed = optionValues(def.options);
     if (allowed.length > 0 && !allowed.includes(String(value))) {
@@ -7098,7 +7037,8 @@ function legalNextStates(objectSchema, field, currentState) {
 }
 
 // src/in-memory-aggregation.ts
-function applyInMemoryAggregation(rows, ast) {
+var import_core = require("@objectstack/core");
+function applyInMemoryAggregation(rows, ast, timezone) {
   const groupBy = ast.groupBy ?? [];
   const aggregations = ast.aggregations ?? [];
   if (groupBy.length === 0 && aggregations.length === 0) return rows;
@@ -7111,7 +7051,7 @@ function applyInMemoryAggregation(rows, ast) {
     const parts = [];
     for (const g of groupBy) {
       const fieldName = typeof g === "string" ? g : g.alias ?? g.field;
-      const value = projectGroupValue(row, g);
+      const value = projectGroupValue(row, g, timezone);
       key[fieldName] = value;
       parts.push(`${fieldName}=${value}`);
     }
@@ -7130,11 +7070,11 @@ function applyInMemoryAggregation(rows, ast) {
   }
   return out;
 }
-function projectGroupValue(row, g) {
+function projectGroupValue(row, g, timezone) {
   const field = typeof g === "string" ? g : g.field;
   const v = row?.[field];
   if (typeof g !== "string" && g.dateGranularity) {
-    return bucketDateValue(v, g.dateGranularity);
+    return bucketDateValue(v, g.dateGranularity, timezone);
   }
   return v == null ? "(null)" : String(v);
 }
@@ -7212,12 +7152,11 @@ function toNumber(v) {
   const n = Number(v);
   return Number.isFinite(n) ? n : 0;
 }
-function bucketDateValue(value, granularity) {
+function bucketDateValue(value, granularity, timezone) {
   if (value == null) return "(null)";
   const d = value instanceof Date ? value : new Date(String(value));
   if (Number.isNaN(d.getTime())) return "(null)";
-  const y = d.getUTCFullYear();
-  const m = d.getUTCMonth() + 1;
+  const { year: y, month: m, day } = (0, import_core.calendarPartsInTzOrUtc)(d, timezone);
   switch (granularity) {
     case "year":
       return String(y);
@@ -7226,9 +7165,9 @@ function bucketDateValue(value, granularity) {
     case "month":
       return `${y}-${String(m).padStart(2, "0")}`;
     case "day":
-      return `${y}-${String(m).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`;
+      return `${y}-${String(m).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
     case "week": {
-      const target = new Date(Date.UTC(y, d.getUTCMonth(), d.getUTCDate()));
+      const target = new Date(Date.UTC(y, m - 1, day));
       const dayNum = (target.getUTCDay() + 6) % 7;
       target.setUTCDate(target.getUTCDate() - dayNum + 3);
       const firstThursday = new Date(Date.UTC(target.getUTCFullYear(), 0, 4));
@@ -7271,16 +7210,25 @@ function planFormulaProjection(schema, requestedFields) {
   }
   return { plan };
 }
-function applyFormulaPlan(plan, records) {
+function applyFormulaPlan(plan, records, execCtx, nowSnapshot) {
   if (!plan.length) return;
+  const now = nowSnapshot ?? /* @__PURE__ */ new Date();
+  const timezone = execCtx?.timezone;
+  const user = execCtx?.userId ? { id: String(execCtx.userId), role: execCtx?.roles?.[0] } : void 0;
+  const org = execCtx?.tenantId ? { id: String(execCtx.tenantId) } : void 0;
   for (const rec of records) {
     if (rec == null) continue;
     for (const fp of plan) {
-      const r = import_formula4.ExpressionEngine.evaluate(fp.expression, { record: rec });
+      const r = import_formula4.ExpressionEngine.evaluate(fp.expression, { now, timezone, user, org, record: rec });
       rec[fp.name] = r.ok ? r.value : null;
     }
   }
 }
+function mergeReadContext(fromQuery, fromOptions) {
+  if (fromOptions == null) return fromQuery;
+  if (fromQuery == null) return fromOptions;
+  return { ...fromQuery, ...fromOptions };
+}
 function resolveMetadataItemName(key, item) {
   if (!item) return void 0;
   if (item.name) return item.name;
@@ -7349,7 +7297,7 @@ var _ObjectQL = class _ObjectQL {
      *  parent objects that aggregate it. Invalidated when packages register. */
     this.summaryIndex = null;
     this.hostContext = hostContext;
-    this.logger = hostContext.logger || (0, import_core.createLogger)({ level: "info", format: "pretty" });
+    this.logger = hostContext.logger || (0, import_core2.createLogger)({ level: "info", format: "pretty" });
     if (process?.env?.OBJECTQL_STRICT_HOOKS === "1") {
       this._strictHookBinding = true;
     }
@@ -7703,6 +7651,7 @@ var _ObjectQL = class _ObjectQL {
       if (typeof dv === "object" && dv !== null && dv.dialect && typeof dv.source === "string") {
         const result = import_formula4.ExpressionEngine.evaluate(dv, {
           now,
+          timezone: execCtx?.timezone,
           user: execCtx?.userId ? { id: String(execCtx.userId), role: execCtx?.roles?.[0] } : void 0,
           org: execCtx?.tenantId ? { id: String(execCtx.tenantId) } : void 0,
           record: out,
@@ -8594,7 +8543,7 @@ var _ObjectQL = class _ObjectQL {
   // ============================================
   // Data Access Methods (IDataEngine Interface)
   // ============================================
-  async find(object, query) {
+  async find(object, query, options) {
     object = this.resolveObjectName(object);
     this.logger.debug("Find operation starting", { object, query });
     const driver = this.getDriver(object);
@@ -8623,7 +8572,7 @@ var _ObjectQL = class _ObjectQL {
       operation: "find",
       ast,
       options: query,
-      context: query?.context
+      context: mergeReadContext(query?.context, options?.context)
     };
     await this.executeWithMiddleware(opCtx, async () => {
       const hookContext = {
@@ -8639,7 +8588,7 @@ var _ObjectQL = class _ObjectQL {
       hookContext.input.options = this.buildDriverOptions(opCtx.context, hookContext.input.options);
       try {
         let result = await driver.find(object, hookContext.input.ast, hookContext.input.options);
-        if (Array.isArray(result)) applyFormulaPlan(_findFormula.plan, result);
+        if (Array.isArray(result)) applyFormulaPlan(_findFormula.plan, result, opCtx.context);
         if (ast.expand && Object.keys(ast.expand).length > 0 && Array.isArray(result)) {
           result = await this.expandRelatedRecords(object, result, ast.expand, 0, opCtx.context);
         }
@@ -8655,7 +8604,7 @@ var _ObjectQL = class _ObjectQL {
     });
     return opCtx.result;
   }
-  async findOne(objectName, query) {
+  async findOne(objectName, query, options) {
     objectName = this.resolveObjectName(objectName);
     this.logger.debug("FindOne operation", { objectName });
     const driver = this.getDriver(objectName);
@@ -8678,12 +8627,12 @@ var _ObjectQL = class _ObjectQL {
       operation: "findOne",
       ast,
       options: query,
-      context: query?.context
+      context: mergeReadContext(query?.context, options?.context)
     };
     await this.executeWithMiddleware(opCtx, async () => {
       const findOneOpts = this.buildDriverOptions(opCtx.context);
       let result = await driver.findOne(objectName, opCtx.ast, findOneOpts);
-      if (result != null) applyFormulaPlan(_findOneFormula.plan, [result]);
+      if (result != null) applyFormulaPlan(_findOneFormula.plan, [result], opCtx.context);
       if (ast.expand && Object.keys(ast.expand).length > 0 && result != null) {
         const expanded = await this.expandRelatedRecords(objectName, [result], ast.expand, 0, opCtx.context);
         result = expanded[0];
@@ -8898,7 +8847,10 @@ var _ObjectQL = class _ObjectQL {
    *   - `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).
    */
   async cascadeDeleteRelations(object, id, context, depth = 0) {
@@ -8924,7 +8876,10 @@ var _ObjectQL = class _ObjectQL {
           resolvedRef = void 0;
         }
         if (ref !== object && resolvedRef !== object) continue;
-        const behavior = fdef.type === "master_detail" ? fdef.deleteBehavior === "restrict" ? "restrict" : "cascade" : fdef.deleteBehavior || "set_null";
+        let behavior = fdef.type === "master_detail" ? fdef.deleteBehavior === "restrict" ? "restrict" : "cascade" : fdef.deleteBehavior || "set_null";
+        if (behavior === "set_null" && fdef.required === true) {
+          behavior = "restrict";
+        }
         let dependents;
         try {
           dependents = await this.find(childName, { where: { [fieldName]: id }, context });
@@ -8933,9 +8888,16 @@ var _ObjectQL = class _ObjectQL {
         }
         if (!dependents || dependents.length === 0) continue;
         if (behavior === "restrict") {
-          throw new Error(
-            `Cannot delete ${object} (${id}): ${dependents.length} dependent ${childName} record(s) via ${fieldName}`
+          const reason = fdef.deleteBehavior !== "restrict" && fdef.required === true ? ` (${fieldName} is required, so it cannot be cleared)` : "";
+          const err = new Error(
+            `Cannot delete ${object} (${id}): ${dependents.length} dependent ${childName} record(s) reference it via ${fieldName}${reason}. Delete or reassign them first, or set deleteBehavior:'cascade' on ${childName}.${fieldName}.`
           );
+          err.code = "DELETE_RESTRICTED";
+          err.status = 409;
+          err.object = object;
+          err.dependentObject = childName;
+          err.dependentCount = dependents.length;
+          throw err;
         }
         for (const dep of dependents) {
           const depId = dep?.id;
@@ -9024,14 +8986,14 @@ var _ObjectQL = class _ObjectQL {
     });
     return opCtx.result;
   }
-  async count(object, query) {
+  async count(object, query, options) {
     object = this.resolveObjectName(object);
     const driver = this.getDriver(object);
     const opCtx = {
       object,
       operation: "count",
       options: query,
-      context: query?.context
+      context: mergeReadContext(query?.context, options?.context)
     };
     await this.executeWithMiddleware(opCtx, async () => {
       const countOpts = this.buildDriverOptions(opCtx.context);
@@ -9044,7 +9006,7 @@ var _ObjectQL = class _ObjectQL {
     });
     return opCtx.result;
   }
-  async aggregate(object, query) {
+  async aggregate(object, query, options) {
     object = this.resolveObjectName(object);
     const driver = this.getDriver(object);
     this.logger.debug(`Aggregate on ${object} using ${driver.name}`, query);
@@ -9052,7 +9014,7 @@ var _ObjectQL = class _ObjectQL {
       object,
       operation: "aggregate",
       options: query,
-      context: query?.context
+      context: mergeReadContext(query?.context, options?.context)
     };
     await this.executeWithMiddleware(opCtx, async () => {
       const ast = {
@@ -9069,11 +9031,14 @@ var _ObjectQL = class _ObjectQL {
         if (!g?.dateGranularity) return true;
         return granularityCaps?.[g.dateGranularity] === true;
       });
-      if (typeof drv.aggregate === "function" && allStructuredSupported) {
+      const tz = query.timezone;
+      const hasDateBucket = structuredItems.some((g) => !!g?.dateGranularity);
+      const tzRequiresInMemory = !!tz && tz !== "UTC" && hasDateBucket;
+      if (typeof drv.aggregate === "function" && allStructuredSupported && !tzRequiresInMemory) {
         return drv.aggregate(object, ast, this.buildDriverOptions(opCtx.context));
       }
       const raw = await driver.find(object, ast, this.buildDriverOptions(opCtx.context));
-      return applyInMemoryAggregation(raw, ast);
+      return applyInMemoryAggregation(raw, ast, tz);
     });
     return opCtx.result;
   }
@@ -10280,9 +10245,9 @@ var ObjectQLPlugin = class {
 };
 
 // src/kernel-factory.ts
-var import_core2 = require("@objectstack/core");
+var import_core3 = require("@objectstack/core");
 async function createObjectQLKernel(options = {}) {
-  const kernel = new import_core2.ObjectKernel();
+  const kernel = new import_core3.ObjectKernel();
   await kernel.use(new ObjectQLPlugin());
   if (options.plugins) {
     for (const plugin of options.plugins) {