@ganju/utils 0.0.21 → 0.0.22

package/src/data.ts

@@ -65,9 +65,12 @@ export {
   writeReachesCopy,
   assertActor,
   assertWritable,
+  assertNotSynced,
+  syncRows,
+  recordSyncFailure,
   exportRows
 } from './dataEngine';
-export type { SqlRow, SqlRunner } from './dataEngine';
+export type { SqlRow, SqlRunner, SheetSyncArgs } from './dataEngine';
 export { adviseIndexes, adviceDoubled } from './dataIndexAdvice';
 export type {
   IndexAdviceCandidate,
@@ -118,6 +121,7 @@ export {
 export type { DataToolDefinition, DataAdminAction } from './dataTools';
 export {
   DATA_TRIGGER_EVENTS,
+  DATA_CHANGE_EVENTS,
   DATA_TRIGGER_ACTIONS,
   DATA_MAX_TRIGGERS,
   DATA_TRIGGER_MAX_DEPTH,
@@ -125,6 +129,12 @@ export {
   DATA_TRIGGER_MAX_RATE,
   DATA_OUTBOX_BATCH,
   DATA_TRIGGER_MAX_MESSAGE_BYTES,
+  DATA_TIME_SCAN_MS,
+  DATA_TIME_MIN_MINUTES,
+  DATA_TIME_MAX_MINUTES,
+  DATA_MAX_TIME_TRIGGERS,
+  DATA_TIME_EVENTS_PER_SCAN,
+  DATA_TIME_EVENTS_PER_DAY,
   utf8Bytes,
   conditionMatches,
   renderTriggerText,
@@ -144,7 +154,11 @@ export {
   outboxSize,
   clearOutbox,
   triggersUsingColumn,
-  renameColumnInTriggers
+  renameColumnInTriggers,
+  timeTriggersCountingFrom,
+  syncTimeIndexes,
+  hasTimeTriggers,
+  scanTimeTriggers
 } from './dataTriggers';
 export type {
   DataTrigger,
@@ -155,8 +169,10 @@ export type {
   DataTriggerEvent,
   DataTriggerEventMessage,
   DataTriggerInput,
+  DataTriggerSchedule,
   DataTriggerTemplate,
   DataTriggerTest,
   DataTriggerWithSecret,
-  SavedTrigger
+  SavedTrigger,
+  TimeScanResult
 } from './dataTriggers';

package/src/dataApi.ts

@@ -27,7 +27,7 @@ export interface DataApiRoute {
   query?: z.ZodObject;
   // What a 200/201 answers with, in a sentence.
   returns: string;
-  status?: 200 | 201;
+  status?: 200 | 201 | 202;
   // Answers with a file instead of JSON.
   file?: boolean;
 }
@@ -179,9 +179,21 @@ export const DATA_API_ROUTES = {
     path: '/table/:table',
     tag: 'Tables',
     summary: 'Rename a table or change its settings',
+    description:
+      "`source` (`{ uri, sheet?, key }`) keeps the table's rows in step with a spreadsheet or CSV in the project's knowledge, matched by `key`, a unique column: the sheet wins, and row writes to the table are refused until `source` is set back to null. It syncs when the file changes and from `POST …/sync`; `sync` on the table says how the last one went.",
     body: DATA_TABLE_PATCH,
     returns: '{ table }'
   },
+  syncTable: {
+    method: 'post',
+    path: '/table/:table/sync',
+    tag: 'Tables',
+    summary: 'Sync a table from its sheet now',
+    description:
+      "Queues a sync of a table that has a `source`: a Google Drive or OneDrive file is fetched again first if it changed. New keys are inserted, rows that differ updated (actor `system:sheet-sync`, so triggers fire), rows whose key is gone deleted. A sheet that doesn't fit (a missing key column, a repeated key, a value a column won't take) changes nothing; the table's `sync` says why.",
+    returns: '{ queued: true }',
+    status: 202
+  },
   dropTable: {
     method: 'delete',
     path: '/table/:table',
@@ -347,7 +359,7 @@ export const DATA_API_ROUTES = {
     tag: 'Triggers',
     summary: 'Save a trigger',
     description:
-      'Runs one action when rows of `table` are inserted, updated or deleted, and `when` holds: `{ "status": { "changedTo": "READY" } }` fires on the transition only; `changedFrom`, `changed: true` and `equals` test a column too, and `all` / `any` combine them. The action is one of `function` (a function of this project, given `{ event, table, row, previous, actor, eventId, triggerId }`), `webhook` (an https URL, sent a POST signed in `x-ganju-signature`), `chat` (`{ channelId, chatId, text }`), `email` (`{ to, subject, text }`) or `customer` (`{ text, template? }`, to the row\'s customer on a customer-scoped table). Texts take `{{field}}` from the row, inserted as plain text. Saving under an existing name replaces it, unless `replace` is false; with no `name`, it always creates a new trigger, named from the table, event and action and numbered past those taken. Left out, `enabled` keeps a saved trigger on or off as it was. A new webhook answers with its signing `secret`, shown this once. An `email` goes to the organization\'s members; any other address is sent a link to confirm first, and those still waiting come back as `confirming`. Delivery is at least once: every event carries an `eventId`.',
+      'Runs one action when rows of `table` are inserted, updated or deleted, and `when` holds: `{ "status": { "changedTo": "READY" } }` fires on the transition only; `changedFrom`, `changed: true` and `equals` test a column too, and `all` / `any` combine them. With `"on": "time"` it fires instead once a row comes due, with nothing written: `after` is `{ column, minutes }`, the column `created_at`, `updated_at` or a date or datetime column (a date counts from midnight in the database\'s time zone) and `minutes` 5 to 43,200, negative on a date or datetime for before it. Its `when` tests `equals` only, read when the row comes due; rows already due when it is saved don\'t fire, and each row fires once per due time (an `updated_at` trigger again after the next change). Due rows are looked for every 5 minutes, up to 100 events per trigger per scan; a database holds up to 10 time triggers, and the database\'s time triggers share 2,000 events a day (UTC): past that, each time trigger with another row due that day is turned off and the organization\'s admins are emailed. A time trigger is also turned off when its runs are paused (the plan no longer includes Data, or the month\'s trigger runs reached the plan\'s limit). The action is one of `function` (a function of this project, given `{ event, table, row, previous, actor, eventId, triggerId, dueAt? }`), `webhook` (an https URL, sent a POST signed in `x-ganju-signature`), `chat` (`{ channelId, chatId, text }`), `email` (`{ to, subject, text }`) or `customer` (`{ text, template? }`, to the row\'s customer on a customer-scoped table). Texts take `{{field}}` from the row, inserted as plain text. Saving under an existing name replaces it, unless `replace` is false; with no `name`, it always creates a new trigger, named from the table, event and action and numbered past those taken. Left out, `enabled` keeps a saved trigger on or off as it was. A new webhook answers with its signing `secret`, shown this once. An `email` goes to the organization\'s members; any other address is sent a link to confirm first, and those still waiting come back as `confirming`. Delivery is at least once: every event carries an `eventId`.',
     body: DATA_TRIGGER_INPUT,
     returns: '{ trigger, secret?, confirming? }',
     status: 201

package/src/dataCompiler.ts

@@ -194,7 +194,10 @@ const LOCAL_DATETIME =
 // "2026-10-21T15:00:00" with no offset, read as a wall-clock time in
 // `timeZone` (UTC without one). `new Date()` would read it in the server's
 // zone: UTC on Workers, the developer's own zone on a laptop.
-const localDatetime = (value: string, timeZone?: string): Date | null => {
+export const localDatetime = (
+  value: string,
+  timeZone?: string
+): Date | null => {
   const m = LOCAL_DATETIME.exec(value.trim());
   if (!m) return null;
   const [year, month, day, hour, minute, second] = m