@ganju/utils 0.0.17 → 0.0.20

package/src/dataApi.ts

@@ -16,7 +16,13 @@ export interface DataApiRoute {
   path: string;
   summary: string;
   description?: string;
-  tag: 'Database' | 'Tables' | 'Rows' | 'Queries' | '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.
@@ -49,7 +55,11 @@ const {
   DATA_EXPORT_FILE_QUERY,
   DATA_CHANGE_LIST_QUERY,
   DATA_QUERY_INPUT,
-  DATA_QUERY_RUN_BODY
+  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 = {
@@ -303,6 +313,71 @@ export const DATA_API_ROUTES = {
     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. 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
+  },
+  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, and email addresses still to confirm as `confirming`.",
+    body: DATA_TRIGGER_DEPLOY_BODY,
+    returns: '{ triggers, removed, secrets, confirming? }'
+  },
+  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',
@@ -448,6 +523,7 @@ export const dataOpenApi = (serverUrl: string) => {
       { name: 'Tables' },
       { name: 'Rows' },
       { name: 'Queries' },
+      { name: 'Triggers' },
       { name: 'History and export' }
     ],
     paths,

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,
@@ -188,6 +189,44 @@ export const INTERNAL_MIGRATIONS: readonly (readonly string[])[] = [
       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})
+    )`
   ]
 ];
 
@@ -1796,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 {
@@ -1812,6 +1853,7 @@ export const write = (
         throw error;
       }
     });
+    collectTriggerEvents(runner, schema, caller);
     return { ok: true as const, results };
   });
 };
@@ -2288,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]);
@@ -2662,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,
@@ -2690,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,
@@ -2707,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);
@@ -2729,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/dataRpc.ts

@@ -10,6 +10,7 @@ import type {
   DataTableCopy
 } from './dataTypes';
 import type { DataQuery } from './dataQueries';
+import type { DataTrigger, DataTriggerWithSecret, SavedTrigger } from './dataTriggers';
 
 export type ExportFormat = 'jsonl' | 'csv';
 
@@ -124,6 +125,20 @@ export interface ProjectDatabaseRpc {
     caller: DataCaller,
     args: { name: string; params?: Record<string, unknown>; limit?: number }
   ): R<{ query: string; rows: Record<string, unknown>[]; truncated?: string }>;
+  // Triggers. `pending` counts events waiting for the queue.
+  listTriggers(caller: DataCaller): R<{ triggers: DataTrigger[]; pending: number }>;
+  getTrigger(nameOrId: string): R<DataTriggerWithSecret>;
+  saveTrigger(caller: DataCaller, input: unknown): R<SavedTrigger>;
+  dropTrigger(caller: DataCaller, name: string): R<{ dropped: string }>;
+  setTriggerEnabled(
+    caller: DataCaller,
+    args: { name: string; enabled: boolean; reason?: string | null }
+  ): R<DataTrigger>;
+  replaceManagedTriggers(
+    caller: DataCaller,
+    inputs: unknown
+  ): R<{ triggers: DataTrigger[]; removed: string[]; secrets: Record<string, string> }>;
+  clearOutbox(args: { before: number }): R<{ cleared: number }>;
   exportStart(
     caller: DataCaller,
     args?: { format?: ExportFormat }