@ganju/utils 0.0.16 → 0.0.18

package/src/dataApi.ts

@@ -16,7 +16,13 @@ export interface DataApiRoute {
   path: string;
   summary: string;
   description?: string;
-  tag: 'Database' | 'Tables' | 'Rows' | 'History and export';
+  tag:
+    | 'Database'
+    | 'Tables'
+    | 'Rows'
+    | 'Queries'
+    | 'Triggers'
+    | 'History and export';
   body?: z.ZodType;
   query?: z.ZodObject;
   // What a 200/201 answers with, in a sentence.
@@ -29,6 +35,7 @@ export interface DataApiRoute {
 const {
   DATA_DATABASE_CREATE,
   DATA_DATABASE_DELETE,
+  DATA_DATABASE_PATCH,
   DATA_TABLE_INPUT,
   DATA_TABLE_PATCH,
   DATA_COLUMN_INPUT,
@@ -46,7 +53,13 @@ const {
   DATA_EXPORT_BODY,
   DATA_EXPORT_QUERY,
   DATA_EXPORT_FILE_QUERY,
-  DATA_CHANGE_LIST_QUERY
+  DATA_CHANGE_LIST_QUERY,
+  DATA_QUERY_INPUT,
+  DATA_QUERY_RUN_BODY,
+  DATA_TRIGGER_INPUT,
+  DATA_TRIGGER_PATCH,
+  DATA_TRIGGER_DEPLOY_BODY,
+  DATA_TRIGGER_RUN_LIST_QUERY
 } = Schema;
 
 export const DATA_API_ROUTES = {
@@ -70,6 +83,16 @@ export const DATA_API_ROUTES = {
     returns: '{ database }',
     status: 201
   },
+  updateDatabase: {
+    method: 'patch',
+    path: '',
+    tag: 'Database',
+    summary: "Change the database's settings",
+    description:
+      '`timeZone`, an IANA zone such as `America/Bogota`, or null for UTC. Datetimes come back in it for callers that send no `timeZone` of their own: the assistant, functions and scripts. Datetimes without an offset are read in it too.',
+    body: DATA_DATABASE_PATCH,
+    returns: '{ database }'
+  },
   remove: {
     method: 'delete',
     path: '',
@@ -253,6 +276,108 @@ export const DATA_API_ROUTES = {
     body: DATA_WRITE_BODY,
     returns: '{ results }'
   },
+  listQueries: {
+    method: 'get',
+    path: '/query',
+    tag: 'Queries',
+    summary: 'Named queries',
+    description:
+      'Each with its SQL, parameters, the tables it reads and its plan (`SCAN orders` means it reads the whole table).',
+    returns: '{ queries }'
+  },
+  saveQuery: {
+    method: 'post',
+    path: '/query',
+    tag: 'Queries',
+    summary: 'Save a named query',
+    description:
+      "One `SELECT` (or `WITH … SELECT`) with named parameters such as `:from`, each declared in `params` with its type. It is compiled, never run, and refused unless it only reads this database's tables. Saving under an existing name replaces it. `assistant: true` lets channel bots run it from data-query.",
+    body: DATA_QUERY_INPUT,
+    returns: '{ query }',
+    status: 201
+  },
+  dropQuery: {
+    method: 'delete',
+    path: '/query/:name',
+    tag: 'Queries',
+    summary: 'Delete a named query',
+    returns: '{ dropped }'
+  },
+  runQuery: {
+    method: 'post',
+    path: '/query/:name/run',
+    tag: 'Queries',
+    summary: 'Run a named query',
+    description:
+      'With its `params`, up to `limit` rows (100 by default, 500 at most) and 1 MB; `truncated` says it stopped early. A query that would scan a table over 200,000 rows is refused.',
+    body: DATA_QUERY_RUN_BODY,
+    returns: '{ query, rows, truncated? }'
+  },
+  listTriggers: {
+    method: 'get',
+    path: '/trigger',
+    tag: 'Triggers',
+    summary: 'Triggers',
+    description:
+      'Each with its table, event, condition and action. `pending` counts events not yet handed to the queue. Webhook secrets are never listed.',
+    returns: '{ triggers, pending }'
+  },
+  saveTrigger: {
+    method: 'post',
+    path: '/trigger',
+    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. Delivery is at least once: every event carries an `eventId`.',
+    body: DATA_TRIGGER_INPUT,
+    returns: '{ trigger, secret? }',
+    status: 201
+  },
+  updateTrigger: {
+    method: 'patch',
+    path: '/trigger/:name',
+    tag: 'Triggers',
+    summary: 'Turn a trigger on or off',
+    description:
+      'Turning one back on clears why Ganju turned it off (20 failed runs in a row).',
+    body: DATA_TRIGGER_PATCH,
+    returns: '{ trigger }'
+  },
+  dropTrigger: {
+    method: 'delete',
+    path: '/trigger/:name',
+    tag: 'Triggers',
+    summary: 'Delete a trigger',
+    returns: '{ dropped }'
+  },
+  deployTriggers: {
+    method: 'post',
+    path: '/trigger/deploy',
+    tag: 'Triggers',
+    summary: 'Deploy the triggers of ganju.json',
+    description:
+      "What `ganju deploy` sends: every trigger listed is saved as managed by the CLI, and the CLI's earlier ones not listed are deleted. Triggers made in the dashboard are left alone. All or nothing. New webhooks' secrets come back once, by name.",
+    body: DATA_TRIGGER_DEPLOY_BODY,
+    returns: '{ triggers, removed, secrets }'
+  },
+  listTriggerRuns: {
+    method: 'get',
+    path: '/trigger/:name/run',
+    tag: 'Triggers',
+    summary: "A trigger's recent runs",
+    description:
+      'Newest first, up to 50: `ok`, `failed` with its error, `skipped`, or `running`.',
+    query: DATA_TRIGGER_RUN_LIST_QUERY,
+    returns: '{ runs }'
+  },
+  retryTriggerRun: {
+    method: 'post',
+    path: '/trigger/:name/run/:runId/retry',
+    tag: 'Triggers',
+    summary: 'Run a failed event again',
+    description: 'The same event, with the same `eventId`.',
+    returns: '{ run }'
+  },
   startExport: {
     method: 'post',
     path: '/export',
@@ -397,6 +522,8 @@ export const dataOpenApi = (serverUrl: string) => {
       { name: 'Database' },
       { name: 'Tables' },
       { name: 'Rows' },
+      { name: 'Queries' },
+      { name: 'Triggers' },
       { name: 'History and export' }
     ],
     paths,

package/src/dataCompiler.ts

@@ -83,7 +83,11 @@ export const unknownColumn = (table: DataTable, name: string) =>
 // Access
 
 export const accessOf = (caller: DataCaller, table: DataTable): DataAccess =>
-  caller.restricted ? table.access : 'full';
+  caller.tables && !caller.tables.includes(table.name)
+    ? 'none'
+    : caller.restricted
+      ? table.access
+      : 'full';
 
 export const visibleTables = (schema: DataSchema, caller: DataCaller) =>
   schema.tables.filter(table => DATA_ACCESS_RANK[accessOf(caller, table)] >= 1);

package/src/dataCsv.ts

@@ -0,0 +1,99 @@
+/**
+ * Reading a CSV file into rows of text, with no parser package behind it:
+ * the CLI's import and the owner's data-admin tool read files the same way.
+ *
+ * RFC 4180 plus the two things spreadsheets actually write: a byte-order mark
+ * in front, and `;` between fields where the decimal mark is a comma (Excel in
+ * Spanish). The separator is read from the header line, so the same file
+ * exported from either locale imports the same way.
+ *
+ * Every cell comes back as text. Deciding what "28.000" means is the shared
+ * import code's job, so the CLI and the dashboard decide it the same way.
+ */
+
+export interface ParsedCsv {
+  headers: string[];
+  rows: string[][];
+  // The file line each row starts on, counting the header as line 1, since a
+  // quoted cell can span lines and blank lines are skipped.
+  lines: number[];
+}
+
+const SEPARATORS = [',', ';', '\t'] as const;
+
+// The separator that appears most in the first line, outside quotes.
+export const detectSeparator = (text: string): string => {
+  const counts = new Map<string, number>(SEPARATORS.map(s => [s, 0]));
+  let quoted = false;
+  for (const char of text) {
+    if (char === '"') quoted = !quoted;
+    else if (!quoted && (char === '\n' || char === '\r')) break;
+    else if (!quoted && counts.has(char))
+      counts.set(char, counts.get(char)! + 1);
+  }
+  let best = ',';
+  for (const [separator, count] of counts) {
+    if (count > counts.get(best)!) best = separator;
+  }
+  return best;
+};
+
+export const parseCsv = (input: string, separator?: string): ParsedCsv => {
+  const text = input.charCodeAt(0) === 0xfeff ? input.slice(1) : input;
+  const sep = separator ?? detectSeparator(text);
+  const records: { cells: string[]; line: number }[] = [];
+  let cells: string[] = [];
+  let cell = '';
+  let quoted = false;
+  let line = 1;
+  let startLine = 1;
+
+  const endCell = () => {
+    cells.push(cell);
+    cell = '';
+  };
+  const endRecord = () => {
+    endCell();
+    // A blank line, or one of nothing but separators, is not a row.
+    if (cells.some(c => c.trim() !== '')) {
+      records.push({ cells, line: startLine });
+    }
+    cells = [];
+  };
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (quoted) {
+      if (char === '"') {
+        if (text[i + 1] === '"') {
+          cell += '"';
+          i++;
+        } else quoted = false;
+      } else {
+        if (char === '\n') line++;
+        cell += char;
+      }
+      continue;
+    }
+    if (char === '"' && cell === '') {
+      quoted = true;
+    } else if (char === sep) {
+      endCell();
+    } else if (char === '\n' || char === '\r') {
+      if (char === '\r' && text[i + 1] === '\n') i++;
+      endRecord();
+      line++;
+      startLine = line;
+    } else {
+      cell += char;
+    }
+  }
+  if (cell !== '' || cells.length) endRecord();
+
+  const [header, ...body] = records;
+  return {
+    headers: (header?.cells ?? []).map(h => h.trim()),
+    rows: body.map(r => r.cells),
+    lines: body.map(r => r.line)
+  };
+};

package/src/dataDdl.ts

@@ -1,6 +1,7 @@
 // The SQL a project's database runs to build and change its tables. Pure
 // string building: every name in here passed identifierIssue or is one of
 // ours, and every owner-supplied value is a literal escaped by sqlLiteral.
+import { changeCaptureTriggers } from './dataTriggers';
 import { quoteIdentifier as q } from './dataIdentifiers';
 import type {
   DataColumn,
@@ -339,7 +340,8 @@ const historyTriggers = (table: DataTable): NamedStatement[] => {
 
 export const desiredTriggers = (table: DataTable): NamedStatement[] => [
   ...ftsTriggers(table),
-  ...historyTriggers(table)
+  ...historyTriggers(table),
+  ...changeCaptureTriggers(table)
 ];
 
 // Type changes

package/src/dataEngine.ts

@@ -3,6 +3,7 @@
 // the tests and the tool-design eval. The runner executes; everything about
 // which SQL is allowed and how results look is decided here.
 import { identifierIssue, quoteIdentifier as q } from './dataIdentifiers';
+import { collectTriggerEvents, renameColumnInTriggers, triggersUsingColumn } from './dataTriggers';
 import {
   DATA_NOW_SQL,
   NUMERIC_TYPES,
@@ -172,6 +173,60 @@ export const INTERNAL_MIGRATIONS: readonly (readonly string[])[] = [
       WHERE c.table_id = _ganju_tables.id AND c.type = 'text'
       ORDER BY c.position, c.id LIMIT 1
     ) WHERE display_column_id IS NULL AND created_at < '2026-10-24T00:00:00Z'`
+  ],
+  // Named queries: the owner's SELECTs, run by name. `tables` and `plan` are
+  // what the check found when each was saved.
+  [
+    `CREATE TABLE IF NOT EXISTS _ganju_queries (
+      name TEXT PRIMARY KEY,
+      description TEXT,
+      sql TEXT NOT NULL,
+      params TEXT NOT NULL DEFAULT '[]',
+      assistant INTEGER NOT NULL DEFAULT 0,
+      tables TEXT NOT NULL DEFAULT '[]',
+      plan TEXT NOT NULL DEFAULT '[]',
+      created_at TEXT NOT NULL DEFAULT (${DATA_NOW_SQL}),
+      updated_at TEXT NOT NULL DEFAULT (${DATA_NOW_SQL}),
+      updated_by TEXT
+    ) WITHOUT ROWID`
+  ],
+  // Triggers: the owner's rules, the rows a write changed while one listens
+  // (emptied before the write commits), and the events waiting for the queue.
+  [
+    `CREATE TABLE IF NOT EXISTS _ganju_triggers (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL UNIQUE,
+      description TEXT,
+      table_id INTEGER NOT NULL,
+      event TEXT NOT NULL,
+      condition TEXT,
+      action TEXT NOT NULL,
+      enabled INTEGER NOT NULL DEFAULT 1,
+      disabled_reason TEXT,
+      managed TEXT,
+      rate_limit INTEGER NOT NULL DEFAULT 60,
+      secret TEXT,
+      created_at TEXT NOT NULL DEFAULT (${DATA_NOW_SQL}),
+      updated_at TEXT NOT NULL DEFAULT (${DATA_NOW_SQL}),
+      updated_by TEXT
+    ) WITHOUT ROWID`,
+    'CREATE INDEX IF NOT EXISTS _ganju_triggers_table ON _ganju_triggers(table_id, event)',
+    `CREATE TABLE IF NOT EXISTS _ganju_changes (
+      id INTEGER PRIMARY KEY,
+      table_id INTEGER NOT NULL,
+      event TEXT NOT NULL,
+      row_id INTEGER NOT NULL,
+      actor TEXT,
+      old TEXT,
+      new TEXT
+    )`,
+    `CREATE TABLE IF NOT EXISTS _ganju_outbox (
+      seq INTEGER PRIMARY KEY,
+      id TEXT NOT NULL UNIQUE,
+      trigger_id TEXT NOT NULL,
+      message TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (${DATA_NOW_SQL})
+    )`
   ]
 ];
 
@@ -271,7 +326,8 @@ export const loadSchema = (runner: SqlRunner): DataSchema => {
             position: Number(c.position)
           };
         })
-    }))
+    })),
+    timeZone: getMeta(runner, 'time_zone')
   };
 };
 
@@ -1356,7 +1412,8 @@ const insertValues = (
 // A bot may only point a relation at a row it could read: none in a table
 // hidden from it, and only its own customer's in a scoped one. Otherwise it
 // could link an order to another customer and read their name back as the
-// label.
+// label. A caller held to some tables (a function's `data.tables`) may not
+// point outside them either.
 const assertRelationsVisible = (
   runner: SqlRunner,
   schema: DataSchema,
@@ -1364,7 +1421,7 @@ const assertRelationsVisible = (
   table: DataTable,
   values: Map<string, SqlValue>
 ) => {
-  if (!caller.restricted) return;
+  if (!caller.restricted && !caller.tables) return;
   for (const [name, value] of values) {
     if (value === null) continue;
     const column = table.columns.find(c => c.name === name);
@@ -1373,7 +1430,9 @@ const assertRelationsVisible = (
     if (!target) continue;
     if (!canRead(caller, target)) {
       throw new DataError(
-        `${table.name}.${name} points at a table the assistant can't use.`,
+        caller.restricted
+          ? `${table.name}.${name} points at a table the assistant can't use.`
+          : `${table.name}.${name} points at ${target.name}, which isn't one of this caller's tables.`,
         'forbidden'
       );
     }
@@ -1776,6 +1835,8 @@ export const write = (
   assertWritable(runner, caller, addsData);
   return runner.transaction(() => {
     setContextActor(runner, caller.actor);
+    // Rows left by a change that wasn't a write (a schema change) fire nothing.
+    runner.all('DELETE FROM _ganju_changes');
     const results: WriteResult[] = [];
     operations.forEach((op, index) => {
       try {
@@ -1792,6 +1853,7 @@ export const write = (
         throw error;
       }
     });
+    collectTriggerEvents(runner, schema, caller);
     return { ok: true as const, results };
   });
 };
@@ -2268,6 +2330,8 @@ export const dropTable = (
     dropTriggers(runner, table);
     runner.all(`DROP TABLE IF EXISTS ${q(ftsTableName(table))}`);
     runner.all(`DROP TABLE ${q(table.name)}`);
+    // Its triggers go with it; a later table of the same name starts with none.
+    runner.all('DELETE FROM _ganju_triggers WHERE table_id = ?', [table.id]);
     runner.all('UPDATE _ganju_tables SET display_column_id = NULL WHERE id = ?', [table.id]);
     runner.all('DELETE FROM _ganju_columns WHERE table_id = ?', [table.id]);
     runner.all('DELETE FROM _ganju_tables WHERE id = ?', [table.id]);
@@ -2642,6 +2706,20 @@ export const copyTableStep = (
   }
 };
 
+// Triggers name columns in their conditions and texts, checked only when
+// saved: a column one of them uses can't be dropped under it.
+const assertNoTriggerUses = (runner: SqlRunner, table: DataTable, column: string) => {
+  const triggers = triggersUsingColumn(runner, table.id, column);
+  if (triggers.length === 0) return;
+  throw new DataError(
+    triggers.length === 1
+      ? `${table.name}.${column} can't be dropped while the trigger ${triggers[0]} uses it; change or delete that trigger first.`
+      : `${table.name}.${column} can't be dropped while the triggers ${triggers.join(', ')} use it; change or delete those triggers first.`,
+    'constraint',
+    { triggers }
+  );
+};
+
 export const updateColumn = (
   runner: SqlRunner,
   schema: DataSchema,
@@ -2670,6 +2748,16 @@ export const updateColumn = (
   }
 
   if (columnChangeNeedsRebuild(schema, table.name, column.name, patch)) {
+    // A rename renames the column in its triggers too; a copy can't, so the
+    // two go one after the other.
+    const triggers = draft.name !== column.name ? triggersUsingColumn(runner, table.id, column.name) : [];
+    if (triggers.length) {
+      throw new DataError(
+        `${table.name}.${column.name} is used by triggers (${triggers.join(', ')}): rename it on its own, then make the other changes.`,
+        'constraint',
+        { triggers }
+      );
+    }
     return rebuildTable(
       runner,
       schema,
@@ -2687,6 +2775,7 @@ export const updateColumn = (
       runner.all(
         `ALTER TABLE ${q(table.name)} RENAME COLUMN ${q(column.name)} TO ${q(draft.name)}`
       );
+      renameColumnInTriggers(runner, table.id, column.name, draft.name);
     }
     updateColumnMeta(runner, schema, table, column.id, draft);
     touchTable(runner, table.id);
@@ -2709,6 +2798,7 @@ export const dropColumn = (
   if (table.columns.length === 1) {
     throw new DataError(`${table.name} needs at least one column; drop the table instead.`);
   }
+  assertNoTriggerUses(runner, table, column.name);
   if (dropColumnNeedsRebuild(schema, table.name, column.name)) {
     return rebuildTable(
       runner,

package/src/dataImport.ts

@@ -552,3 +552,6 @@ export const csvLine = (cells: ImportCell[]) =>
       return /[",\n\r]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
     })
     .join(',');
+
+export { detectSeparator, parseCsv } from './dataCsv';
+export type { ParsedCsv } from './dataCsv';