@mindstudio-ai/agent 0.1.176 → 0.1.178

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/dist/analytics/index.d.ts +384 -0
  3. package/dist/auth/index.d.ts +113 -0
  4. package/dist/browser/index.d.ts +332 -0
  5. package/dist/cli.js +29 -29
  6. package/dist/client.d.ts +767 -0
  7. package/dist/config.d.ts +13 -0
  8. package/dist/context.d.ts +125 -0
  9. package/dist/datasources/index.d.ts +52 -0
  10. package/dist/datasources/source.d.ts +1074 -0
  11. package/dist/db/aggregate.d.ts +101 -0
  12. package/dist/db/index.d.ts +280 -0
  13. package/dist/db/mutation.d.ts +65 -0
  14. package/dist/db/predicate.d.ts +85 -0
  15. package/dist/db/query.d.ts +233 -0
  16. package/dist/db/raw.d.ts +36 -0
  17. package/dist/db/readBatching.d.ts +36 -0
  18. package/dist/db/scanHints.d.ts +8 -0
  19. package/dist/db/sql.d.ts +136 -0
  20. package/dist/db/table.d.ts +146 -0
  21. package/dist/db/time.d.ts +17 -0
  22. package/dist/db/types.d.ts +237 -0
  23. package/dist/db-ws.d.ts +35 -0
  24. package/dist/email/index.d.ts +396 -0
  25. package/dist/errors.d.ts +34 -0
  26. package/dist/events/index.d.ts +127 -0
  27. package/dist/files/index.d.ts +62 -0
  28. package/dist/files/store.d.ts +244 -0
  29. package/dist/generated/metadata.d.ts +8 -0
  30. package/dist/generated/snippets.d.ts +8 -0
  31. package/dist/generated/steps.d.ts +2745 -0
  32. package/dist/generated/types.d.ts +4234 -0
  33. package/dist/http.d.ts +22 -0
  34. package/dist/index.d.ts +59 -13329
  35. package/dist/index.js +17 -17
  36. package/dist/index.js.map +7 -1
  37. package/dist/jewel/index.d.ts +325 -0
  38. package/dist/mapper/index.d.ts +229 -0
  39. package/dist/rate-limit.d.ts +25 -0
  40. package/dist/reader/index.d.ts +170 -0
  41. package/dist/respond.d.ts +68 -0
  42. package/dist/task/index.d.ts +18 -0
  43. package/dist/task/local.d.ts +48 -0
  44. package/dist/task/schema.d.ts +120 -0
  45. package/dist/task/types.d.ts +203 -0
  46. package/dist/types.d.ts +591 -0
  47. package/dist/voice/index.d.ts +87 -0
  48. package/llms.txt +2 -2
  49. package/package.json +6 -12
  50. package/dist/postinstall.js +0 -12115
@@ -0,0 +1,237 @@
1
+ /**
2
+ * Internal type definitions for the `db` namespace.
3
+ *
4
+ * These types power the chainable collection API over MindStudio's managed
5
+ * SQLite databases. They're used internally by Table, Query, and the
6
+ * predicate compiler — most are also re-exported from the package for
7
+ * consumers who need them in type annotations.
8
+ *
9
+ * Key concepts:
10
+ * - **SystemFields**: columns managed by the platform (id, timestamps, audit).
11
+ * Never part of a table's own write input; a write may still set the
12
+ * timestamps and the author (`SettableSystemColumns`), never `id`.
13
+ * - **Predicate / Accessor**: callback shapes used in filter(), sortBy(), etc.
14
+ * Predicates are compiled to SQL WHERE clauses when possible, with a JS
15
+ * fallback for complex expressions.
16
+ * - **TableConfig**: runtime binding between a Table instance and the
17
+ * underlying queryAppDatabase step execution.
18
+ */
19
+ import type { AppDatabaseColumnSchema } from '../types.js';
20
+ /**
21
+ * Names of columns that the platform manages automatically.
22
+ *
23
+ * - `id`: UUID primary key, generated on INSERT
24
+ * - `created_at`: unix timestamp (ms), set on INSERT
25
+ * - `updated_at`: unix timestamp (ms), set on INSERT and every UPDATE
26
+ * - `last_updated_by`: the user who last wrote this row
27
+ *
28
+ * Both snake_case (platform convention) and camelCase (legacy) are left
29
+ * out of a table's own input types, to support either naming convention in
30
+ * table interfaces. The snake_case ones come back as `SettableSystemColumns`.
31
+ */
32
+ export type SystemFields = 'id' | 'created_at' | 'createdAt' | 'updated_at' | 'updatedAt' | 'last_updated_by' | 'lastUpdatedBy';
33
+ /**
34
+ * System columns added to every row on read. This is the concrete shape
35
+ * of the platform-managed columns — used to augment user-defined interfaces
36
+ * so reads include id, timestamps, etc. regardless of whether the user
37
+ * declared them.
38
+ */
39
+ export interface SystemColumns {
40
+ id: string;
41
+ created_at: number;
42
+ updated_at: number;
43
+ last_updated_by: string;
44
+ }
45
+ /**
46
+ * A row as returned from the database. Merges the user-defined type T
47
+ * with system columns. If T already includes system columns (e.g., the
48
+ * user declared `id: string`), the intersection is harmless — same type.
49
+ *
50
+ * This ensures TypeScript knows about `id`, `created_at`, etc. on read
51
+ * results even if the user's interface only declares their own fields.
52
+ */
53
+ export type Row<T> = T & SystemColumns;
54
+ /**
55
+ * The system columns a write may set, to carry a record's history in (an
56
+ * import, a scenario's seed data). Whichever a write leaves out the platform
57
+ * fills in: `created_at` and `updated_at` with now, and `last_updated_by` with
58
+ * the signed-in user (or nobody). An update that leaves them out advances
59
+ * `updated_at` and stamps `last_updated_by`, as every write does. `id` is
60
+ * always the platform's.
61
+ */
62
+ export interface SettableSystemColumns {
63
+ /** When the row was created, unix ms. */
64
+ created_at?: number;
65
+ /** When the row was last changed, unix ms. */
66
+ updated_at?: number;
67
+ /** The id of the user who last changed the row. */
68
+ last_updated_by?: string;
69
+ }
70
+ /**
71
+ * Input type for `Table.push()`. Excludes `id`, which the platform
72
+ * generates, and takes the other system columns optionally
73
+ * (`SettableSystemColumns`). Optional fields in T remain optional.
74
+ *
75
+ * @example
76
+ * ```ts
77
+ * // If Order has { item: string; amount: number }
78
+ * // then PushInput<Order> is { item: string; amount: number }
79
+ * // plus optional created_at, updated_at and last_updated_by
80
+ * ```
81
+ */
82
+ export type PushInput<T> = Omit<T, SystemFields> & SettableSystemColumns;
83
+ /**
84
+ * Input type for `Table.update()`. Every field is optional (partial update),
85
+ * the settable system columns included; `id` is never written.
86
+ */
87
+ export type UpdateInput<T> = Partial<Omit<T, SystemFields>> & SettableSystemColumns;
88
+ /**
89
+ * A predicate function for filtering rows. Receives a typed row and
90
+ * returns a boolean.
91
+ *
92
+ * The SDK attempts to compile the predicate to a SQL WHERE clause for
93
+ * performance. Simple expressions (field comparisons, &&/||, .includes(),
94
+ * constant right-hand sides like `db.ago(db.days(7))`) compile to efficient
95
+ * SQL. If the predicate can't be compiled (function calls, regex, computed
96
+ * fields), the SDK falls back to fetching all rows and evaluating in JS. Both
97
+ * paths select the same rows, NULL columns included.
98
+ *
99
+ * For predicates that compare to outer-scope values (e.g.
100
+ * `o => o.companyId === input.companyId`), prefer the explicit-bindings
101
+ * form so the filter compiles to SQL instead of falling back to JS:
102
+ *
103
+ * ```ts
104
+ * Investments.filter(
105
+ * (i, $) => i.companyId === $.companyId,
106
+ * { companyId: input.companyId },
107
+ * )
108
+ * ```
109
+ */
110
+ export type Predicate<T> = (row: T, bindings?: any) => boolean;
111
+ /**
112
+ * Bindings for an explicit-bindings predicate — a plain object of named
113
+ * scalar values referenced via the predicate's second parameter.
114
+ *
115
+ * @example
116
+ * ```ts
117
+ * const bindings: PredicateBindings = { companyId: 'abc', minAmount: 1000 };
118
+ * Investments.filter((i, $) => i.companyId === $.companyId && i.amount >= $.minAmount, bindings);
119
+ * ```
120
+ */
121
+ export type PredicateBindings = Record<string, unknown>;
122
+ /**
123
+ * A field accessor function used by sortBy(), min(), max(), groupBy().
124
+ * Receives a typed row and returns the value to sort/aggregate by.
125
+ *
126
+ * @example
127
+ * ```ts
128
+ * .sortBy(o => o.createdAt) // sort by createdAt
129
+ * .min(o => o.amount) // row with smallest amount
130
+ * .groupBy(o => o.status) // group rows by status
131
+ * ```
132
+ */
133
+ export type Accessor<T, R = unknown> = (row: T) => R;
134
+ /**
135
+ * Runtime configuration for a Table instance. Created by `createDb()` when
136
+ * `defineTable()` is called. Contains everything the Table needs to execute
137
+ * queries against the correct database.
138
+ */
139
+ export interface TableConfig {
140
+ /**
141
+ * The managed database ID (from app context metadata). Empty on a lazy
142
+ * table until its context is loaded (`ready`).
143
+ */
144
+ databaseId: string;
145
+ /** The SQL table name (as declared in defineTable). */
146
+ tableName: string;
147
+ /**
148
+ * Column schema from app context. Used to identify user-type columns
149
+ * (which need @@user@@ prefix handling) and for validation.
150
+ */
151
+ columns: AppDatabaseColumnSchema[];
152
+ /**
153
+ * Unique constraints declared via defineTable options.
154
+ * Each entry is an array of column names that form a unique constraint.
155
+ * e.g. [['email'], ['userId', 'orgId']]
156
+ */
157
+ unique?: string[][];
158
+ /**
159
+ * Default values for columns, applied client-side in push() and upsert().
160
+ * Explicit values in the input override defaults.
161
+ */
162
+ defaults?: Record<string, unknown>;
163
+ /**
164
+ * Platform-managed auth columns. Set when this table is the app's auth
165
+ * table. Writes to the apiKey column throw; email, phone and roles are the
166
+ * app's to write, and a roles write syncs to the platform.
167
+ */
168
+ managedColumns?: {
169
+ email?: string;
170
+ phone?: string;
171
+ roles?: string;
172
+ apiKey?: string;
173
+ };
174
+ /**
175
+ * Sync role changes to the platform after a successful auth table write.
176
+ * Fire-and-forget: failures are caught and logged internally.
177
+ * @internal Provided by the agent instance; has closure over HTTP config.
178
+ */
179
+ syncRoles?: (userId: string, roles: unknown) => Promise<void>;
180
+ /**
181
+ * Execute one or more SQL queries against the managed database in a
182
+ * single round trip. All queries run on the same SQLite connection,
183
+ * enabling RETURNING clauses and multi-statement batches.
184
+ *
185
+ * Bound to the `POST /_internal/v2/db/query` endpoint at creation time.
186
+ *
187
+ * @param queries - Array of SQL queries with optional bind params
188
+ * @returns Array of results in the same order as the input queries
189
+ */
190
+ executeBatch: (queries: SqlQuery[]) => Promise<SqlResult[]>;
191
+ /**
192
+ * Loads the app's context, for a table defined before it was available
193
+ * (the lazy db's `defineTable`). Such a table's database, columns and
194
+ * managed columns read the context whenever they're read, so whatever
195
+ * builds SQL from them awaits this first: built without them, a write
196
+ * stores a user ID with no `@@user@@` prefix and skips the managed-column
197
+ * check. Absent on a table made with its context in hand.
198
+ */
199
+ ready?: () => Promise<void>;
200
+ }
201
+ /** A single SQL query with optional positional bind params. */
202
+ export interface SqlQuery {
203
+ sql: string;
204
+ params?: unknown[];
205
+ }
206
+ /** Result of a single SQL query execution. */
207
+ export interface SqlResult {
208
+ rows: unknown[];
209
+ changes: number;
210
+ }
211
+ /**
212
+ * Result of attempting to compile a predicate function to SQL.
213
+ *
214
+ * - `type: 'sql'` — compilation succeeded. `where` is a SQL WHERE clause
215
+ * fragment (without the WHERE keyword), its values bound as `params`, in
216
+ * the order their `?` appear.
217
+ * - `type: 'js'` — compilation failed. The original function should be
218
+ * used to filter rows in JavaScript after fetching all rows.
219
+ */
220
+ export type CompiledPredicate<T> = {
221
+ type: 'sql';
222
+ where: string;
223
+ params: unknown[];
224
+ } | {
225
+ type: 'js';
226
+ fn: Predicate<T>;
227
+ reason?: string;
228
+ };
229
+ /**
230
+ * A predicate paired with its bindings. Stored internally on Query so that
231
+ * each filter call's bindings travel with its predicate through the chain.
232
+ * @internal
233
+ */
234
+ export interface PredicateEntry<T> {
235
+ fn: Predicate<T>;
236
+ bindings?: PredicateBindings;
237
+ }
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Thrown on a WS-transport failure so the caller can fall back to fetch.
3
+ *
4
+ * `sent` records whether the request was fully handed to the socket before the
5
+ * failure. It decides whether a fetch retry is safe: an UNSENT request provably
6
+ * never executed and always retries transparently; a SENT one may have executed
7
+ * server-side with only the response lost — re-running a batch that contains
8
+ * writes would double-apply them, so the caller only retries sent requests when
9
+ * every statement is a read.
10
+ *
11
+ * For a chunked request `sent` only becomes true once `db-end` is away, so a
12
+ * large write that fails partway through its own upload is provably unsent and
13
+ * retries cleanly. That case used to skip the socket entirely.
14
+ */
15
+ export declare class DbWsTransportError extends Error {
16
+ readonly sent: boolean;
17
+ readonly name = "DbWsTransportError";
18
+ constructor(message: string, sent?: boolean);
19
+ }
20
+ /**
21
+ * Whether a statement is definitely read-only, for the retry decision above.
22
+ * Deliberately conservative: only unambiguous read prefixes count — anything
23
+ * else (including `WITH …`, which can head an INSERT) is treated as a write,
24
+ * because the cost of misclassifying a write as a read is a double-apply.
25
+ */
26
+ export declare function isReadOnlySql(sql: string): boolean;
27
+ interface SqlResult {
28
+ rows: unknown[];
29
+ changes: number;
30
+ }
31
+ export declare function executeDbBatchOverWs(url: string, token: string, databaseId: string, queries: {
32
+ sql: string;
33
+ params?: unknown[];
34
+ }[]): Promise<SqlResult[]>;
35
+ export {};
@@ -0,0 +1,396 @@
1
+ /**
2
+ * The `email` namespace: send, read and manage your app's OWN outbound email.
3
+ *
4
+ * `email.send()` is the send path. The older `mindstudio.sendEmail({...})` action
5
+ * still works and shares exactly the same implementation, so nothing breaks — but
6
+ * `send()` is the one to reach for: it returns a proper receipt (including the
7
+ * `batchId` you read stats back with) and it lives alongside everything you do
8
+ * with the result.
9
+ *
10
+ * The rest of the namespace is everything *after* the send: what happened to each
11
+ * message, how a campaign performed, and who has unsubscribed.
12
+ *
13
+ * The point is that you can build your own email admin screen inside your own app
14
+ * and never open the MindStudio dashboard. So this deliberately includes the
15
+ * suppression writes, not just reads — anything the dashboard can do to your app's
16
+ * unsubscribe list, this can do too.
17
+ *
18
+ * Every call is scoped to the executing app by its request token; there is no
19
+ * appId parameter and no way to read or send as another app.
20
+ */
21
+ /** Where a message got to. See `EmailMessage.status`. */
22
+ export type EmailMessageStatus =
23
+ /** Recipient had unsubscribed — never handed to the provider. */
24
+ 'suppressed'
25
+ /** Failed before the provider: daily cap, sender not allowed, bad address. */
26
+ | 'failed'
27
+ /** The provider accepted it. */
28
+ | 'sent'
29
+ /** The receiving mail server accepted it. NOT "landed in the inbox". */
30
+ | 'delivered'
31
+ /**
32
+ * Dropped by the platform-wide suppression list — usually because of a hard
33
+ * bounce recorded against this address for ANOTHER app. Not a sign that your
34
+ * app did anything wrong, and it doesn't count toward your bounce rate.
35
+ */
36
+ | 'blocked' | 'bounced' | 'complained' | 'delayed' | 'rejected';
37
+ /** `method` = your app's `sendEmail` calls; `auth` = platform sign-in codes. */
38
+ export type EmailMessageKind = 'method' | 'auth';
39
+ export interface EmailMessage {
40
+ id: string;
41
+ recipient: string;
42
+ status: EmailMessageStatus;
43
+ category: string;
44
+ kind: EmailMessageKind;
45
+ subject: string | null;
46
+ fromAddress: string | null;
47
+ methodId: string | null;
48
+ /** The blast this message was part of, if any. */
49
+ batchId: string | null;
50
+ /** Provider diagnostics — for a bounce, includes the SMTP reason. */
51
+ diagnostic: Record<string, unknown> | null;
52
+ sentAt: string | null;
53
+ deliveredAt: string | null;
54
+ bouncedAt: string | null;
55
+ complainedAt: string | null;
56
+ delayedAt: string | null;
57
+ rejectedAt: string | null;
58
+ failedAt: string | null;
59
+ createdAt: string;
60
+ }
61
+ export interface EmailStats {
62
+ counts: Record<EmailMessageStatus, number>;
63
+ /**
64
+ * Messages the provider accepted — the denominator behind every rate below.
65
+ *
66
+ * Worth checking before you render a percentage: 1 bounce out of 10 sends is a
67
+ * 10% bounce rate, and showing that next to the 5% industry review threshold
68
+ * alarms someone over a sample of ten. Below ~50 accepted, show counts instead.
69
+ */
70
+ accepted: number;
71
+ rates: {
72
+ bounceRate: number;
73
+ complaintRate: number;
74
+ deliveredRate: number;
75
+ };
76
+ byKind: Record<EmailMessageKind, number>;
77
+ /** Bucketed counts over the window, for charting. */
78
+ series: Array<{
79
+ t: string;
80
+ counts: Record<string, number>;
81
+ }>;
82
+ }
83
+ /**
84
+ * Lifecycle of a QUEUED send. Large and marketing sends are accepted
85
+ * immediately and delivered in the background, so a blast can legitimately be
86
+ * observed mid-flight:
87
+ *
88
+ * `accepted` — queued, nothing delivered yet. `sending` — delivery in
89
+ * progress. `completed` — every recipient was handed to the provider.
90
+ * `partial` — finished, but some recipients were not sent to. `failed` —
91
+ * finished and nothing was sent.
92
+ */
93
+ export type EmailBatchLifecycle = 'accepted' | 'sending' | 'completed' | 'partial' | 'failed';
94
+ /**
95
+ * One blast, aggregated.
96
+ *
97
+ * `recipients` counts every row including those never handed to the provider;
98
+ * `accepted` counts only those it took, and is the honest denominator for a rate.
99
+ */
100
+ export interface EmailBatch {
101
+ batchId: string;
102
+ subject: string | null;
103
+ startedAt: string;
104
+ recipients: number;
105
+ accepted: number;
106
+ counts: Record<EmailMessageStatus, number>;
107
+ /**
108
+ * Delivery lifecycle, when the send was QUEUED. `null` means the send was
109
+ * delivered inline (small transactional sends) and already finished — treat
110
+ * null as done, never as unknown.
111
+ */
112
+ status: EmailBatchLifecycle | null;
113
+ /** Delivery-chunk progress, when queued. Null otherwise. */
114
+ chunksTotal: number | null;
115
+ chunksDone: number | null;
116
+ /** Recipients not yet attempted, when queued. Null otherwise. */
117
+ pending: number | null;
118
+ }
119
+ export interface EmailSuppression {
120
+ id: string;
121
+ email: string;
122
+ /**
123
+ * How the address ended up suppressed.
124
+ *
125
+ * `one_click` — the RFC 8058 one-click button in their mail client.
126
+ * `link` — the visible unsubscribe link in the message body.
127
+ * `owner` — you added them (dashboard, CLI, or `suppress()`).
128
+ * `complaint` — the receiving provider reported it as spam.
129
+ */
130
+ source: 'one_click' | 'link' | 'owner' | 'complaint';
131
+ createdAt: string;
132
+ }
133
+ /**
134
+ * An address on the PLATFORM's suppression list, which is separate from your
135
+ * app's. Populated automatically on hard bounces and complaints, shared across the
136
+ * whole platform, and never cleared — re-sending to a hard-bounced address would
137
+ * spend sending reputation belonging to everyone.
138
+ *
139
+ * So when this is non-null after an `unsuppress`, the address is off *your* list
140
+ * but mail to it is still blocked. Tell the user that rather than reporting
141
+ * success.
142
+ */
143
+ export interface PlatformSuppression {
144
+ /** `BOUNCE` or `COMPLAINT`. */
145
+ reason: string;
146
+ at: string | null;
147
+ }
148
+ export interface UnsuppressResult {
149
+ ok: true;
150
+ /** False when the address wasn't on your list to begin with. */
151
+ removed: boolean;
152
+ platformSuppression: PlatformSuppression | null;
153
+ }
154
+ export interface EmailListOptions {
155
+ statuses?: EmailMessageStatus[];
156
+ kind?: EmailMessageKind;
157
+ category?: 'transactional' | 'marketing';
158
+ methodId?: string;
159
+ /** Exact address match — the fast path, and the one to use for a support lookup. */
160
+ recipient?: string;
161
+ /** One blast. */
162
+ batchId?: string;
163
+ /** Contains-match over recipient and subject. Bounded, and not paginated. */
164
+ search?: string;
165
+ start?: string | Date;
166
+ end?: string | Date;
167
+ sort?: 'newest' | 'oldest';
168
+ cursor?: string;
169
+ /** Ignored when `cursor` is set — the cursor is the precise mechanism. */
170
+ offset?: number;
171
+ limit?: number;
172
+ }
173
+ export interface EmailWindowOptions {
174
+ start?: string | Date;
175
+ end?: string | Date;
176
+ }
177
+ /**
178
+ * How a message body is interpreted.
179
+ *
180
+ * `auto` (the default) sniffs it: something that looks like HTML is sent as HTML,
181
+ * anything else is rendered from Markdown. Every message goes out multipart with a
182
+ * plain-text alternative derived from the body, which mail providers reward.
183
+ */
184
+ export type EmailBodyType = 'auto' | 'html' | 'markdown' | 'text';
185
+ export interface EmailAttachmentInput {
186
+ url: string;
187
+ /** Displayed filename. Derived from the URL when omitted. */
188
+ filename?: string;
189
+ contentType?: string;
190
+ }
191
+ export interface EmailSendOptions {
192
+ /** Visible recipients. Optional only if you supply `cc` or `bcc`. */
193
+ to?: string | string[];
194
+ cc?: string | string[];
195
+ /**
196
+ * Hidden recipients. With no `to`/`cc`, the To: header is addressed to your
197
+ * app's own sender — the standard "undisclosed recipients" pattern — so
198
+ * recipients can't see each other.
199
+ */
200
+ bcc?: string | string[];
201
+ subject: string;
202
+ /** Plain text, Markdown, or HTML. See {@link EmailBodyType}. */
203
+ body: string;
204
+ bodyType?: EmailBodyType;
205
+ /** Your own plain-text alternative, instead of the auto-derived one. */
206
+ text?: string;
207
+ attachments?: Array<string | EmailAttachmentInput>;
208
+ /**
209
+ * Sender handle — only if your app has a custom domain or platform subdomain.
210
+ * `"support"`, `"support@your-domain.com"`, or `"Name <support@your-domain.com>"`.
211
+ * The domain must be one your app owns or the send fails.
212
+ */
213
+ from?: string;
214
+ replyTo?: string;
215
+ /** Message-ID this replies to, for threading in a shared inbox. */
216
+ inReplyTo?: string;
217
+ /** Prior Message-IDs in the thread. */
218
+ references?: string[];
219
+ /**
220
+ * **Defaults to `marketing`**, which is the consequential choice here.
221
+ *
222
+ * `marketing` attaches a one-click unsubscribe header pointing at your own
223
+ * domain and skips anyone who previously unsubscribed from your app. Because
224
+ * that link is per-recipient, a marketing send delivers one separate message per
225
+ * recipient and `cc`/`bcc` are folded into that list — so they come back empty.
226
+ *
227
+ * `transactional` is for receipts, alerts and password resets: no unsubscribe
228
+ * header, the unsubscribe list is ignored, and `cc`/`bcc` stay on one shared
229
+ * message. Use it whenever cc/bcc semantics actually matter.
230
+ */
231
+ category?: 'transactional' | 'marketing';
232
+ /**
233
+ * Groups this send's per-recipient rows into one blast. Pass your own campaign
234
+ * id (1–64 printable chars) to join our delivery stats onto your own tables with
235
+ * no mapping; one is generated when omitted, and it's always returned.
236
+ */
237
+ batchId?: string;
238
+ }
239
+ export interface EmailSendResult {
240
+ /** Addresses the message went to. */
241
+ recipients: string[];
242
+ /** Always empty for a marketing send — see `category`. */
243
+ cc: string[];
244
+ /** Always empty for a marketing send — see `category`. */
245
+ bcc: string[];
246
+ /** The resolved sender it went out as. */
247
+ from: string;
248
+ /**
249
+ * Recipients skipped because they had unsubscribed from your app. **Not an
250
+ * error** — the send succeeded and we honoured their opt-out. Always empty for
251
+ * a transactional send.
252
+ *
253
+ * Worth surfacing to whoever triggered the send: "sent to 48 of 50, 2
254
+ * unsubscribed" is the honest report, and silence here is what makes people
255
+ * think mail vanished.
256
+ */
257
+ suppressed: string[];
258
+ /** Read stats back with `email.batch(batchId)`. */
259
+ batchId: string;
260
+ }
261
+ /** Your app's sending allowance for the current window. */
262
+ export interface EmailQuota {
263
+ /** What the numbers count — `recipients`. */
264
+ unit: string;
265
+ window: 'day' | 'month' | 'total';
266
+ /** `null` means unlimited. */
267
+ limit: number | null;
268
+ used: number;
269
+ /** `null` when `limit` is null. */
270
+ remaining: number | null;
271
+ /** When `used` resets. */
272
+ resetsAt: string | null;
273
+ }
274
+ export type EmailTransport = (op: string, body: unknown) => Promise<any>;
275
+ export interface Email {
276
+ /**
277
+ * Send an email.
278
+ *
279
+ * Two things to know before your first call. **`category` defaults to
280
+ * `marketing`**, which fans a multi-recipient send out into one message each and
281
+ * empties `cc`/`bcc` — pass `'transactional'` for receipts, alerts and codes.
282
+ * And a non-empty `suppressed` in the result is a **success**, not a failure: it
283
+ * lists people who had unsubscribed and were therefore skipped.
284
+ *
285
+ * Delivery is split from acceptance: small transactional sends deliver before
286
+ * this resolves; marketing and large sends are QUEUED — this resolves once the
287
+ * send is accepted, and delivery continues in the background. Track progress
288
+ * with `email.batch(batchId)` (`status`, `pending`, chunk counts); outcomes
289
+ * (delivered, bounced, complained) arrive later on `email.messages({ batchId })`.
290
+ *
291
+ * Who you can mail depends on the sender. From the app's own subdomain or a
292
+ * verified sending domain, anyone. An app with neither sends from the
293
+ * platform's shared address, which only mails the app's verified users and its
294
+ * workspace's members, in dev and live alike, and refuses the whole send with
295
+ * `unverified_recipients` (400) otherwise. Mail to people who haven't signed in
296
+ * (a form's acknowledgement, an invite) needs a subdomain or sending domain.
297
+ *
298
+ * Throws `outbound_daily_cap_exceeded` (429) over the app's daily recipient
299
+ * quota — check `email.quota()` before a big send — and `sending_paused` (409)
300
+ * when the app's sending is paused for reputation or by support; a 409 will
301
+ * not succeed on retry.
302
+ *
303
+ * @example
304
+ * ```ts
305
+ * // A receipt: one message, cc preserved, no unsubscribe header.
306
+ * await email.send({
307
+ * to: 'customer@example.com',
308
+ * cc: 'billing@your-co.com',
309
+ * subject: 'Your receipt',
310
+ * body: '# Thanks!\n\nOrder #1234 is confirmed.',
311
+ * category: 'transactional',
312
+ * });
313
+ *
314
+ * // A campaign: per-recipient unsubscribe, your own id for joining stats.
315
+ * const { suppressed, batchId } = await email.send({
316
+ * to: subscribers,
317
+ * subject: 'August newsletter',
318
+ * body: markdown,
319
+ * batchId: 'newsletter-2026-08',
320
+ * });
321
+ * console.log(`skipped ${suppressed.length} unsubscribed`);
322
+ * const stats = await email.batch(batchId);
323
+ * ```
324
+ */
325
+ send(options: EmailSendOptions): Promise<EmailSendResult>;
326
+ /**
327
+ * Your app's sending allowance and how much is left.
328
+ *
329
+ * Useful before a large send: check `remaining` and split the list rather than
330
+ * discovering the limit as a failure partway through. Going over throws with
331
+ * `outbound_daily_cap_exceeded`.
332
+ */
333
+ quota(): Promise<EmailQuota>;
334
+ /** Counts, rates and a timeseries over a window (default: last 24h). */
335
+ stats(options?: EmailWindowOptions & {
336
+ buckets?: number;
337
+ }): Promise<EmailStats>;
338
+ /**
339
+ * The per-recipient delivery log, newest first.
340
+ *
341
+ * Includes messages that never reached the provider — unsubscribed, over the
342
+ * daily cap, sender not allowed — which is where most "it didn't send" reports
343
+ * actually land. Nothing is filtered by default, deliberately: defaulting to
344
+ * your app's own mail would make a lookup for a missing sign-in code come back
345
+ * empty.
346
+ */
347
+ messages(options?: EmailListOptions): Promise<{
348
+ messages: EmailMessage[];
349
+ nextCursor: string | null;
350
+ }>;
351
+ /** One message, including bounce diagnostics. */
352
+ message(messageId: string): Promise<EmailMessage>;
353
+ /** One row per blast, newest first, with delivery lifecycle where queued. */
354
+ batches(options?: EmailWindowOptions & {
355
+ limit?: number;
356
+ offset?: number;
357
+ }): Promise<{
358
+ batches: EmailBatch[];
359
+ total: number;
360
+ }>;
361
+ /**
362
+ * Stats and delivery progress for a single blast — the id you passed to
363
+ * `email.send()`, or the one it returned. Poll this to watch a queued send
364
+ * drain (`status`, `pending`, chunk counts).
365
+ */
366
+ batch(batchId: string): Promise<EmailBatch>;
367
+ /** Your app's unsubscribe list, newest first. */
368
+ suppressions(options?: {
369
+ cursor?: string;
370
+ /** Ignored when `cursor` is set. */
371
+ offset?: number;
372
+ limit?: number;
373
+ }): Promise<{
374
+ suppressions: EmailSuppression[];
375
+ nextCursor: string | null;
376
+ total: number;
377
+ }>;
378
+ /** Add an address to your app's unsubscribe list. Idempotent. */
379
+ suppress(email: string): Promise<{
380
+ ok: true;
381
+ }>;
382
+ /**
383
+ * Remove an address from your app's unsubscribe list.
384
+ *
385
+ * Check `platformSuppression` on the result before telling anyone mail will now
386
+ * reach them — see {@link PlatformSuppression}.
387
+ */
388
+ unsuppress(email: string): Promise<UnsuppressResult>;
389
+ }
390
+ /**
391
+ * Create an Email namespace bound to a transport.
392
+ *
393
+ * @internal Called by MindStudioAgent; not part of the public API — access
394
+ * `email` via the agent instance or the top-level export.
395
+ */
396
+ export declare function createEmail(call: EmailTransport): Email;