@mindstudio-ai/agent 0.1.103 → 0.1.105

package/dist/index.js

@@ -462,6 +462,59 @@ function buildSelect(table, options = {}) {
   if (options.offset != null) sql += ` OFFSET ${options.offset}`;
   return { sql, params: params.length > 0 ? params : void 0 };
 }
+var SQL_IDENTIFIER_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+function assertSqlIdentifier(name, context) {
+  if (!SQL_IDENTIFIER_RE.test(name)) {
+    throw new MindStudioError(
+      `Invalid ${context}: "${name}" \u2014 must be a plain identifier (letters, digits, _ and $, not starting with a digit).`,
+      "invalid_identifier",
+      400
+    );
+  }
+}
+function aggregateExpr(fn, column) {
+  switch (fn) {
+    case "count":
+      return "COUNT(*)";
+    case "sum":
+      return `TOTAL(${column})`;
+    case "avg":
+      return `AVG(${column})`;
+    case "min":
+      return `MIN(${column})`;
+    case "max":
+      return `MAX(${column})`;
+    case "countDistinct":
+      return `COUNT(DISTINCT ${column})`;
+  }
+}
+function buildScalarAggregate(table, fn, column, where, whereParams) {
+  if (column != null) assertSqlIdentifier(column, "aggregate column");
+  let sql = `SELECT ${aggregateExpr(fn, column ?? void 0)} AS value FROM ${table}`;
+  if (where) sql += ` WHERE ${where}`;
+  return { sql, params: whereParams?.length ? whereParams : void 0 };
+}
+function buildGroupedAggregate(table, options) {
+  for (const col of options.by) assertSqlIdentifier(col, "group-by column");
+  for (const term of options.select) {
+    assertSqlIdentifier(term.alias, "aggregate alias");
+    if (term.column != null) assertSqlIdentifier(term.column, "aggregate column");
+  }
+  if (options.orderBy != null) assertSqlIdentifier(options.orderBy, "aggregate order key");
+  const selectList = [
+    ...options.by,
+    ...options.select.map((t) => `${aggregateExpr(t.fn, t.column)} AS ${t.alias}`)
+  ].join(", ");
+  let sql = `SELECT ${selectList} FROM ${table}`;
+  if (options.where) sql += ` WHERE ${options.where}`;
+  if (options.by.length > 0) sql += ` GROUP BY ${options.by.join(", ")}`;
+  if (options.orderBy) sql += ` ORDER BY ${options.orderBy}${options.desc ? " DESC" : " ASC"}`;
+  if (options.limit != null) sql += ` LIMIT ${options.limit}`;
+  return {
+    sql,
+    params: options.whereParams?.length ? options.whereParams : void 0
+  };
+}
 function buildExists(table, where, whereParams, negate) {
   const inner = where ? `SELECT 1 FROM ${table} WHERE ${where}` : `SELECT 1 FROM ${table}`;
   const fn = negate ? "NOT EXISTS" : "EXISTS";
@@ -1119,6 +1172,187 @@ function isComparisonOp(value) {
   return value in JS_TO_SQL_OP;
 }
 
+// src/db/aggregate.ts
+var IDENTIFIER_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+var AGGREGATE_FNS = [
+  "count",
+  "sum",
+  "avg",
+  "min",
+  "max",
+  "countDistinct"
+];
+function normalizeAggregateSpec(spec) {
+  const by = [...spec.by ?? []];
+  for (const col of by) {
+    if (typeof col !== "string" || !IDENTIFIER_RE.test(col)) {
+      throw new MindStudioError(
+        `aggregate(): invalid group-by column "${col}" \u2014 column names are plain identifiers.`,
+        "invalid_column",
+        400
+      );
+    }
+  }
+  const aliases = Object.keys(spec.select ?? {});
+  if (aliases.length === 0) {
+    throw new MindStudioError(
+      "aggregate(): select must contain at least one aggregate, e.g. { n: { count: true } }.",
+      "invalid_aggregate_spec",
+      400
+    );
+  }
+  const select = aliases.map((alias) => {
+    if (!IDENTIFIER_RE.test(alias)) {
+      throw new MindStudioError(
+        `aggregate(): invalid alias "${alias}" \u2014 result property names are plain identifiers.`,
+        "invalid_aggregate_alias",
+        400
+      );
+    }
+    if (by.includes(alias)) {
+      throw new MindStudioError(
+        `aggregate(): alias "${alias}" collides with a group-by column of the same name.`,
+        "invalid_aggregate_alias",
+        400
+      );
+    }
+    const term = spec.select[alias];
+    const fns = AGGREGATE_FNS.filter((fn2) => term && fn2 in term);
+    if (fns.length !== 1) {
+      throw new MindStudioError(
+        `aggregate(): term "${alias}" must have exactly one aggregate key (count, sum, avg, min, max, countDistinct).`,
+        "invalid_aggregate_spec",
+        400
+      );
+    }
+    const fn = fns[0];
+    if (fn === "count") {
+      if (term[fn] !== true) {
+        throw new MindStudioError(
+          `aggregate(): term "${alias}" \u2014 count takes \`true\`, e.g. { count: true }.`,
+          "invalid_aggregate_spec",
+          400
+        );
+      }
+      return { alias, fn };
+    }
+    const column = term[fn];
+    if (typeof column !== "string" || !IDENTIFIER_RE.test(column)) {
+      throw new MindStudioError(
+        `aggregate(): term "${alias}" \u2014 invalid column "${String(column)}".`,
+        "invalid_column",
+        400
+      );
+    }
+    return { alias, fn, column };
+  });
+  if (spec.orderBy != null) {
+    if (!aliases.includes(spec.orderBy) && !by.includes(spec.orderBy)) {
+      throw new MindStudioError(
+        `aggregate(): orderBy "${spec.orderBy}" is neither a select alias nor a group-by column.`,
+        "invalid_aggregate_order",
+        400
+      );
+    }
+  }
+  return {
+    by,
+    select,
+    orderBy: spec.orderBy,
+    desc: spec.desc,
+    limit: spec.limit
+  };
+}
+function aggregateValues(fn, values) {
+  const present = values.filter((v) => v != null);
+  switch (fn) {
+    case "count":
+      return values.length;
+    case "sum":
+      return present.reduce((s, v) => s + v, 0);
+    case "avg":
+      return present.length === 0 ? null : present.reduce((s, v) => s + v, 0) / present.length;
+    case "countDistinct":
+      return new Set(present).size;
+    case "min":
+      return present.length === 0 ? null : present.reduce((m, v) => v < m ? v : m);
+    case "max":
+      return present.length === 0 ? null : present.reduce((m, v) => v > m ? v : m);
+  }
+}
+function compareForOrder(a, b) {
+  if (a == null && b == null) return 0;
+  if (a == null) return -1;
+  if (b == null) return 1;
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+function computeAggregateInJs(rows, spec) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = JSON.stringify(spec.by.map((col) => row[col]));
+    const group = groups.get(key);
+    if (group) group.push(row);
+    else groups.set(key, [row]);
+  }
+  if (spec.by.length === 0 && groups.size === 0) {
+    groups.set("[]", []);
+  }
+  let out = Array.from(groups.values()).map((groupRows) => {
+    const result = {};
+    for (const col of spec.by) {
+      result[col] = groupRows[0]?.[col];
+    }
+    for (const term of spec.select) {
+      result[term.alias] = aggregateValues(
+        term.fn,
+        term.column != null ? groupRows.map((r) => r[term.column]) : groupRows
+      );
+    }
+    return result;
+  });
+  if (spec.orderBy) {
+    const key = spec.orderBy;
+    out.sort((a, b) => compareForOrder(a[key], b[key]));
+    if (spec.desc) out.reverse();
+  }
+  if (spec.limit != null) {
+    out = out.slice(0, spec.limit);
+  }
+  return spec.by.length === 0 ? out[0] : out;
+}
+function deserializeAggregateRows(rows, spec, columns) {
+  const schemaFor = /* @__PURE__ */ new Map();
+  for (const col of spec.by) {
+    schemaFor.set(
+      col,
+      columns.filter((c) => c.name === col)
+    );
+  }
+  for (const term of spec.select) {
+    if ((term.fn === "min" || term.fn === "max") && term.column != null) {
+      schemaFor.set(
+        term.alias,
+        columns.filter((c) => c.name === term.column).map((c) => ({ ...c, name: term.alias }))
+      );
+    }
+  }
+  return rows.map((raw) => {
+    const row = raw;
+    const result = {};
+    for (const [key, value] of Object.entries(row)) {
+      const schema = schemaFor.get(key);
+      if (schema) {
+        result[key] = deserializeRow({ [key]: value }, schema)[key];
+      } else {
+        result[key] = value;
+      }
+    }
+    return result;
+  });
+}
+
 // src/db/query.ts
 var Query = class _Query {
   _predicates;
@@ -1130,6 +1364,8 @@ var Query = class _Query {
   /** @internal Pre-compiled WHERE clause (bypasses predicate compiler). Used by Table.get(). */
   _rawWhere;
   _rawWhereParams;
+  /** @internal See AggregateState — set by aggregate terminals. */
+  _aggregate;
   /** @internal Post-process transform applied after row deserialization. */
   _postProcess;
   constructor(config, options) {
@@ -1142,6 +1378,7 @@ var Query = class _Query {
     this._postProcess = options?.postProcess;
     this._rawWhere = options?.rawWhere;
     this._rawWhereParams = options?.rawWhereParams;
+    this._aggregate = options?.aggregate;
   }
   _clone(overrides) {
     return new _Query(this._config, {
@@ -1152,7 +1389,8 @@ var Query = class _Query {
       offset: overrides.offset ?? this._offset,
       postProcess: overrides.postProcess,
       rawWhere: this._rawWhere,
-      rawWhereParams: this._rawWhereParams
+      rawWhereParams: this._rawWhereParams,
+      aggregate: overrides.aggregate ?? this._aggregate
     });
   }
   filter(predicate, bindings) {
@@ -1190,9 +1428,60 @@ var Query = class _Query {
   }
   count() {
     return this._clone({
+      aggregate: { kind: "scalar", fn: "count" },
       postProcess: (rows) => rows.length
     });
   }
+  /**
+   * Sum of a numeric field across matching rows. Compiles to a SQL
+   * aggregate (TOTAL) when possible — no rows are fetched. Returns 0 for
+   * an empty set; NULL values are skipped (SQL semantics).
+   */
+  sum(accessor) {
+    return this._clone({
+      aggregate: { kind: "scalar", fn: "sum", accessor },
+      postProcess: (rows) => rows.reduce((total, row) => {
+        const value = accessor(row);
+        return value == null ? total : total + value;
+      }, 0)
+    });
+  }
+  /**
+   * Average of a numeric field across matching rows. Compiles to SQL AVG
+   * when possible. Returns null for an empty set (or when every value is
+   * null) — SQL AVG semantics.
+   */
+  avg(accessor) {
+    return this._clone({
+      aggregate: { kind: "scalar", fn: "avg", accessor },
+      postProcess: (rows) => {
+        const values = rows.map((row) => accessor(row)).filter((v) => v != null);
+        return values.length === 0 ? null : values.reduce((s, v) => s + v, 0) / values.length;
+      }
+    });
+  }
+  /**
+   * Number of distinct non-null values of a field across matching rows.
+   * Compiles to SQL COUNT(DISTINCT col) when possible.
+   */
+  countDistinct(accessor) {
+    return this._clone({
+      aggregate: { kind: "scalar", fn: "countDistinct", accessor },
+      postProcess: (rows) => new Set(rows.map((row) => accessor(row)).filter((v) => v != null)).size
+    });
+  }
+  aggregate(spec) {
+    const normalized = normalizeAggregateSpec(
+      spec
+    );
+    return this._clone({
+      aggregate: { kind: "grouped", spec: normalized },
+      postProcess: (rows) => computeAggregateInJs(
+        rows,
+        normalized
+      )
+    });
+  }
   some() {
     return this._clone({
       limit: 1,
@@ -1263,6 +1552,10 @@ var Query = class _Query {
     const compiled = this._compilePredicates();
     const sortField = this._sortAccessor ? extractFieldName(this._sortAccessor) : void 0;
     if (compiled.allSql) {
+      const agg = this._compileAggregateSql(compiled.sqlWhere);
+      if (agg) {
+        return { type: "query", query: agg.query, fallbackQuery: null, config: this._config, processRaw: agg.processRaw };
+      }
       const query = buildSelect(this._config.tableName, {
         where: compiled.sqlWhere || void 0,
         orderBy: sortField ?? void 0,
@@ -1294,6 +1587,9 @@ var Query = class _Query {
    * For JS-fallback queries: filter, sort, and slice in JS.
    */
   static _processResults(result, compiled) {
+    if (compiled.processRaw) {
+      return compiled.processRaw(result);
+    }
     const rows = result.rows.map(
       (row) => deserializeRow(
         row,
@@ -1326,10 +1622,81 @@ var Query = class _Query {
   // PromiseLike
   // -------------------------------------------------------------------------
   then(onfulfilled, onrejected) {
-    const promise = this._execute().then(
-      (rows) => this._postProcess ? this._postProcess(rows) : rows
-    );
-    return promise.then(onfulfilled, onrejected);
+    return this._run().then(onfulfilled, onrejected);
+  }
+  async _run() {
+    if (this._aggregate && !this._rawWhere) {
+      const compiled = this._compilePredicates();
+      if (compiled.allSql) {
+        const agg = this._compileAggregateSql(compiled.sqlWhere);
+        if (agg) {
+          const results = await this._config.executeBatch([agg.query]);
+          return agg.processRaw(results[0]);
+        }
+      }
+    }
+    const rows = await this._execute();
+    return this._postProcess ? this._postProcess(rows) : rows;
+  }
+  /**
+   * @internal Compile the pending aggregate into a single SQL statement +
+   * result processor. Returns null (→ fetch path, postProcess computes the
+   * aggregate) when there is no aggregate, when a pre-compiled WHERE is in
+   * play (Table.get()), when limit/offset are set (aggregate-the-page
+   * semantics — COUNT(*)/TOTAL can't express "over the limited page"), or
+   * when a scalar accessor doesn't extract to a column (computed accessors
+   * stay correct via JS, with a warning to prompt optimization).
+   */
+  _compileAggregateSql(sqlWhere) {
+    const agg = this._aggregate;
+    if (!agg || this._rawWhere || this._limit != null || this._offset != null) {
+      return null;
+    }
+    const where = sqlWhere || void 0;
+    if (agg.kind === "scalar") {
+      let column = null;
+      if (agg.accessor) {
+        column = extractFieldName(agg.accessor);
+        if (column == null) {
+          console.warn(
+            `[mindstudio] ${agg.fn}() accessor on '${this._config.tableName}' could not be compiled to SQL \u2014 fetching matching rows and computing in JS`
+          );
+          return null;
+        }
+      }
+      const query2 = buildScalarAggregate(
+        this._config.tableName,
+        agg.fn,
+        column,
+        where
+      );
+      const processRaw2 = (result) => {
+        const value = result.rows[0]?.value;
+        if (agg.fn === "avg") {
+          return value == null ? null : Number(value);
+        }
+        return Number(value ?? 0);
+      };
+      return { query: query2, processRaw: processRaw2 };
+    }
+    const spec = agg.spec;
+    const query = buildGroupedAggregate(this._config.tableName, {
+      by: spec.by,
+      select: spec.select,
+      where,
+      orderBy: spec.orderBy,
+      desc: spec.desc,
+      limit: spec.limit
+    });
+    const processRaw = (result) => {
+      const rows = deserializeAggregateRows(
+        result.rows,
+        spec,
+        this._config.columns
+      );
+      return spec.by.length === 0 ? rows[0] : rows;
+    };
+    return { query, processRaw };
   }
   catch(onrejected) {
     return this.then(void 0, onrejected);
@@ -1560,7 +1927,34 @@ var Table = class {
   max(accessor) {
     return this.sortBy(accessor).reverse().first();
   }
-  /** Group rows by a field. Returns a Map. */
+  /**
+   * Sum of a numeric field across all rows (0 for an empty table).
+   * Runs as a SQL aggregate — no rows are fetched. Chain from filter()
+   * to sum a subset: `Orders.filter(...).sum(o => o.amount)`.
+   */
+  sum(accessor) {
+    return this.toArray().sum(accessor);
+  }
+  /**
+   * Average of a numeric field across all rows (null for an empty table).
+   * Runs as a SQL aggregate — no rows are fetched.
+   */
+  avg(accessor) {
+    return this.toArray().avg(accessor);
+  }
+  /**
+   * Number of distinct non-null values of a field across all rows.
+   * Runs as a SQL aggregate — no rows are fetched.
+   */
+  countDistinct(accessor) {
+    return this.toArray().countDistinct(accessor);
+  }
+  aggregate(spec) {
+    return this.toArray().aggregate(spec);
+  }
+  /** Group rows by a field. Returns a Map of FULL rows per group — it
+   * fetches everything. For grouped counts/sums/averages over tables that
+   * can grow large, use `aggregate()` instead (SQL GROUP BY, no row fetch). */
   groupBy(accessor) {
     return new Query(this._config).groupBy(accessor);
   }
@@ -1796,6 +2190,57 @@ var Table = class {
   }
 };
 
+// src/db/raw.ts
+var RawQuery = class _RawQuery {
+  _databaseId;
+  _executeBatch;
+  _query;
+  constructor(databaseId, executeBatch, query) {
+    this._databaseId = databaseId;
+    this._executeBatch = executeBatch;
+    this._query = query;
+  }
+  // -------------------------------------------------------------------------
+  // PromiseLike — executes on await
+  // -------------------------------------------------------------------------
+  then(onfulfilled, onrejected) {
+    return this._execute().then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this._execute().catch(onrejected);
+  }
+  // -------------------------------------------------------------------------
+  // Batch support
+  // -------------------------------------------------------------------------
+  /** @internal Compile for db.batch(). */
+  _compile() {
+    return {
+      type: "raw",
+      query: this._query,
+      config: { databaseId: this._databaseId },
+      processResult: (result) => _RawQuery._process(result)
+    };
+  }
+  /** @internal Process a raw SQL result. Used by db.batch(). */
+  static _processResults(result, compiled) {
+    return compiled.processResult(result);
+  }
+  // -------------------------------------------------------------------------
+  // Execution
+  // -------------------------------------------------------------------------
+  /** Schema-less deserialization: strips @@user@@ prefixes and best-effort
+   * parses JSON-looking strings; makes no other representation promises. */
+  static _process(result) {
+    return result.rows.map(
+      (row) => deserializeRow(row, [])
+    );
+  }
+  async _execute() {
+    const results = await this._executeBatch([this._query]);
+    return _RawQuery._process(results[0]);
+  }
+};
+
 // src/db/index.ts
 function createDb(databases, executeBatch, authConfig, syncRoles) {
   return {
@@ -1823,6 +2268,16 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
     fromNow: (ms) => Date.now() + ms,
     // --- User references ---
     userRef: (id) => id.startsWith(USER_PREFIX) ? id.slice(USER_PREFIX.length) : id,
+    // --- Raw SQL (read-only) ---
+    sql(query, params, options) {
+      validateRawSql(query);
+      const database = resolveDatabase(databases, options?.database);
+      return new RawQuery(
+        database.id,
+        (queries) => executeBatch(database.id, queries),
+        { sql: query, params: params?.map(serializeParam) }
+      );
+    },
     // --- Batch execution ---
     batch: ((...operations) => {
       return (async () => {
@@ -1833,8 +2288,11 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
           if (op instanceof Mutation) {
             return op._compile();
           }
+          if (op instanceof RawQuery) {
+            return op._compile();
+          }
           throw new MindStudioError(
-            "db.batch() only accepts Query and Mutation objects (from .filter(), .update(), .push(), etc.)",
+            "db.batch() only accepts Query, Mutation, and RawQuery objects (from .filter(), .update(), .push(), db.sql(), etc.)",
             "invalid_batch_operation",
             400
           );
@@ -1847,6 +2305,8 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
           if (c.type === "query") {
             const sqlQuery = c.query ?? c.fallbackQuery;
             groups.get(dbId).push({ opIndex: i, sqlQueries: [sqlQuery] });
+          } else if (c.type === "raw") {
+            groups.get(dbId).push({ opIndex: i, sqlQueries: [c.query] });
           } else {
             groups.get(dbId).push({ opIndex: i, sqlQueries: c.queries });
           }
@@ -1879,6 +2339,8 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
               );
             }
             return Query._processResults(results[0], c);
+          } else if (c.type === "raw") {
+            return RawQuery._processResults(results[0], c);
           } else {
             return Mutation._processResults(results, c);
           }
@@ -1887,7 +2349,23 @@ function createDb(databases, executeBatch, authConfig, syncRoles) {
     })
   };
 }
-function resolveTable(databases, tableName, databaseHint) {
+function validateRawSql(query) {
+  if (typeof query !== "string" || !query.trim()) {
+    throw new MindStudioError(
+      "db.sql() requires a non-empty SQL string.",
+      "invalid_sql",
+      400
+    );
+  }
+  if (!/^\s*(select|with)\b/i.test(query)) {
+    throw new MindStudioError(
+      "db.sql() is read-only \u2014 the statement must start with SELECT or WITH. Use Table methods (push/update/upsert/remove) for writes.",
+      "sql_read_only",
+      400
+    );
+  }
+}
+function resolveDatabase(databases, hint) {
   if (databases.length === 0) {
     throw new MindStudioError(
       `No databases found in app context. Make sure the app has at least one database configured.`,
@@ -1895,18 +2373,40 @@ function resolveTable(databases, tableName, databaseHint) {
       400
     );
   }
-  if (databaseHint) {
+  if (hint) {
     const targetDb = databases.find(
-      (db2) => db2.id === databaseHint || db2.name === databaseHint
+      (db2) => db2.id === hint || db2.name === hint
     );
     if (!targetDb) {
       const available = databases.map((db2) => db2.name || db2.id).join(", ");
       throw new MindStudioError(
-        `Database "${databaseHint}" not found. Available databases: ${available}`,
+        `Database "${hint}" not found. Available databases: ${available}`,
         "database_not_found",
         400
       );
     }
+    return targetDb;
+  }
+  if (databases.length > 1) {
+    const available = databases.map((db2) => db2.name || db2.id).join(", ");
+    throw new MindStudioError(
+      `This app has multiple databases \u2014 pass { database } to pick one. Available databases: ${available}`,
+      "ambiguous_database",
+      400
+    );
+  }
+  return databases[0];
+}
+function resolveTable(databases, tableName, databaseHint) {
+  if (databases.length === 0) {
+    throw new MindStudioError(
+      `No databases found in app context. Make sure the app has at least one database configured.`,
+      "no_databases",
+      400
+    );
+  }
+  if (databaseHint) {
+    const targetDb = resolveDatabase(databases, databaseHint);
     const table = targetDb.tables.find((t) => t.name === tableName);
     if (!table) {
       const available = targetDb.tables.map((t) => t.name).join(", ");
@@ -2278,6 +2778,38 @@ function createVoice(call) {
   };
 }
 
+// src/analytics/index.ts
+function createAnalytics(call) {
+  return {
+    query(spec) {
+      return call("query", spec);
+    },
+    live() {
+      return call("live", {});
+    },
+    sources(options) {
+      return call("sources", options ?? {});
+    },
+    map(options) {
+      return call("map", options ?? {});
+    },
+    aiSources(options) {
+      return call("ai-sources", options ?? {});
+    },
+    crawlers: {
+      overview(options) {
+        return call("crawlers-overview", options ?? {});
+      },
+      timeseries(options) {
+        return call("crawlers-timeseries", options ?? {});
+      },
+      recent(options) {
+        return call("crawlers-recent", options ?? {});
+      }
+    }
+  };
+}
+
 // src/task/index.ts
 import { randomUUID as randomUUID2 } from "crypto";
 
@@ -3056,13 +3588,6 @@ var stepMetadata = {
     inputSchema: { "type": "object", "properties": { "webhookUrl": { "type": "string", "description": "Zapier webhook URL to send data to" }, "input": { "type": "object", "properties": {}, "required": [], "description": "Key-value pairs to send as the JSON POST body" } }, "required": ["webhookUrl", "input"] },
     outputSchema: { "type": "object", "properties": { "data": { "description": "Parsed webhook response from Zapier (JSON object, array, or string)" } }, "required": ["data"] }
   },
-  "queryAppDatabase": {
-    stepType: "queryAppDatabase",
-    description: "Execute a SQL query against the app managed database.",
-    usageNotes: '- Executes raw SQL against a SQLite database managed by the app.\n- For SELECT queries, returns rows as JSON.\n- For INSERT/UPDATE/DELETE, returns the number of affected rows.\n- Use {{variables}} directly in your SQL. By default they are automatically extracted\n  and passed as safe parameterized values (preventing SQL injection).\n  Example: INSERT INTO contacts (name, comment) VALUES ({{name}}, {{comment}})\n- Full MindStudio handlebars syntax is supported, including helpers like {{json myVar}},\n  {{get myVar "$.path"}}, {{global.orgName}}, etc.\n- Set parameterize to false for raw/dynamic SQL where variables are interpolated directly\n  into the query string. Use this when another step generates full or partial SQL, e.g.\n  a bulk INSERT with a precomputed VALUES list. The user is responsible for sanitization\n  when parameterize is false.',
-    inputSchema: { "type": "object", "properties": { "databaseId": { "type": "string", "description": "Name or ID of the app data database to query" }, "sql": { "type": "string", "description": "SQL query to execute. Use {{variables}} directly in the SQL \u2014 they are handled according to the `parameterize` setting.\n\nWhen parameterize is true (default):   {{variables}} are extracted from the SQL, replaced with ? placeholders,   resolved via the full MindStudio handlebars pipeline, and passed as safe   parameterized values to SQLite. This prevents SQL injection.   Example: INSERT INTO contacts (name, email) VALUES ({{name}}, {{email}})\n\nWhen parameterize is false:   The entire SQL string is resolved via compileString (standard handlebars   interpolation) and executed as-is. Use this for dynamic/generated SQL   where another step builds the query. The user is responsible for safety.   Example: {{generatedInsertQuery}}\n\nAsk the user for the database schema if they have not already provided it." }, "parameterize": { "type": "boolean", "description": "Whether to treat {{variables}} as parameterized query values (default: true).\n\n- true:  {{vars}} are extracted, replaced with ?, and passed as bind params.          Safe from SQL injection. Use for standard CRUD operations.\n- false: {{vars}} are interpolated directly into the SQL string via handlebars.          Use when another step generates full or partial SQL (e.g. bulk inserts          with precomputed VALUES). The user is responsible for sanitization." } }, "required": ["databaseId", "sql"] },
-    outputSchema: { "type": "object", "properties": { "rows": { "type": "array", "items": {}, "description": "Result rows for SELECT queries (empty array for write queries)" }, "changes": { "type": "number", "description": "Number of rows affected by INSERT, UPDATE, or DELETE queries (0 for SELECT)" } }, "required": ["rows", "changes"] }
-  },
   "queryDataSource": {
     stepType: "queryDataSource",
     description: "Legacy v1 data sources. v2 apps should use `dataSources.defineDataSource()` from @mindstudio-ai/agent instead, which owns parsing, chunking, embedding and citations. Search a vector data source (RAG) and return relevant document chunks.",
@@ -3266,9 +3791,11 @@ var stepMetadata = {
 - Set replyTo to control the Reply-To address for replies.
 - For threaded replies in a shared inbox, set inReplyTo (the Message-ID being replied to) and references (prior Message-IDs in the thread).
 - connectionId can be a comma-separated list to send to multiple recipients.
-- The special connectionId "trigger_email" uses the email address that triggered the workflow.`,
-    inputSchema: { "type": "object", "properties": { "subject": { "type": "string", "description": "Email subject line" }, "body": { "type": "string", "description": "Email body content (plain text, markdown, HTML, or a CDN URL to an HTML file)" }, "to": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "cc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "bcc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "connectionId": { "type": "string", "description": "OAuth connection ID(s) for the recipient(s), comma-separated for multiple" }, "generateHtml": { "type": "boolean", "description": "When true, auto-convert the body text into a styled HTML email using AI" }, "generateHtmlInstructions": { "type": "string", "description": "Natural language instructions for the HTML generation style" }, "generateHtmlModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": 'Model identifier (e.g. "gpt-4", "claude-3-opus")' }, "temperature": { "type": "number", "description": "Sampling temperature for the model (0-2)" }, "maxResponseTokens": { "type": "number", "description": "Maximum number of tokens in the model's response" }, "ignorePreamble": { "type": "boolean", "description": "Whether to skip the system preamble/instructions" }, "userMessagePreprocessor": { "type": "object", "properties": { "dataSource": { "type": "string", "description": "Data source identifier for the preprocessor" }, "messageTemplate": { "type": "string", "description": "Template string applied to user messages before sending to the model" }, "maxResults": { "type": "number", "description": "Maximum number of results to include from the data source" }, "enabled": { "type": "boolean", "description": "Whether the preprocessor is active" }, "shouldInherit": { "type": "boolean", "description": "Whether child steps should inherit this preprocessor configuration" } }, "description": "Preprocessor applied to user messages before sending to the model" }, "preamble": { "type": "string", "description": "System preamble/instructions for the model" }, "multiModelEnabled": { "type": "boolean", "description": "Whether multi-model candidate generation is enabled" }, "editResponseEnabled": { "type": "boolean", "description": "Whether the user can edit the model's response" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model", "temperature", "maxResponseTokens"], "description": "Model settings override for HTML generation" }, "attachments": { "type": "array", "items": { "anyOf": [{ "type": "string" }, { "type": "object", "properties": { "url": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" } }, "required": ["url"] }] }, "description": "Files to attach: each entry is a URL string, or an object `{ url, filename?, contentType? }` to control the displayed filename and MIME type." }, "from": { "type": "string", "description": "Custom sender handle \u2014 only for apps with a custom domain or subdomain. Bare handle (`support`), full `support@your-domain.com`, or `Name <support@your-domain.com>`. Must resolve to a domain the app owns." }, "bodyType": { "enum": ["auto", "html", "markdown", "text"], "type": "string", "description": "How to interpret `body`: `auto` (default \u2014 detect HTML, else render markdown), `html` (send as-is), `markdown` (render to HTML), or `text` (send as plain text only, no HTML part). Every send includes a text/plain alternative." }, "text": { "type": "string", "description": "Explicit text/plain alternative body. Auto-derived from `body` if omitted." }, "replyTo": { "type": "string", "description": "Reply-To address for the email." }, "inReplyTo": { "type": "string", "description": "Message-ID this email replies to, for inbox threading (In-Reply-To header)." }, "references": { "type": "array", "items": { "type": "string" }, "description": "Prior Message-IDs in the thread, for inbox threading (References header)." } }, "required": ["subject", "body"] },
-    outputSchema: { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "string" }, "description": "To addresses the message was sent to." }, "cc": { "type": "array", "items": { "type": "string" }, "description": "Cc addresses on the message (empty if none)." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "Bcc addresses on the message (empty if none)." }, "from": { "type": "string", "description": "The resolved sender address the message went out as (auto-selected when no `from` is given)." } }, "required": ["recipients", "cc", "bcc", "from"] }
+- The special connectionId "trigger_email" uses the email address that triggered the workflow.
+- Sends default to category "marketing": every message carries a one-click unsubscribe header pointing at the app's own domain, and recipients who previously unsubscribed from this app are skipped and returned in "suppressed". Because the unsubscribe link is per-recipient, a marketing send delivers one separate message per recipient and cc/bcc are folded into that list.
+- Set category to "transactional" for receipts, alerts, password resets and anything a recipient must not be able to opt out of. Transactional sends carry no unsubscribe header, ignore the unsubscribe list, and keep cc/bcc on a single message \u2014 use it whenever cc/bcc semantics matter.`,
+    inputSchema: { "type": "object", "properties": { "subject": { "type": "string", "description": "Email subject line" }, "body": { "type": "string", "description": "Email body content (plain text, markdown, HTML, or a CDN URL to an HTML file)" }, "to": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "cc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "bcc": { "anyOf": [{ "type": "string" }, { "type": "array", "items": { "type": "string" } }] }, "connectionId": { "type": "string", "description": "OAuth connection ID(s) for the recipient(s), comma-separated for multiple" }, "generateHtml": { "type": "boolean", "description": "When true, auto-convert the body text into a styled HTML email using AI" }, "generateHtmlInstructions": { "type": "string", "description": "Natural language instructions for the HTML generation style" }, "generateHtmlModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": 'Model identifier (e.g. "gpt-4", "claude-3-opus")' }, "temperature": { "type": "number", "description": "Sampling temperature for the model (0-2)" }, "maxResponseTokens": { "type": "number", "description": "Maximum number of tokens in the model's response" }, "ignorePreamble": { "type": "boolean", "description": "Whether to skip the system preamble/instructions" }, "userMessagePreprocessor": { "type": "object", "properties": { "dataSource": { "type": "string", "description": "Data source identifier for the preprocessor" }, "messageTemplate": { "type": "string", "description": "Template string applied to user messages before sending to the model" }, "maxResults": { "type": "number", "description": "Maximum number of results to include from the data source" }, "enabled": { "type": "boolean", "description": "Whether the preprocessor is active" }, "shouldInherit": { "type": "boolean", "description": "Whether child steps should inherit this preprocessor configuration" } }, "description": "Preprocessor applied to user messages before sending to the model" }, "preamble": { "type": "string", "description": "System preamble/instructions for the model" }, "multiModelEnabled": { "type": "boolean", "description": "Whether multi-model candidate generation is enabled" }, "editResponseEnabled": { "type": "boolean", "description": "Whether the user can edit the model's response" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model", "temperature", "maxResponseTokens"], "description": "Model settings override for HTML generation" }, "attachments": { "type": "array", "items": { "anyOf": [{ "type": "string" }, { "type": "object", "properties": { "url": { "type": "string" }, "filename": { "type": "string" }, "contentType": { "type": "string" } }, "required": ["url"] }] }, "description": "Files to attach: each entry is a URL string, or an object `{ url, filename?, contentType? }` to control the displayed filename and MIME type." }, "from": { "type": "string", "description": "Custom sender handle \u2014 only for apps with a custom domain or subdomain. Bare handle (`support`), full `support@your-domain.com`, or `Name <support@your-domain.com>`. Must resolve to a domain the app owns." }, "bodyType": { "enum": ["auto", "html", "markdown", "text"], "type": "string", "description": "How to interpret `body`: `auto` (default \u2014 detect HTML, else render markdown), `html` (send as-is), `markdown` (render to HTML), or `text` (send as plain text only, no HTML part). Every send includes a text/plain alternative." }, "text": { "type": "string", "description": "Explicit text/plain alternative body. Auto-derived from `body` if omitted." }, "replyTo": { "type": "string", "description": "Reply-To address for the email." }, "inReplyTo": { "type": "string", "description": "Message-ID this email replies to, for inbox threading (In-Reply-To header)." }, "references": { "type": "array", "items": { "type": "string" }, "description": "Prior Message-IDs in the thread, for inbox threading (References header)." }, "category": { "enum": ["transactional", "marketing"], "type": "string", "description": "`marketing` (default) adds one-click unsubscribe headers and skips recipients who unsubscribed from this app. Use `transactional` for receipts, alerts and password resets: no unsubscribe header, never suppressed, and cc/bcc preserved on a single message." } }, "required": ["subject", "body"] },
+    outputSchema: { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "string" }, "description": "To addresses the message was sent to." }, "cc": { "type": "array", "items": { "type": "string" }, "description": "Cc addresses on the message (empty if none)." }, "bcc": { "type": "array", "items": { "type": "string" }, "description": "Bcc addresses on the message (empty if none)." }, "from": { "type": "string", "description": "The resolved sender address the message went out as (auto-selected when no `from` is given)." }, "suppressed": { "type": "array", "items": { "type": "string" }, "description": "Recipients skipped because they unsubscribed from this app. Always empty for a `transactional` send." } }, "required": ["recipients", "cc", "bcc", "from", "suppressed"] }
   },
   "sendGmailDraft": {
     stepType: "sendGmailDraft",
@@ -4733,9 +5260,6 @@ function applyStepMethods(AgentClass) {
   proto.postToZapier = function(step, options) {
     return this.executeStep("postToZapier", step, options);
   };
-  proto.queryAppDatabase = function(step, options) {
-    return this.executeStep("queryAppDatabase", step, options);
-  };
   proto.queryDataSource = function(step, options) {
     return this.executeStep("queryDataSource", step, options);
   };
@@ -4962,6 +5486,7 @@ var MindStudioAgent = class {
   _files;
   _dataSources;
   _voice;
+  _analytics;
   /** @internal Auth type — 'internal' for CALLBACK_TOKEN (managed mode), 'apiKey' otherwise. */
   _authType;
   /** @internal Usage source sent on step executions (from MINDSTUDIO_REQUEST_SOURCE).
@@ -5978,6 +6503,27 @@ var MindStudioAgent = class {
   get files() {
     return this._files ??= createFiles(this._filesRequest.bind(this));
   }
+  /**
+   * The `analytics` namespace — read the app's own traffic + event analytics
+   * (auto-tracked pageviews, `analytics.track()` events). One general
+   * `query()` (metrics × dimensions × filters × time) plus `live()`,
+   * `sources()`, `map()`, `aiSources()`, `crawlers.*`. See {@link Analytics}
+   * for the lifetime-rollup vs 90-day-events split.
+   *
+   * @example
+   * ```ts
+   * const top = await agent.analytics.query({
+   *   metrics: ['pageviews', 'visitors'],
+   *   dimensions: ['path'],
+   *   dateRange: 'all',
+   * });
+   * ```
+   */
+  get analytics() {
+    return this._analytics ??= createAnalytics(
+      this._analyticsRequest.bind(this)
+    );
+  }
   /**
    * Jewel surfaces: arrival-shaped triggers (`propose`) and the app-native
    * approval queue (`queue.list` / `queue.resolve`). See {@link JewelsApi}.
@@ -6106,6 +6652,16 @@ var MindStudioAgent = class {
       fallbackCode: "voice_error"
     });
   }
+  /**
+   * @internal Transport for the `analytics` namespace —
+   * POST /_internal/v2/analytics/<op> with the raw hook token.
+   */
+  async _analyticsRequest(op, body) {
+    return this._brokeredRequest("analytics", op, body, {
+      fallbackMessage: "Analytics read failed",
+      fallbackCode: "analytics_error"
+    });
+  }
   /**
    * @internal Shared shape for the brokered `/_internal/v2/<ns>/<op>` data
    * planes. Factored out rather than copied per namespace so error handling
@@ -6299,6 +6855,24 @@ var MindStudioAgent = class {
       ago: (ms) => Date.now() - ms,
       fromNow: (ms) => Date.now() + ms,
       userRef: (id) => id.startsWith("@@user@@") ? id.slice("@@user@@".length) : id,
+      // Raw SQL — validate synchronously; database resolution needs context,
+      // so it happens inside the executeBatch closure at execution time
+      // (the same deferral lazy defineTable uses).
+      sql: ((query, params, options) => {
+        validateRawSql(query);
+        return new RawQuery(
+          "",
+          async (queries) => {
+            await agent.ensureContext();
+            const database = resolveDatabase(
+              agent._getContext().databases,
+              options?.database
+            );
+            return agent._executeDbBatch(database.id, queries);
+          },
+          { sql: query, params: params?.map(serializeParam) }
+        );
+      }),
       // Batch needs context — hydrate first, then delegate to real db
       batch: ((...queries) => {
         return (async () => {
@@ -6854,7 +7428,6 @@ var monacoSnippets = {
   "postToSlackChannel": { fields: [["channelId", "string"], ["messageType", ["string", "blocks"]], ["message", "string"]], outputKeys: [] },
   "postToX": { fields: [["text", "string"]], outputKeys: [] },
   "postToZapier": { fields: [["webhookUrl", "string"], ["input", "object"]], outputKeys: ["data"] },
-  "queryAppDatabase": { fields: [["databaseId", "string"], ["sql", "string"]], outputKeys: ["rows", "changes"] },
   "queryDataSource": { fields: [["dataSourceId", "string"], ["query", "string"], ["maxResults", "number"]], outputKeys: ["text", "chunks", "query", "citations", "latencyMs"] },
   "queryExternalDatabase": { fields: [["query", "string"], ["outputFormat", ["json", "csv"]]], outputKeys: ["data"] },
   "redactPII": { fields: [["input", "string"], ["language", "string"], ["entities", "array"]], outputKeys: ["text"] },
@@ -6880,7 +7453,7 @@ var monacoSnippets = {
   "searchXPosts": { fields: [["query", "string"], ["scope", ["recent", "all"]], ["options", "object"]], outputKeys: ["posts"] },
   "searchYoutube": { fields: [["query", "string"], ["limitPages", "string"], ["filter", "string"], ["filterType", "string"]], outputKeys: ["results"] },
   "searchYoutubeTrends": { fields: [["bp", ["now", "music", "gaming", "films"]], ["hl", "string"], ["gl", "string"]], outputKeys: [] },
-  "sendEmail": { fields: [["subject", "string"], ["body", "string"]], outputKeys: ["recipients", "cc", "bcc", "from"] },
+  "sendEmail": { fields: [["subject", "string"], ["body", "string"]], outputKeys: ["recipients", "cc", "bcc", "from", "suppressed"] },
   "sendGmailDraft": { fields: [["draftId", "string"]], outputKeys: [] },
   "sendGmailMessage": { fields: [["to", "string"], ["subject", "string"], ["message", "string"], ["messageType", ["plain", "html", "markdown"]]], outputKeys: ["messageId"] },
   "sendSlackDirectMessage": { fields: [["slackUserId", "string"], ["messageType", ["string", "blocks"]], ["message", "string"]], outputKeys: [] },
@@ -6969,6 +7542,13 @@ var voice = new Proxy({}, {
     return typeof value === "function" ? value.bind(target) : value;
   }
 });
+var analytics = new Proxy({}, {
+  get(_, prop) {
+    const target = mindstudio.analytics;
+    const value = Reflect.get(target, prop, target);
+    return typeof value === "function" ? value.bind(target) : value;
+  }
+});
 var session = new Proxy(
   {},
   {
@@ -6990,6 +7570,7 @@ export {
   MindStudioAgent2 as MindStudioAgent,
   MindStudioError,
   Roles,
+  analytics,
   auth,
   blockTypeAliases,
   dataSources,