@ganju/utils 0.0.20 → 0.0.21

package/src/dataIndexAdvice.ts

@@ -0,0 +1,127 @@
+// Which columns of a database are worth an index, and which indexes nobody
+// uses, from the API's daily query stats and the database's schema. Pure, so
+// the daily job and the tests apply the same rule.
+import { constants } from './constants';
+import { isIndexedColumn } from './dataDdl';
+import type { DataSchema } from './dataTypes';
+
+// A column's (or, with column '', a table's) sums over a window.
+export interface IndexAdviceStat {
+  tableName: string;
+  columnName: string;
+  queries: number;
+  rowsRead: number;
+  rowsReturned: number;
+  rowsWritten: number;
+}
+
+export interface IndexAdviceCandidate {
+  tableName: string;
+  columnName: string;
+  kind: 'add' | 'unused';
+  queries: number;
+  avgRowsRead: number;
+  avgRowsReturned: number;
+  rowsWritten: number;
+}
+
+export interface IndexAdviceInput {
+  schema: DataSchema;
+  // Sums over the last 7 days, and over the last 30.
+  week: IndexAdviceStat[];
+  month: IndexAdviceStat[];
+  // Whether stats go back the whole 30 days, so "no query used it" means it.
+  monthCovered: boolean;
+  // "table.column" made filterable, or "table" created, in the last 30 days.
+  recentlyIndexed: Set<string>;
+}
+
+// Indexes the owner can add or remove: a column marked filterable. Unique and
+// relation columns are indexed for what they are, and stay.
+const canIndex = (type: string) => type !== 'json' && type !== 'long_text';
+
+export const adviseIndexes = (
+  input: IndexAdviceInput
+): IndexAdviceCandidate[] => {
+  const out: IndexAdviceCandidate[] = [];
+  const tables = new Map(input.schema.tables.map(t => [t.name, t]));
+
+  for (const stat of input.week) {
+    if (!stat.columnName) continue;
+    const table = tables.get(stat.tableName);
+    const column = table?.columns.find(c => c.name === stat.columnName);
+    if (!column || isIndexedColumn(column) || !canIndex(column.type)) continue;
+    if (stat.queries < constants.DATA_INDEX_ADVICE_MIN_QUERIES) continue;
+    const avgRead = stat.rowsRead / stat.queries;
+    const avgReturned = stat.rowsReturned / stat.queries;
+    if (avgRead < constants.DATA_INDEX_ADVICE_MIN_ROWS_READ) continue;
+    // Scanning, not just a small table: many rows read for each one returned.
+    if (
+      stat.rowsRead <
+      constants.DATA_INDEX_ADVICE_MIN_READ_RATIO * stat.rowsReturned
+    ) {
+      continue;
+    }
+    out.push({
+      tableName: stat.tableName,
+      columnName: stat.columnName,
+      kind: constants.DATA_INDEX_ADVICE_ADD,
+      queries: stat.queries,
+      avgRowsRead: Math.round(avgRead),
+      avgRowsReturned: Math.round(avgReturned),
+      rowsWritten: 0
+    });
+  }
+
+  if (input.monthCovered) {
+    const used = new Set(
+      input.month
+        .filter(s => s.columnName && s.queries > 0)
+        .map(s => `${s.tableName}.${s.columnName}`)
+    );
+    for (const table of input.schema.tables) {
+      const totals = input.month.find(
+        s => s.tableName === table.name && s.columnName === ''
+      );
+      const written = totals?.rowsWritten ?? 0;
+      if (written < constants.DATA_INDEX_UNUSED_MIN_ROWS_WRITTEN) continue;
+      if (written <= (totals?.queries ?? 0)) continue;
+      if (input.recentlyIndexed.has(table.name)) continue;
+      for (const column of table.columns) {
+        if (!column.filterable || column.unique) continue;
+        if (column.type === 'relation' || column.type === 'file') continue;
+        const key = `${table.name}.${column.name}`;
+        if (used.has(key) || input.recentlyIndexed.has(key)) continue;
+        out.push({
+          tableName: table.name,
+          columnName: column.name,
+          kind: constants.DATA_INDEX_ADVICE_UNUSED,
+          queries: 0,
+          avgRowsRead: 0,
+          avgRowsReturned: 0,
+          rowsWritten: written
+        });
+      }
+    }
+  }
+  return out;
+};
+
+// A dismissed suggestion comes back once its numbers have doubled.
+export const adviceDoubled = (
+  current: { queries: number; avgRowsRead: number; rowsWritten: number },
+  dismissed: {
+    queries: number | null;
+    avgRowsRead: number | null;
+    rowsWritten: number | null;
+  }
+): boolean =>
+  (dismissed.queries !== null &&
+    dismissed.queries > 0 &&
+    current.queries >= 2 * dismissed.queries) ||
+  (dismissed.avgRowsRead !== null &&
+    dismissed.avgRowsRead > 0 &&
+    current.avgRowsRead >= 2 * dismissed.avgRowsRead) ||
+  (dismissed.rowsWritten !== null &&
+    dismissed.rowsWritten > 0 &&
+    current.rowsWritten >= 2 * dismissed.rowsWritten);

