@mindstudio-ai/agent 0.1.103 → 0.1.104

package/llms.txt

@@ -642,23 +642,6 @@ Send data to a Zapier Zap via webhook and return the response.
 - Input: `{ webhookUrl: string, input: object }`
 - Output: `{ data: unknown }`
 
-#### queryAppDatabase
-Execute a SQL query against the app managed database.
-- Executes raw SQL against a SQLite database managed by the app.
-- For SELECT queries, returns rows as JSON.
-- For INSERT/UPDATE/DELETE, returns the number of affected rows.
-- Use {{variables}} directly in your SQL. By default they are automatically extracted
-and passed as safe parameterized values (preventing SQL injection).
-Example: INSERT INTO contacts (name, comment) VALUES ({{name}}, {{comment}})
-- Full MindStudio handlebars syntax is supported, including helpers like {{json myVar}},
-{{get myVar "$.path"}}, {{global.orgName}}, etc.
-- Set parameterize to false for raw/dynamic SQL where variables are interpolated directly
-into the query string. Use this when another step generates full or partial SQL, e.g.
-a bulk INSERT with a precomputed VALUES list. The user is responsible for sanitization
-when parameterize is false.
-- Input: `{ databaseId: string, sql: string, parameterize?: boolean }`
-- Output: `{ rows: unknown[], changes: number }`
-
 #### queryDataSource
 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.
 - Queries a vectorized data source and returns the most relevant chunks.
@@ -1854,6 +1837,42 @@ Generated assets: any action that produces a file (`generateImage`, `generateVid
 const { imageUrl } = await mindstudio.generateImage({ prompt: 'a red sneaker' }, { store: Assets });
 ```
 
+#### `db` — typed tables over the app's managed SQLite
+
+Chainable, typed collection API over the app's managed databases. Define a table at module scope; every read/write is lazy until awaited, and reads/writes can be batched into one round trip with `db.batch()`.
+```typescript
+import { db } from '@mindstudio-ai/agent';
+
+export const Orders = db.defineTable<Order>('orders');
+
+// Reads — filters compile to SQL WHERE when possible
+const recent = await Orders.filter(o => o.status === 'paid').sortBy(o => o.created_at).reverse().take(20);
+// Comparing to an outer-scope value? Use the bindings form so it compiles to SQL:
+const mine = await Orders.filter((o, $) => o.requestedBy === $.uid, { uid: auth.userId }); // bindings: lifts closure var so filter compiles to SQL
+
+// Writes
+const order = await Orders.push({ item: 'Laptop', amount: 999, status: 'pending' });
+await Orders.update(order.id, { status: 'approved' });
+```
+
+Aggregation — `count()`, `sum(fn)`, `avg(fn)`, `countDistinct(fn)`, and `aggregate(spec)` compile to SQL aggregates (COUNT/TOTAL/AVG/GROUP BY); no rows are fetched, so they stay cheap at any table size. Never page a whole table into memory to compute a summary.
+```typescript
+const top = await Answers
+  .filter((a, $) => a.surveyId === $.surveyId, { surveyId }) // bindings: compiles to SQL
+  .aggregate({
+    by: ['questionId', 'dimension'],
+    select: { n: { count: true }, total: { sum: 'score' }, avgScore: { avg: 'score' }, respondents: { countDistinct: 'responseId' } },
+    orderBy: 'total', desc: true, limit: 20,
+  });
+// Array<{ questionId, dimension, n: number, total: number, avgScore: number | null, respondents: number }>
+```
+Select terms: `{ count: true }` · `{ sum: 'col' }` · `{ avg: 'col' }` · `{ min: 'col' }` · `{ max: 'col' }` · `{ countDistinct: 'col' }` (string column names). Omit `by` for whole-set aggregates (single object). Empty set: count/countDistinct 0, sum 0, avg/min/max null.
+
+Raw SQL escape hatch — `db.sql<T>(query, params?, { database? })` runs read-only raw SQL (joins, subqueries, window functions) against the app's own managed database. SELECT/WITH only; writes throw — use Table methods. Lazy and batchable. Last resort: prefer the typed API (including `aggregate()`) whenever it can express the query; raw rows may not exactly match the typed API's value representations.
+```typescript
+const rows = await db.sql<{ questionId: string; n: number }>('SELECT questionId, COUNT(*) AS n FROM answers WHERE surveyId = ? GROUP BY questionId', [surveyId]);
+```
+
 #### `dataSources` — searchable document corpora (RAG)
 
 Declare a data source at module scope and import the handle. The platform owns parsing, chunking, embedding, storage and tenant isolation; every hit returns a citation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/agent",
-  "version": "0.1.103",
+  "version": "0.1.104",
   "description": "TypeScript SDK for MindStudio direct step execution",
   "type": "module",
   "main": "./dist/index.js",