@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.
- package/CHANGELOG.md +14 -0
- package/dist/analytics/index.d.ts +384 -0
- package/dist/auth/index.d.ts +113 -0
- package/dist/browser/index.d.ts +332 -0
- package/dist/cli.js +29 -29
- package/dist/client.d.ts +767 -0
- package/dist/config.d.ts +13 -0
- package/dist/context.d.ts +125 -0
- package/dist/datasources/index.d.ts +52 -0
- package/dist/datasources/source.d.ts +1074 -0
- package/dist/db/aggregate.d.ts +101 -0
- package/dist/db/index.d.ts +280 -0
- package/dist/db/mutation.d.ts +65 -0
- package/dist/db/predicate.d.ts +85 -0
- package/dist/db/query.d.ts +233 -0
- package/dist/db/raw.d.ts +36 -0
- package/dist/db/readBatching.d.ts +36 -0
- package/dist/db/scanHints.d.ts +8 -0
- package/dist/db/sql.d.ts +136 -0
- package/dist/db/table.d.ts +146 -0
- package/dist/db/time.d.ts +17 -0
- package/dist/db/types.d.ts +237 -0
- package/dist/db-ws.d.ts +35 -0
- package/dist/email/index.d.ts +396 -0
- package/dist/errors.d.ts +34 -0
- package/dist/events/index.d.ts +127 -0
- package/dist/files/index.d.ts +62 -0
- package/dist/files/store.d.ts +244 -0
- package/dist/generated/metadata.d.ts +8 -0
- package/dist/generated/snippets.d.ts +8 -0
- package/dist/generated/steps.d.ts +2745 -0
- package/dist/generated/types.d.ts +4234 -0
- package/dist/http.d.ts +22 -0
- package/dist/index.d.ts +59 -13329
- package/dist/index.js +17 -17
- package/dist/index.js.map +7 -1
- package/dist/jewel/index.d.ts +325 -0
- package/dist/mapper/index.d.ts +229 -0
- package/dist/rate-limit.d.ts +25 -0
- package/dist/reader/index.d.ts +170 -0
- package/dist/respond.d.ts +68 -0
- package/dist/task/index.d.ts +18 -0
- package/dist/task/local.d.ts +48 -0
- package/dist/task/schema.d.ts +120 -0
- package/dist/task/types.d.ts +203 -0
- package/dist/types.d.ts +591 -0
- package/dist/voice/index.d.ts +87 -0
- package/llms.txt +2 -2
- package/package.json +6 -12
- 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
|
+
}
|
package/dist/db-ws.d.ts
ADDED
|
@@ -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;
|