package/src/dataRpc.ts

@@ -4,6 +4,9 @@
 import type {
   DataCaller,
   DataDeleteImpact,
+  DataFileLinkChange,
+  DataFileLinks,
+  DataFileLinksReplaced,
   DataResult,
   DataSchema,
   DataTable,
@@ -56,7 +59,8 @@ export interface DatabaseInfo {
   timeZone: string | null;
   schemaVersion: number;
   size: number;
-  tables: { name: string; label: string | null; columns: number }[];
+  // `rows` is about how many: the highest id, read from the index.
+  tables: { name: string; label: string | null; columns: number; rows: number }[];
   // A column change copying a large table in the background: table changes,
   // and writes that would change its rows, wait while it runs.
   copy: DataTableCopy | null;
@@ -106,6 +110,12 @@ export interface ProjectDatabaseRpc {
   dismissCopy(caller: DataCaller): R<{ copy: null }>;
   describe(caller: DataCaller, args?: unknown): R<unknown>;
   query(caller: DataCaller, args: unknown): R<unknown>;
+  // A row as a trigger event carries it (`id`, or the newest): for a test
+  // send and for a run whose event was too large to carry its row.
+  eventRow(
+    caller: DataCaller,
+    args: { table: string; id?: number }
+  ): R<Record<string, unknown> | null>;
   write(
     caller: DataCaller,
     args: unknown
@@ -114,6 +124,12 @@ export interface ProjectDatabaseRpc {
     caller: DataCaller,
     args: { table: string; ids?: number[] }
   ): R<DataDeleteImpact>;
+  // The rows that link knowledge items, and moving or clearing those links.
+  fileLinks(caller: DataCaller, args: { uris: string[] }): R<DataFileLinks>;
+  replaceFileLinks(
+    caller: DataCaller,
+    args: { changes: DataFileLinkChange[] }
+  ): R<DataFileLinksReplaced>;
   history(
     caller: DataCaller,
     args: { table: string; id: number; limit?: number; cursor?: number }

package/src/dataTools.ts

@@ -61,7 +61,7 @@ const CHANGES = {
 };
 
 const WHERE_HELP =
-  'Filter object. { "column": value } matches exactly; { "column": { "op": value } } with op one of eq, ne, gt, gte, lt, lte, in, notIn (lists), contains, startsWith (text, case-insensitive), isNull (true/false). Several keys must all match; { "or": [ {...}, {...} ] } matches any. A relation column takes the related row\'s id, or filter on a column of the related table with "relation.column", e.g. { "product.name": "Margherita" }. Datetimes are ISO 8601; include the offset for local times, e.g. "2026-10-19T00:00:00-05:00".';
+  'Filter object. { "column": value } matches exactly; { "column": { "op": value } } with op one of eq, ne, gt, gte, lt, lte, in, notIn (lists), contains, startsWith (text, case-insensitive), isNull (true/false). Several keys must all match; { "or": [ {...}, {...} ] } matches any. A relation column takes the related row\'s id, or filter on a column of the related table with "relation.column", e.g. { "product.name": "Margherita" }. A file column matches the item\'s uri. Datetimes are ISO 8601; include the offset for local times, e.g. "2026-10-19T00:00:00-05:00".';
 
 const accessOf = (caller: DataCaller, table: DataTable) =>
   caller.restricted ? table.access : 'full';
@@ -145,7 +145,7 @@ export const dataToolDefinitions = (
       title: DATA_TOOL_TITLES[DATA_TOOL_QUERY],
       description: [
         "Read rows from the project's database: structured records such as products, prices, stock, orders, bookings or customers. Use it for anything with fields and numbers; use the knowledge/resource tools for documents and pages.",
-        'Returns matching rows (relation columns come back as { id, label }), the total that match, and nextCursor when there are more. With "aggregate" it returns counts, sums, averages, minimums or maximums instead of rows, optionally per group: use that for "how many" and "how much" rather than adding rows up yourself.',
+        'Returns matching rows (relation columns come back as { id, label }; file columns as { uri, title, mimeType }, or { uri, missing: true } when the item is gone: deliver one with send-resource and its uri, or read a document with read-resource), the total that match, and nextCursor when there are more. With "aggregate" it returns counts, sums, averages, minimums or maximums instead of rows, optionally per group: use that for "how many" and "how much" rather than adding rows up yourself.',
         "The database holds only what these tables and columns hold. When a question needs something they don't have (opening hours, parking, calories, reviews, forecasts), look in the knowledge tools if you have them; if nothing has it, say you don't have that information. Never guess it.",
         `Every table also has id, created_at and updated_at. Datetimes come back in the project's time zone (${timeZone}) with their offset; read them as local times.`,
         'Tables:',
@@ -242,7 +242,7 @@ export const dataToolDefinitions = (
       title: DATA_TOOL_TITLES[DATA_TOOL_WRITE],
       description: [
         "Add, change or delete rows in the project's database. All operations in one call succeed together or none is applied, so put everything that belongs together (an order, its lines and the stock they use) in one call.",
-        '- insert: { "op": "insert", "table": "...", "values": { column: value } }. A relation column takes the related row\'s id; to point at a row inserted earlier in the same call use { "$ref": n }, n being that operation\'s position (0-based).',
+        '- insert: { "op": "insert", "table": "...", "values": { column: value } }. A relation column takes the related row\'s id; to point at a row inserted earlier in the same call use { "$ref": n }, n being that operation\'s position (0-based). A file column takes the uri of an item in the project\'s knowledge (from list-resources or search-resources), or null.',
         '- update: { "op": "update", "table": "...", "id": 12, "set": { column: value } }. For numbers, { "decrement": 2 } or { "increment": 2 } changes the value relative to what is stored. Instead of id you can give "where" (same format as data-query).',
         '- delete: { "op": "delete", "table": "...", "id": 12 } (or "where").',
         'Guards: an update or delete also takes "where" conditions that must hold, e.g. "where": { "stock": { "gte": 2 } }, and "expect", how many rows must change (1 by default when id is given). If a guard fails, nothing in the call is written and the error says why (e.g. how much stock is left).',

package/src/dataTriggers.ts

@@ -146,6 +146,9 @@ export interface DataTriggerEventMessage {
   depth: number;
   at: string;
   truncated?: true;
+  // The row's customer on a customer-scoped table, kept when the row is
+  // left out for its size.
+  participantId?: string;
   // Not run: the chain went too deep. Recorded as a failed run.
   error?: string;
 }
@@ -321,6 +324,29 @@ export const renderTriggerText = (
     return typeof value === 'object' ? JSON.stringify(value) : String(value);
   });
 
+export interface DataTriggerCustomerMessage {
+  text: string;
+  template: { name: string; language: string; params: string[] } | null;
+}
+
+// What a "customer" action sends for a row: its text, and the template with
+// each value filled in. A test send builds it the same way as a real run.
+export const renderCustomerMessage = (
+  action: { text: string; template?: DataTriggerTemplate },
+  row: Record<string, unknown> | null
+): DataTriggerCustomerMessage => ({
+  text: renderTriggerText(action.text, row),
+  template: action.template
+    ? {
+        name: action.template.name,
+        language: action.template.language,
+        params: (action.template.params ?? []).map(p =>
+          renderTriggerText(p, row)
+        )
+      }
+    : null
+});
+
 const templateFields = (text: string) =>
   [...text.matchAll(/\{\{\s*([a-z][a-z0-9_]*)\s*\}\}/g)].map(m => m[1]);
 
@@ -465,6 +491,23 @@ const normaliseAction = (
   }
 };
 
+// A "customer" action as the dialog has it, saved or not, checked against
+// its table the way saving it would be.
+export const normaliseCustomerAction = (
+  schema: DataSchema,
+  tableName: string,
+  value: unknown
+): Extract<DataTriggerAction, { type: 'customer' }> => {
+  const table = schema.tables.find(t => t.name === tableName);
+  if (!table) {
+    throw new DataError(`There is no table named ${tableName}.`, 'not_found');
+  }
+  return normaliseAction(table, { customer: value }) as Extract<
+    DataTriggerAction,
+    { type: 'customer' }
+  >;
+};
+
 const defaultName = (table: string, on: string, action: DataTriggerAction) => {
   const target =
     action.type === 'function'
@@ -898,6 +941,29 @@ const shape = (
   return out;
 };
 
+/**
+ * A row as a trigger event carries it, read from the table: `id`, or the
+ * newest row. Null when there is none. A test send and a run whose event
+ * was too large to carry its row build their message from it, so it reads
+ * as it does for the event, system fields and the customer included.
+ */
+export const readEventRow = (
+  runner: SqlRunner,
+  schema: DataSchema,
+  tableName: string,
+  id?: number
+): Record<string, unknown> | null => {
+  const table = schema.tables.find(t => t.name === tableName);
+  if (!table) {
+    throw new DataError(`There is no table named ${tableName}.`, 'not_found');
+  }
+  const [stored] =
+    id === undefined
+      ? runner.all(`SELECT * FROM "${table.name}" ORDER BY id DESC LIMIT 1`)
+      : runner.all(`SELECT * FROM "${table.name}" WHERE id = ?`, [id]);
+  return stored ? shape(table, JSON.stringify(stored)) : null;
+};
+
 const DEPTH_PATTERN = /^trigger:([^\s]+)$/;
 
 /**
@@ -933,6 +999,7 @@ export const collectTriggerEvents = (
     if (listening.length === 0) continue;
     const row = shape(table, change.new);
     const previous = shape(table, change.old);
+    const customer = row?.participant_id ?? previous?.participant_id;
     for (const trigger of listening) {
       if (trigger.id === ownTrigger) continue;
       if (!conditionMatches(trigger.when, row, previous)) continue;
@@ -948,7 +1015,10 @@ export const collectTriggerEvents = (
         previous,
         actor: (change.actor as string | null) ?? null,
         depth,
-        at: new Date().toISOString()
+        at: new Date().toISOString(),
+        ...(typeof customer === 'string' && customer
+          ? { participantId: customer }
+          : {})
       };
       if (depth > DATA_TRIGGER_MAX_DEPTH) {
         message.row = null;

package/src/dataTypes.ts

@@ -138,11 +138,33 @@ export interface DataCallerLimits {
   readOnly?: boolean;
 }
 
+// What one query on a table did: the columns it filtered and sorted on, and
+// how many rows it read to return how many. The API sums them per column for
+// a week to suggest indexes.
+export interface DataQueryShape {
+  table: string;
+  filtered: string[];
+  sorted: string[];
+  rowsRead: number;
+  returned: number;
+}
+
+// Rows one write operation wrote to a table, which tells a write-heavy table.
+export interface DataWriteShape {
+  table: string;
+  rowsWritten: number;
+}
+
 export interface DataUsage {
   rowsRead: number;
   rowsWritten: number;
+  queries?: DataQueryShape[];
+  writes?: DataWriteShape[];
 }
 
+// At most this many shapes travel back with one call.
+export const DATA_MAX_USAGE_SHAPES = 20;
+
 export const DATA_ERROR_CODES = [
   'invalid',
   'not_found',
@@ -278,6 +300,46 @@ export interface DataDeleteImpact {
   truncated: boolean;
 }
 
+// A file column links a knowledge item by its uri. Reads return it as
+// { uri }, which the workers fill with the item's title and type.
+export const DATA_FILE_URI_MAX = 2048;
+export const DATA_FILE_LINKS_MAX_URIS = 500;
+
+export interface DataFileValue {
+  uri: string;
+  // The item's id and size: only in the dashboard's reads, for previews.
+  id?: string;
+  size?: number;
+  title?: string;
+  mimeType?: string;
+  // No knowledge item has this uri any more.
+  missing?: true;
+}
+
+// The rows whose file columns point at some uris, per column.
+export interface DataFileLinks {
+  links: {
+    table: string;
+    tableLabel: string | null;
+    column: string;
+    columnLabel: string | null;
+    required: boolean;
+    rows: number;
+  }[];
+}
+
+export interface DataFileLinkChange {
+  from: string;
+  // null clears the link.
+  to: string | null;
+}
+
+export interface DataFileLinksReplaced {
+  updated: number;
+  // Required columns can't be emptied: their links stay, and show as missing.
+  kept: { table: string; column: string; rows: number }[];
+}
+
 // A table copy running in the background, as callers see it.
 export interface DataTableCopy {
   table: string;

package/src/index.ts

@@ -129,6 +129,8 @@ import { oauthProviders } from './oauthProviders';
 import type { OAuthProviderConfig } from './oauthProviders';
 import { resolveAttachment } from './attachment';
 import { isExposedResource } from './exposedResource';
+import { dataAttachmentOf, skipsIndexing } from './dataAttachment';
+import type { DataAttachment } from './dataAttachment';
 import type { ExposableResource } from './exposedResource';
 import {
   isSyncableResource,
@@ -391,6 +393,10 @@ import {
   cleanWhatsappTemplateParam,
   whatsappSendError
 } from './whatsappTemplates';
+import {
+  whatsappMessageChange,
+  whatsappAccountChanges
+} from './whatsappWebhook';
 import type {
   WhatsappTemplateCategory,
   WhatsappTemplateDraft,
@@ -428,6 +434,8 @@ export const utils = {
   whatsappTemplateSendable,
   cleanWhatsappTemplateParam,
   whatsappSendError,
+  whatsappMessageChange,
+  whatsappAccountChanges,
   getEnv,
   fetcher,
   constants,
@@ -485,6 +493,8 @@ export const utils = {
   oauthProviders,
   resolveAttachment,
   isExposedResource,
+  dataAttachmentOf,
+  skipsIndexing,
   isSyncableResource,
   isResourceSyncInProgress,
   resourceSyncProvider,
@@ -730,6 +740,7 @@ export type {
   AttachmentResource,
   ResolvedAttachment,
   ResolveAttachmentResult,
+  DataAttachment,
   ExposableResource,
   SyncableResource,
   ResourceSyncProvider,

package/src/localizeDataError.ts

@@ -39,6 +39,21 @@ const guardSuffix = (suffix: string): string => {
   return suffix;
 };
 
+// Meta's other template statuses, as the refusal writes them.
+const TEMPLATE_STATUS_ES: Record<string, string> = {
+  paused: 'pausada',
+  disabled: 'desactivada',
+  flagged: 'marcada',
+  'in appeal': 'en apelación',
+  'pending deletion': 'pendiente de eliminación',
+  deleted: 'eliminada',
+  'limit exceeded': 'por encima del límite'
+};
+
+// "The WhatsApp template x (es)", as a channel's refusal names it.
+const templateLabel = (label: string): string =>
+  label.replace(/^The WhatsApp template /, 'La plantilla de WhatsApp ');
+
 export const DATA_ERROR_MESSAGES_ES: Record<string, string | Render> = {
   'Unknown column "{0}" in {1}. Columns: {2}.':
     'Columna desconocida "{0}" en {1}. Columnas: {2}.',
@@ -124,8 +139,22 @@ export const DATA_ERROR_MESSAGES_ES: Record<string, string | Render> = {
   '{0}: "min" is a number.': '{0}: "min" es un número.',
   "{0}: a {1} column can't be unique.":
     '{0}: una columna {1} no puede ser única.',
-  '{0}: only text columns can be searchable (text, long_text, email, url, phone, enum).':
-    '{0}: solo las columnas de texto pueden ser buscables (text, long_text, email, url, phone, enum).',
+  '{0}: only text and file columns can be searchable (text, long_text, email, url, phone, enum, file).':
+    '{0}: solo las columnas de texto y de archivo pueden ser buscables (text, long_text, email, url, phone, enum, file).',
+  "{0} takes a knowledge item's uri, e.g. resource://menu-photo.":
+    '{0} lleva el uri de un elemento del conocimiento, p. ej. resource://menu-photo.',
+  '{0}: a uri is at most {1} characters.':
+    '{0}: un uri tiene como máximo {1} caracteres.',
+  '"uris" lists 1 to {0} knowledge item uris.':
+    '"uris" lista de 1 a {0} uris de elementos del conocimiento.',
+  'No resource in this project has the uri {0}; link an existing resource by its uri.':
+    'Ningún recurso de este proyecto tiene el uri {0}; enlaza un recurso que exista por su uri.',
+  'File links are for the owner.':
+    'Los enlaces a archivos son para el dueño.',
+  '"changes" lists 1 to {0} { from, to } pairs.':
+    '"changes" lista de 1 a {0} pares { from, to }.',
+  'Each change is { from, to }; to is null to clear.':
+    'Cada cambio es { from, to }; to es null para quitar el enlace.',
   '{0}: a column named "rank" can\'t be searchable; rename it (e.g. "ranking").':
     '{0}: una columna llamada "rank" no puede ser buscable; cámbiale el nombre (p. ej. "ranking").',
   "{0}: a {1} column can't be filterable; mark it searchable instead.":
@@ -469,6 +498,9 @@ export const DATA_ERROR_MESSAGES_ES: Record<string, string | Render> = {
   'Type the table\'s name, "{0}", to drop it.':
     'Escribe el nombre de la tabla, "{0}", para eliminarla.',
   'There is no such run.': 'No existe esa ejecución.',
+  'There is no such index suggestion.': 'No existe esa sugerencia de índice.',
+  'An unused index is only flagged; remove it from the column if you want to, or dismiss the suggestion.':
+    'Un índice sin uso solo se señala; quítalo de la columna si quieres, o descarta la sugerencia.',
   'Only a failed or skipped run can be tried again.':
     'Solo se puede reintentar una ejecución fallida u omitida.',
   'This run kept no event to send again.':
@@ -516,7 +548,73 @@ export const DATA_ERROR_MESSAGES_ES: Record<string, string | Render> = {
   '"{0}" is reserved by SQLite; pick another column name (e.g. "{1}_ref").':
     '"{0}" está reservado por SQLite; elige otro nombre de columna (p. ej. "{1}_ref").',
   '"{0}" is a column every table already has.':
-    '"{0}" es una columna que ya tienen todas las tablas.'
+    '"{0}" es una columna que ya tienen todas las tablas.',
+  // A test send of a trigger's customer message.
+  "You haven't linked a chat with this project's bots: write to the bot from your own phone and send /link.":
+    'No has vinculado un chat con los bots de este proyecto: escríbele al bot desde tu propio teléfono y envía /link.',
+  "{0} isn't one of your linked chats with this project's bots.":
+    '{0} no es uno de tus chats vinculados con los bots de este proyecto.',
+  'Several of your chats are linked to this project\'s bots; pick one with "participantId".':
+    'Varios de tus chats están vinculados con los bots de este proyecto; elige uno con "participantId".',
+  '{0} has no rows yet; add one to build the test from.':
+    '{0} aún no tiene filas; agrega una para armar la prueba.',
+  'Reading a row as its trigger event is for the project owner.':
+    'Leer una fila como su evento de disparador es solo para el dueño del proyecto.',
+  // The channel's refusals, which a test send answers with.
+  "This channel's credentials can't be read; connect it again.":
+    'No se pueden leer las credenciales de este canal; conéctalo de nuevo.',
+  'A message needs "text".': 'Un mensaje necesita "text".',
+  'A message is at most {0} characters.':
+    'Un mensaje tiene como máximo {0} caracteres.',
+  '{0} refused the message: {1}': '{0} rechazó el mensaje: {1}',
+  '{0} refused the message.': '{0} rechazó el mensaje.',
+  "Ganju can't send messages on {0} channels.":
+    'Ganju no puede enviar mensajes en canales de {0}.',
+  'WhatsApp: {0}': 'WhatsApp: {0}',
+  'The {0} channel is paused.': 'El canal de {0} está en pausa.',
+  "{0} isn't on this channel's WhatsApp Business account. Create it in the channel's Message templates, or check its name and language.":
+    a =>
+      `${templateLabel(a[0])} no está en la cuenta de WhatsApp Business de este canal. Créala en Plantillas de mensajes del canal, o revisa su nombre e idioma.`,
+  '{0} {1}; only approved templates can be sent.': a => {
+    const whole = `${a[0]} ${a[1]}`;
+    const m =
+      /^(The WhatsApp template [\s\S]+? \([^)]*\)) (is still in Meta's review|was rejected by Meta|is ([\s\S]+?) by Meta)( \([\s\S]*\))?$/.exec(
+        whole
+      );
+    if (!m) return `${whole}; solo se pueden enviar plantillas aprobadas.`;
+    const why = m[2].startsWith('is still')
+      ? 'sigue en revisión de Meta'
+      : m[2].startsWith('was rejected')
+        ? 'fue rechazada por Meta'
+        : `está ${TEMPLATE_STATUS_ES[m[3]] ?? `en el estado ${m[3]}`} por Meta`;
+    return `${templateLabel(m[1])} ${why}${m[4] ?? ''}; solo se pueden enviar plantillas aprobadas.`;
+  },
+  "{0} has a media header, a header variable or a button that takes a value; Ganju only fills the message's variables. Make a version without them.":
+    a =>
+      `${templateLabel(a[0])} tiene un encabezado con archivo, una variable en el encabezado o un botón que recibe un valor; Ganju solo llena las variables del mensaje. Haz una versión sin ellos.`,
+  "There is no customer {0} on this project's channels.":
+    'No hay ningún cliente {0} en los canales de este proyecto.',
+  'A message needs "text", a "template", or both.':
+    'Un mensaje necesita "text", una "template", o ambos.',
+  'This customer has never written to the bot privately, so there is no chat to message them in.':
+    'Este cliente nunca le ha escrito al bot en privado, así que no hay un chat donde escribirle.',
+  "This customer already got the channel's {0} messages for the last 24 hours.":
+    'Este cliente ya recibió los {0} mensajes del canal de las últimas 24 horas.',
+  "Outside WhatsApp's 24-hour window (this customer last wrote more than 24 hours ago); use an approved template.":
+    'Fuera de la ventana de 24 horas de WhatsApp (este cliente escribió por última vez hace más de 24 horas); usa una plantilla aprobada.',
+  'Templates are for WhatsApp; {0} takes "text".':
+    'Las plantillas son para WhatsApp; {0} recibe "text".',
+  'The WhatsApp template {0} has {1} variable; {2} value was given.':
+    'La plantilla de WhatsApp {0} tiene {1} variable; se dio {2} valor.',
+  'The WhatsApp template {0} has {1} variable; {2} values were given.':
+    'La plantilla de WhatsApp {0} tiene {1} variable; se dieron {2} valores.',
+  'The WhatsApp template {0} has {1} variables; {2} value was given.':
+    'La plantilla de WhatsApp {0} tiene {1} variables; se dio {2} valor.',
+  'The WhatsApp template {0} has {1} variables; {2} values were given.':
+    'La plantilla de WhatsApp {0} tiene {1} variables; se dieron {2} valores.',
+  'A post needs "chatId".': 'Una publicación necesita "chatId".',
+  'WhatsApp has no group chats for bots; message a customer with send().':
+    'WhatsApp no tiene chats de grupo para bots; escríbele a un cliente con send().'
 };
 
 interface Compiled {

package/src/schema.ts

@@ -418,6 +418,14 @@ const ARTIFACT_SYNC_ONE_DRIVE = z.object({
   organizationId: z.uuid()
 });
 
+// A knowledge item uploaded from a Data row: which file column it was for,
+// and whether it is indexed for search too (the column's searchable switch).
+const DATA_ATTACHMENT_METADATA = z.object({
+  table: z.string().min(1).max(64),
+  column: z.string().min(1).max(64),
+  index: z.boolean()
+});
+
 const ARTIFACT_CREATE_RESOURCE = z.object({
   title: z.string().min(3).max(200),
   uri: z.string(),
@@ -529,6 +537,15 @@ const ARTIFACT_GET_RESOURCE_BY_ID = z.object({
   organizationId: z.uuid()
 });
 
+// The knowledge items a Data file column can link, newest first.
+const ARTIFACT_PICK_RESOURCE = z.object({
+  projectId: z.uuid(),
+  userId: z.uuid(),
+  organizationId: z.uuid(),
+  q: z.string().trim().max(200).optional(),
+  limit: z.coerce.number().int().min(1).max(50).default(20)
+});
+
 const ARTIFACT_REMOVE_RESOURCE = z.object({
   resourceId: z.uuid(),
   projectId: z.uuid(),
@@ -834,6 +851,17 @@ const DATA_TRIGGER_PATCH = z.strictObject({ enabled: z.boolean() });
 const DATA_TRIGGER_DEPLOY_BODY = z.strictObject({
   triggers: z.array(DATA_TRIGGER_INPUT).max(50)
 });
+// A test of a "customer" action as the dialog has it, sent to the signed-in
+// owner's own chat with the bot, built from one row (the newest by default).
+const DATA_TRIGGER_TEST_SEND_BODY = z.strictObject({
+  table: DATA_IDENTIFIER,
+  customer: DATA_TRIGGER_INPUT.shape.customer.unwrap(),
+  rowId: z.number().int().min(1).optional(),
+  // Which of the owner's linked chats, when there is more than one.
+  participantId: z.string().min(1).max(64).optional(),
+  // Send the template even inside WhatsApp's 24-hour window.
+  asTemplate: z.boolean().optional()
+});
 const DATA_TRIGGER_RUN_LIST_QUERY = z.object({
   limit: z.coerce.number().int().min(1).max(50).optional()
 });
@@ -848,6 +876,8 @@ const DATA_TRIGGER_PATH_PARAMS = DATA_DATABASE_GET.extend({ name: DATA_TRIGGER_N
 const DATA_TRIGGER_RUN_PARAMS = DATA_TRIGGER_PATH_PARAMS.extend({
   runId: z.string().min(1).max(64)
 });
+// An index suggestion, by its id.
+const DATA_INDEX_ADVICE_PARAMS = DATA_DATABASE_GET.extend({ adviceId: z.uuid() });
 
 const ARTIFACT_UPLOAD_RESOURCE_FILE = z.object({
   resourceId: z.uuid(),
@@ -2150,6 +2180,8 @@ export const Schema = {
   ARTIFACT_GET_PROMPT,
   ARTIFACT_REMOVE_PROMPT,
   ARTIFACT_CREATE_RESOURCE,
+  DATA_ATTACHMENT_METADATA,
+  ARTIFACT_PICK_RESOURCE,
   ARTIFACT_CREATE_RESOURCE_VIEW,
   ARTIFACT_CREATE_WEBSITE,
   ARTIFACT_CREATE_WEBSITE_VIEW,
@@ -2196,9 +2228,11 @@ export const Schema = {
   DATA_TRIGGER_INPUT,
   DATA_TRIGGER_PATCH,
   DATA_TRIGGER_DEPLOY_BODY,
+  DATA_TRIGGER_TEST_SEND_BODY,
   DATA_TRIGGER_RUN_LIST_QUERY,
   DATA_TRIGGER_PATH_PARAMS,
   DATA_TRIGGER_RUN_PARAMS,
+  DATA_INDEX_ADVICE_PARAMS,
   DATA_COLUMN_PARAMS,
   DATA_ROW_PARAMS,
   ARTIFACT_REMOVE_RESOURCE,