@lotics/app-sdk 0.125.6 → 0.125.8

package/dist/index.js

@@ -5779,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);
@@ -6091,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();
@@ -6363,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);
@@ -6388,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);
@@ -6886,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
     // ========================================================================
     /**
@@ -7386,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/data_fetching.md

@@ -246,9 +246,9 @@ Reads paginate two different ways, and the difference is load-bearing:
   opaque cursor instead of counting an offset, so a deep scroll stays O(page) and — the reason it
   matters — **never skips or duplicates a row as the set shifts** under concurrent inserts/deletes.
   The cursor is internal: the hook sends it and reads the next one back; you never see it. The
-  server keysets a single sortable key (the runtime `sort`, else the template's own order on a
-  column it projects, else the record id) and falls back to offset transparently for a multi-key
-  sort, or a `first` key, it can't seek. So an infinite feed needs **no
+  server keysets the sort's column keys (the runtime `sort`, else the template's own order on the
+  columns it projects, else the record id) and falls back to offset transparently for a `first`
+  key it can't seek. So an infinite feed needs **no
   dedupe** — key rows by `__source_record_id` for stable React keys, not to guard against repeats.
 - **`page`, `limit`, `queryAll` and manual `rpc("query", { limit, offset })` use offset
   pagination** — count `offset` rows, skip them, return the next page. Two consequences a keyset

package/docs/queries.md

@@ -878,7 +878,7 @@ template as derived nodes, in this order: `filter` (narrow) → `sort` (order)
   `offset` (`limit` clamped to the 10,000-row cap, §10); `useQuery` with `more` opts into **keyset
   (seek)** by sending `keyset: true` + the prior page's `cursor`, and the server returns the next
   `next_cursor` (null on the last page). Seek stays O(page) and never skips/duplicates a row as the
-  set shifts, falling back to offset for a multi-key sort, or a `first` key, it can't seek.
+  set shifts, falling back to offset for a `first` key it can't seek.
 - **`count: true`** — returns `{ total }` only: a COUNT over the *filtered* set, ignoring
   sort/limit/offset. Drives "Page 1 of N". With **`count_by: "<column>"`** the same scan also
   returns `counts` — rows per value of that projected column (a multi-value row under each value,

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.6",
+  "version": "0.125.8",
   "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": {