@lotics/app-sdk 0.125.5 → 0.125.7

package/dist/index.js

@@ -3306,6 +3306,10 @@ function length(value) {
   if (value == null) return 0;
   if (typeof value === "string") return value.length;
   if (Array.isArray(value)) return value.length;
+  if (typeof value === "object" && Object.hasOwn(value, "length")) {
+    const own = Reflect.get(value, "length");
+    if (typeof own === "number") return own;
+  }
   throw new ExpressionArgumentError("length: expected string or array, got " + typeof value);
 }
 function contains(str, search) {
@@ -5775,6 +5779,46 @@ function endOfDay(date2, options) {
   return _date;
 }
 
+// ../../node_modules/date-fns/startOfMonth.js
+function startOfMonth(date2, options) {
+  const _date = toDate(date2, options?.in);
+  _date.setDate(1);
+  _date.setHours(0, 0, 0, 0);
+  return _date;
+}
+
+// ../../node_modules/date-fns/endOfMonth.js
+function endOfMonth(date2, options) {
+  const _date = toDate(date2, options?.in);
+  const month = _date.getMonth();
+  _date.setFullYear(_date.getFullYear(), month + 1, 0);
+  _date.setHours(23, 59, 59, 999);
+  return _date;
+}
+
+// ../../node_modules/date-fns/addMonths.js
+function addMonths(date2, amount, options) {
+  const _date = toDate(date2, options?.in);
+  if (isNaN(amount)) return constructFrom(options?.in || date2, NaN);
+  if (!amount) {
+    return _date;
+  }
+  const dayOfMonth = _date.getDate();
+  const endOfDesiredMonth = constructFrom(options?.in || date2, _date.getTime());
+  endOfDesiredMonth.setMonth(_date.getMonth() + amount + 1, 0);
+  const daysInMonth = endOfDesiredMonth.getDate();
+  if (dayOfMonth >= daysInMonth) {
+    return endOfDesiredMonth;
+  } else {
+    _date.setFullYear(
+      endOfDesiredMonth.getFullYear(),
+      endOfDesiredMonth.getMonth(),
+      dayOfMonth
+    );
+    return _date;
+  }
+}
+
 // ../../node_modules/date-fns/isWithinInterval.js
 function isWithinInterval(date2, interval, options) {
   const time = +toDate(date2, options?.in);
@@ -6087,7 +6131,7 @@ function addDays2(dateStr, days) {
   date2.setDate(date2.getDate() + days);
   return formatDate(date2.getFullYear(), date2.getMonth() + 1, date2.getDate());
 }
-function addMonths(dateStr, months) {
+function addMonths2(dateStr, months) {
   const parsed = parseDate2(dateStr);
   const target = new Date(Date.UTC(parsed.year, parsed.month - 1 + months, 1));
   const lastDay = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
@@ -6359,7 +6403,7 @@ function resolveRelativePoint(offset, unit, fixedTime, timezone) {
       result = addYears(result, offset);
       break;
     case "months":
-      result = addMonths(result, offset);
+      result = addMonths2(result, offset);
       break;
     case "weeks":
       result = addDays2(result, offset * 7);
@@ -6384,10 +6428,10 @@ function resolvePeriodPoint(period, boundary, offset, fixedTime, timezone) {
         referenceDate = addDays2(referenceDate, offset * 7);
         break;
       case "month":
-        referenceDate = addMonths(referenceDate, offset);
+        referenceDate = addMonths2(referenceDate, offset);
         break;
       case "quarter":
-        referenceDate = addMonths(referenceDate, offset * 3);
+        referenceDate = addMonths2(referenceDate, offset * 3);
         break;
       case "year":
         referenceDate = addYears(referenceDate, offset);
@@ -6882,6 +6926,44 @@ function getDateExpressionFunctions(defaultTimezone) {
       return endOfDay(normalized).toISOString();
     },
     // ========================================================================
+    // MONTHS — payment terms ("30 days after month end") count from a month's edge
+    // ========================================================================
+    /**
+     * Get the first moment of the date's month in the workspace timezone. Returns ISO string, or null if date is null.
+     */
+    startOfMonth: (date2, timezone) => {
+      if (date2 == null || date2 === "") return null;
+      validateDateInput(date2, "date", "startOfMonth");
+      validateOptionalTimezone(timezone, "startOfMonth");
+      const tz = getTimezone(timezone);
+      const normalized = normalizeDateWithValidation(date2, tz, "startOfMonth");
+      return startOfMonth(tz ? new TZDate(normalized, tz) : normalized).toISOString();
+    },
+    /**
+     * Get the last moment of the date's month in the workspace timezone. Returns ISO string, or null if date is null.
+     */
+    endOfMonth: (date2, timezone) => {
+      if (date2 == null || date2 === "") return null;
+      validateDateInput(date2, "date", "endOfMonth");
+      validateOptionalTimezone(timezone, "endOfMonth");
+      const tz = getTimezone(timezone);
+      const normalized = normalizeDateWithValidation(date2, tz, "endOfMonth");
+      return endOfMonth(tz ? new TZDate(normalized, tz) : normalized).toISOString();
+    },
+    /**
+     * Add months to a date (negative subtracts); a day past the target month's end lands on its last day
+     * (31 Jan + 1 month is 28 or 29 Feb). Returns ISO string, or null if date is null.
+     */
+    addMonths: (date2, months, timezone) => {
+      if (date2 == null || date2 === "") return null;
+      validateDateInput(date2, "date", "addMonths");
+      validateNumber(months, "months", "addMonths");
+      validateOptionalTimezone(timezone, "addMonths");
+      const tz = getTimezone(timezone);
+      const normalized = normalizeDateWithValidation(date2, tz, "addMonths");
+      return addMonths(tz ? new TZDate(normalized, tz) : normalized, months).toISOString();
+    },
+    // ========================================================================
     // DATE DIFFERENCES
     // ========================================================================
     /**
@@ -7382,6 +7464,9 @@ var HELPER_COST = {
   subMinutes: "builds",
   startOfDay: "builds",
   endOfDay: "builds",
+  startOfMonth: "builds",
+  endOfMonth: "builds",
+  addMonths: "builds",
   differenceInCalendarDays: "reads",
   differenceInHours: "reads",
   differenceInMinutes: "reads",

package/docs/workflows.md

@@ -498,7 +498,7 @@ full menu by category, so a miss is one informed retry.
 | **Number** | `sum`, `sumBy`, `mean`, `meanBy`, `min`, `max`, `minBy`, `maxBy`, `round`, `ceil`, `floor`, `abs`, `mod`, `pow`, `sqrt`, `clamp`, `percentage` |
 | **String** | `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`, `replaceAll`, `removeChars(text, chars)` (without every character that occurs in `chars`), `removeSpaces(text)` (without any whitespace), `substring`, `length`, `split`, `join`, `padStart`, `padEnd`, `uuidFrom(text)` (the same UUID for the same text), `formatNumber(value, decimals)` (fixed-decimal, ungrouped), `formatDecimal(value, decimals, locale)` (grouped for a reader — `formatDecimal(151000, 0, "vi-VN")` → `151.000`), `numberToWords(x, lang?)` (`"vi"` or `"en"`) |
 | **Object** | `keys`, `values`, `entries`, `get`, `pick`, `omit`, `merge`, `nonNullKeys` |
-| **Date** | `now`, `formatDate`, `parseDate`, `addDays`, `subDays`, `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`, `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`, `isSameDay`, `isToday`, `isWithinRange`, `meetsBounds` |
+| **Date** | `now`, `formatDate`, `parseDate`, `addDays`, `subDays`, `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`, `startOfMonth`, `endOfMonth`, `addMonths`, `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`, `isSameDay`, `isToday`, `isWithinRange`, `meetsBounds` |
 | **Other** | `formatCurrency(amount, locale, currency)`, `randomNumber(len)`, `randomAlphaNumeric(len)`, `sample(items)`, `current_member_in_any_group(["grp_…"])`, `current_member_stands_in_for([memberId])`, `current_member_stands_in_for_any_group(["grp_…"])` |
 
 **Emptiness on a record cell.** `isNull` is the strict check — true only for `null`/`undefined`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.125.5",
+  "version": "0.125.7",
   "description": "The SDK a Lotics custom-code app reads and writes through — typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {