@mindstudio-ai/agent 0.1.103 → 0.1.105

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.
@@ -830,8 +813,10 @@ Send an email to one or more recipient addresses.
 - 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.
-- Input: `{ subject: string, body: string, to?: string | string[], cc?: string | string[], bcc?: string | string[], connectionId?: string, generateHtml?: boolean, generateHtmlInstructions?: string, generateHtmlModelOverride?: { model: string, temperature: number, maxResponseTokens: number, ignorePreamble?: boolean, userMessagePreprocessor?: { dataSource?: string, messageTemplate?: string, maxResults?: number, enabled?: boolean, shouldInherit?: boolean }, preamble?: string, multiModelEnabled?: boolean, editResponseEnabled?: boolean, config?: object }, attachments?: (string | { url: string, filename?: string, contentType?: string })[], from?: string, bodyType?: "auto" | "html" | "markdown" | "text", text?: string, replyTo?: string, inReplyTo?: string, references?: string[] }`
-- Output: `{ recipients: string[], cc: string[], bcc: string[], from: string }`
+- 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 — use it whenever cc/bcc semantics matter.
+- Input: `{ subject: string, body: string, to?: string | string[], cc?: string | string[], bcc?: string | string[], connectionId?: string, generateHtml?: boolean, generateHtmlInstructions?: string, generateHtmlModelOverride?: { model: string, temperature: number, maxResponseTokens: number, ignorePreamble?: boolean, userMessagePreprocessor?: { dataSource?: string, messageTemplate?: string, maxResults?: number, enabled?: boolean, shouldInherit?: boolean }, preamble?: string, multiModelEnabled?: boolean, editResponseEnabled?: boolean, config?: object }, attachments?: (string | { url: string, filename?: string, contentType?: string })[], from?: string, bodyType?: "auto" | "html" | "markdown" | "text", text?: string, replyTo?: string, inReplyTo?: string, references?: string[], category?: "transactional" | "marketing" }`
+- Output: `{ recipients: string[], cc: string[], bcc: string[], from: string, suppressed: string[] }`
 
 #### sendGmailDraft
 Send an existing draft from the connected Gmail account.
@@ -1854,6 +1839,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.
@@ -1902,3 +1923,37 @@ Adding the same bytes twice is free — documents are content-addressed, so a re
 Everything in `SearchOptions` — `mode`, `filter`, `rerank`, `hybrid`, `maxPerDocument`, `highlight` — is free to change and takes effect on the next search. How documents are chunked and embedded is configured on the corpus itself with `mindstudio-prod datasources config` — not in code — and changing it on a populated source is rejected rather than silently rebuilding.
 
 **A data source is live and shared.** Unlike database tables there is no dev copy and no per-release isolation: adding or removing a document changes what the deployed app retrieves, immediately. Scenarios never reset a data source, and re-ingesting a large corpus costs real money.
+
+#### `analytics` — read the app's own traffic + event analytics
+
+The platform auto-tracks pageviews (and custom events via the frontend's `analytics.track()`); the backend `analytics` namespace is the read side, so app code can correlate real traffic with its own data — lifetime views next to each blog post, "N people reading now", conversions beside the records that produced them. Backend only (hook token); reads the LIVE app's real traffic even from a dev sandbox. Rate limited per app (120 reads/min).
+
+One general read, `query()`, shaped like the Plausible/GA4 query APIs:
+
+```typescript
+import { analytics } from '@mindstudio-ai/agent';
+
+// Lifetime pageviews + unique visitors per page — top 10.
+const top = await analytics.query({
+  metrics: ['pageviews', 'visitors'],
+  dimensions: ['path'],
+  dateRange: 'all',
+  limit: 10,
+});
+// top.results[0] → { dimensions: { path: '/post/hello' }, metrics: { pageviews: 4210, visitors: 1830 } }
+
+// Daily views for one post, full history.
+const series = await analytics.query({
+  metrics: ['pageviews'],
+  dimensions: ['time'],
+  granularity: 'day',
+  filters: [['is', 'path', ['/post/hello']]],
+  dateRange: 'all',
+});
+```
+
+Grammar: `metrics` from `pageviews | visitors | visits | events`; `dimensions` is at most ONE entity dimension (`path`, `referrerHost`, `sourceCategory`, `country`, `city`, `deviceType`, `browser`, `os`, `language`, `visitorType`, `utmSource`…`utmContent`, `eventName`) OR `'time'` (with `granularity: '5m'|'hour'|'day'|'week'|'month'` and optional IANA `timezone`); `filters` are `[op, dimension, values]` triples with ops `is | is_not | contains`; `dateRange` is a shorthand (`'1h'|'24h'|'7d'|'30d'|'90d'|'all'`) or `[startISO, endISO]`; `orderBy` (grouped only) accepts `pageviews` or `events`. With `dateRange: 'all'`, granularity is a minimum — the server coarsens as history grows. `city` filter values are plain city names (any country) and always read the 90-day event detail.
+
+**Retention split — the one thing to get right:** queries whose filters are all `is` and touch at most one dimension read a rollup kept forever (full lifetime history, exact unique visitors). Cross-dimension intersections, `is_not`, and `contains` scan raw events retained for 90 days; the server clamps the window and reports it. Check `meta`: `source` (`rollup` vs `events`), `clamped`, `window.served`, and `metricsOmitted` — metrics a shape can't carry (e.g. `visits` on grouped reads) are omitted there, never returned as silent zeros. `meta.total` carries the unpaginated group count for paging.
+
+Specials (same `dateRange`/filter-triple grammar): `analytics.live()` → `{count, countries, sparkline}` right now; `analytics.sources(opts?)` → per-session first-source ranking (UTM > referrer > direct) classified by category/vendor incl. AI assistants; `analytics.map(opts?)` → city lat/lon points; `analytics.aiSources(opts?)` → AI-assistant referrals per vendor; `analytics.crawlers.overview()/timeseries()/recent()` → bot/AI-crawler ingestion of the app's pages.

package/package.json

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