@macro-inc/sdk 0.4.1 → 0.5.0

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 (185) hide show
  1. package/README.md +169 -7
  2. package/dist/{chunk-PTX2RV2N.js → chunk-3SW6QVDV.js} +33 -0
  3. package/dist/{chunk-XFA7NCJ5.js → chunk-GT5EUYOR.js} +13 -15
  4. package/dist/{chunk-ZLBDES7U.js → chunk-HIW6KU2I.js} +490 -4
  5. package/dist/{chunk-AZJUIUIV.js → chunk-J2VK3NOR.js} +56 -0
  6. package/dist/{chunk-PZPTJI6F.js → chunk-UVJLWLSJ.js} +41 -2
  7. package/dist/generated/agent-fold/index.d.ts +8 -6
  8. package/dist/generated/agent-harness/index.d.ts +1 -1
  9. package/dist/generated/agent-harness/index.js +1 -1
  10. package/dist/generated/agent-harness/sdk.gen.d.ts +17 -1
  11. package/dist/generated/agent-harness/types.gen.d.ts +188 -3
  12. package/dist/generated/auth/index.js +1 -1
  13. package/dist/generated/auth/sdk.gen.d.ts +13 -15
  14. package/dist/generated/auth/types.gen.d.ts +36 -17
  15. package/dist/generated/cognition/index.d.ts +1 -1
  16. package/dist/generated/cognition/index.js +1 -1
  17. package/dist/generated/cognition/sdk.gen.d.ts +38 -1
  18. package/dist/generated/cognition/types.gen.d.ts +473 -4
  19. package/dist/generated/connection/types.gen.d.ts +1 -1
  20. package/dist/generated/notification/index.d.ts +1 -1
  21. package/dist/generated/notification/types.gen.d.ts +36 -1
  22. package/dist/generated/scheduled-action/index.d.ts +1 -1
  23. package/dist/generated/scheduled-action/index.js +1 -1
  24. package/dist/generated/scheduled-action/sdk.gen.d.ts +17 -2
  25. package/dist/generated/scheduled-action/types.gen.d.ts +642 -104
  26. package/dist/generated/storage/index.d.ts +1 -1
  27. package/dist/generated/storage/index.js +1 -1
  28. package/dist/generated/storage/sdk.gen.d.ts +204 -5
  29. package/dist/generated/storage/types.gen.d.ts +3969 -374
  30. package/dist/src/entities/account-managers/grant.d.ts +28 -5
  31. package/dist/src/entities/account-managers/namespace.d.ts +15 -3
  32. package/dist/src/entities/activity/entity.d.ts +7 -0
  33. package/dist/src/entities/activity/namespace.d.ts +58 -0
  34. package/dist/src/entities/activity/namespace.test.d.ts +1 -0
  35. package/dist/src/entities/agent-sessions/activity.d.ts +10 -2
  36. package/dist/src/entities/agent-sessions/agent-session.d.ts +193 -18
  37. package/dist/src/entities/agent-sessions/code-execution.d.ts +15 -3
  38. package/dist/src/entities/agent-sessions/conversation.d.ts +46 -9
  39. package/dist/src/entities/agent-sessions/namespace.d.ts +71 -16
  40. package/dist/src/entities/agent-sessions/origin.d.ts +1 -1
  41. package/dist/src/entities/agent-sessions/queued-action.d.ts +17 -3
  42. package/dist/src/entities/agent-sessions/review.d.ts +55 -4
  43. package/dist/src/entities/agent-sessions/tool-approval.d.ts +5 -1
  44. package/dist/src/entities/agents/agent.d.ts +98 -3
  45. package/dist/src/entities/agents/namespace.d.ts +52 -8
  46. package/dist/src/entities/ai/namespace.d.ts +9 -1
  47. package/dist/src/entities/api-keys/api-key.d.ts +6 -1
  48. package/dist/src/entities/api-keys/namespace.d.ts +15 -3
  49. package/dist/src/entities/bots/bot.d.ts +38 -6
  50. package/dist/src/entities/bots/namespace.d.ts +13 -1
  51. package/dist/src/entities/bots/token.d.ts +6 -1
  52. package/dist/src/entities/calendar/booking-link.d.ts +7 -1
  53. package/dist/src/entities/calendar/booking-namespace.d.ts +13 -0
  54. package/dist/src/entities/calendar/booking.d.ts +15 -0
  55. package/dist/src/entities/calendar/calendar.d.ts +7 -1
  56. package/dist/src/entities/calendar/event.d.ts +59 -9
  57. package/dist/src/entities/calendar/namespace.d.ts +88 -10
  58. package/dist/src/entities/calendar/replacement.d.ts +19 -3
  59. package/dist/src/entities/calls/call-record.d.ts +90 -14
  60. package/dist/src/entities/calls/connection.d.ts +7 -1
  61. package/dist/src/entities/calls/message.d.ts +27 -5
  62. package/dist/src/entities/calls/namespace.d.ts +15 -3
  63. package/dist/src/entities/canvases/canvas.d.ts +324 -0
  64. package/dist/src/entities/channels/access-request.d.ts +10 -2
  65. package/dist/src/entities/channels/activity.d.ts +20 -4
  66. package/dist/src/entities/channels/channel.d.ts +130 -23
  67. package/dist/src/entities/channels/labels.d.ts +41 -7
  68. package/dist/src/entities/channels/message.d.ts +41 -7
  69. package/dist/src/entities/channels/namespace.d.ts +28 -3
  70. package/dist/src/entities/channels/post.test.d.ts +1 -0
  71. package/dist/src/entities/channels/thread.d.ts +19 -3
  72. package/dist/src/entities/chats/chat.d.ts +56 -6
  73. package/dist/src/entities/chats/generation.d.ts +11 -2
  74. package/dist/src/entities/chats/namespace.d.ts +10 -2
  75. package/dist/src/entities/connected-apps/connected-app.d.ts +14 -1
  76. package/dist/src/entities/connected-apps/connector.d.ts +3 -0
  77. package/dist/src/entities/connected-apps/namespace.d.ts +16 -0
  78. package/dist/src/entities/crm/company.d.ts +63 -15
  79. package/dist/src/entities/crm/contact.d.ts +60 -13
  80. package/dist/src/entities/crm/namespace.d.ts +85 -11
  81. package/dist/src/entities/crm/pipeline-entry.d.ts +102 -0
  82. package/dist/src/entities/crm/pipeline.d.ts +271 -27
  83. package/dist/src/entities/crm/pipelines.d.ts +39 -2
  84. package/dist/src/entities/databases/column.d.ts +54 -7
  85. package/dist/src/entities/databases/database.d.ts +126 -12
  86. package/dist/src/entities/databases/namespace.d.ts +16 -4
  87. package/dist/src/entities/databases/row.d.ts +2 -0
  88. package/dist/src/entities/databases/saved-query.d.ts +145 -0
  89. package/dist/src/entities/databases/table.d.ts +64 -10
  90. package/dist/src/entities/databases/view.d.ts +27 -5
  91. package/dist/src/entities/databases/webhook.d.ts +8 -1
  92. package/dist/src/entities/documents/ai-edit.d.ts +2 -0
  93. package/dist/src/entities/documents/anchor.d.ts +12 -2
  94. package/dist/src/entities/documents/comment.d.ts +29 -5
  95. package/dist/src/entities/documents/document.d.ts +243 -20
  96. package/dist/src/entities/documents/markdown.d.ts +25 -0
  97. package/dist/src/entities/documents/namespace.d.ts +132 -13
  98. package/dist/src/entities/documents/skills.test.d.ts +1 -0
  99. package/dist/src/entities/documents/system-skill.d.ts +21 -1
  100. package/dist/src/entities/documents/text-comment.d.ts +41 -0
  101. package/dist/src/entities/documents/text-comment.test.d.ts +1 -0
  102. package/dist/src/entities/documents/version.d.ts +5 -1
  103. package/dist/src/entities/email/attachment.d.ts +3 -0
  104. package/dist/src/entities/email/draft.d.ts +61 -9
  105. package/dist/src/entities/email/filter.d.ts +12 -2
  106. package/dist/src/entities/email/label.d.ts +7 -1
  107. package/dist/src/entities/email/link.d.ts +5 -1
  108. package/dist/src/entities/email/message.d.ts +55 -8
  109. package/dist/src/entities/email/namespace.d.ts +127 -21
  110. package/dist/src/entities/email/thread.d.ts +99 -16
  111. package/dist/src/entities/entity-mentions/mention.d.ts +6 -1
  112. package/dist/src/entities/entity-mentions/namespace.d.ts +5 -1
  113. package/dist/src/entities/entity.d.ts +56 -6
  114. package/dist/src/entities/external-chat/chat.d.ts +62 -11
  115. package/dist/src/entities/external-chat/message.d.ts +1 -1
  116. package/dist/src/entities/external-chat/namespace.d.ts +5 -1
  117. package/dist/src/entities/external-chat/send.d.ts +10 -2
  118. package/dist/src/entities/favorites/namespace.d.ts +20 -3
  119. package/dist/src/entities/foreign/foreign-entity.d.ts +5 -1
  120. package/dist/src/entities/foreign/namespace.d.ts +4 -0
  121. package/dist/src/entities/forms/form.d.ts +71 -13
  122. package/dist/src/entities/forms/namespace.d.ts +10 -2
  123. package/dist/src/entities/forms/question.d.ts +35 -7
  124. package/dist/src/entities/forms/response.d.ts +25 -5
  125. package/dist/src/entities/forms/section.d.ts +15 -3
  126. package/dist/src/entities/github-pull-requests/namespace.d.ts +5 -1
  127. package/dist/src/entities/github-pull-requests/pull-request.d.ts +15 -3
  128. package/dist/src/entities/harnesses/harness.d.ts +51 -3
  129. package/dist/src/entities/harnesses/namespace.d.ts +53 -7
  130. package/dist/src/entities/harnesses/pairing.d.ts +12 -2
  131. package/dist/src/entities/images/image.d.ts +16 -5
  132. package/dist/src/entities/images/namespace.d.ts +8 -1
  133. package/dist/src/entities/initiatives/initiative.d.ts +117 -3
  134. package/dist/src/entities/initiatives/initiative.test.d.ts +1 -0
  135. package/dist/src/entities/initiatives/namespace.d.ts +69 -7
  136. package/dist/src/entities/me/namespace.d.ts +27 -2
  137. package/dist/src/entities/meetings/meeting.d.ts +45 -8
  138. package/dist/src/entities/meetings/namespace.d.ts +20 -4
  139. package/dist/src/entities/memory/namespace.d.ts +49 -0
  140. package/dist/src/entities/memory/namespace.test.d.ts +1 -0
  141. package/dist/src/entities/messages/discussion.d.ts +84 -0
  142. package/dist/src/entities/messages/thread.d.ts +19 -5
  143. package/dist/src/entities/notifications/namespace.d.ts +40 -7
  144. package/dist/src/entities/notifications/notification.d.ts +29 -5
  145. package/dist/src/entities/pins/namespace.d.ts +23 -4
  146. package/dist/src/entities/projects/namespace.d.ts +29 -0
  147. package/dist/src/entities/projects/project.d.ts +47 -6
  148. package/dist/src/entities/properties/namespace.d.ts +67 -11
  149. package/dist/src/entities/properties/namespace.test.d.ts +1 -0
  150. package/dist/src/entities/properties/property-definition.d.ts +30 -5
  151. package/dist/src/entities/properties/property-option.d.ts +14 -2
  152. package/dist/src/entities/referrals/namespace.d.ts +8 -1
  153. package/dist/src/entities/routines/namespace.d.ts +128 -7
  154. package/dist/src/entities/routines/routine.d.ts +111 -25
  155. package/dist/src/entities/saved-views/namespace.d.ts +57 -0
  156. package/dist/src/entities/saved-views/saved-view.d.ts +78 -0
  157. package/dist/src/entities/search/namespace.d.ts +5 -1
  158. package/dist/src/entities/sharing/access.d.ts +50 -9
  159. package/dist/src/entities/spreadsheets/spreadsheet.d.ts +201 -0
  160. package/dist/src/entities/tasks/namespace.d.ts +13 -1
  161. package/dist/src/entities/tasks/task.d.ts +7 -1
  162. package/dist/src/entities/teams/invite.d.ts +3 -0
  163. package/dist/src/entities/teams/namespace.d.ts +10 -2
  164. package/dist/src/entities/teams/team.d.ts +7 -0
  165. package/dist/src/entities/unfurls/namespace.d.ts +12 -2
  166. package/dist/src/entities/users/namespace.d.ts +19 -1
  167. package/dist/src/entities/users/profile-picture.d.ts +29 -0
  168. package/dist/src/entities/users/profile-picture.test.d.ts +1 -0
  169. package/dist/src/entities/users/user.d.ts +52 -1
  170. package/dist/src/entities/web/namespace.d.ts +6 -0
  171. package/dist/src/entities/webhooks/namespace.d.ts +5 -0
  172. package/dist/src/entities/webhooks/webhook.d.ts +47 -7
  173. package/dist/src/entities/whatsapp/account.d.ts +5 -1
  174. package/dist/src/entities/whatsapp/chat.d.ts +9 -1
  175. package/dist/src/entities/whatsapp/namespace.d.ts +7 -1
  176. package/dist/src/entities/workspace/namespace.d.ts +7 -1
  177. package/dist/src/entities/workspace/query.d.ts +5 -1
  178. package/dist/src/events/hydrate/user.d.ts +14 -0
  179. package/dist/src/events/receiver.d.ts +2 -0
  180. package/dist/src/events/types.d.ts +2 -1
  181. package/dist/src/macro.d.ts +33 -5
  182. package/dist/src/macro.js +15635 -10132
  183. package/dist/src/utils/lazy.d.ts +7 -1
  184. package/package.json +1 -1
  185. package/dist/src/entities/crm/comment.d.ts +0 -64
@@ -8,6 +8,7 @@ import { User } from '../users/user';
8
8
  import { DatabaseColumn } from './column';
9
9
  import { type DatabaseQueryOptions, type DatabaseQueryResult } from './query';
10
10
  import type { DatabaseRow } from './row';
11
+ import { SavedQuery, type SaveQueryOptions } from './saved-query';
11
12
  import { DatabaseTable } from './table';
12
13
  import type { DatabaseView } from './view';
13
14
  import { DatabaseWebhook } from './webhook';
@@ -118,11 +119,17 @@ export declare class MacroOpRefusedError extends MacroApiError {
118
119
  * loads lazily on first field access and is dropped after any mutation.
119
120
  */
120
121
  export declare class Database extends MacroEntity<DatabaseDetail> {
122
+ /** How entity-addressed APIs identify this entity's type. */
123
+ readonly entityType = "database";
121
124
  /** Access requests and direct user grants. */
122
125
  readonly access: EntityAccess;
123
126
  protected fetch(): Promise<DatabaseDetail>;
124
127
  private assertOwns;
125
- /** The database's URL in the Macro web app; hand it to users as the link. */
128
+ /**
129
+ * The database's URL in the Macro web app; hand it to users as the link.
130
+ *
131
+ * @readonly
132
+ */
126
133
  webUrl(): string;
127
134
  /** Identity, loaded detail and {@link webUrl}, so serialized handles carry their link. */
128
135
  toJSON(): {
@@ -140,6 +147,8 @@ export declare class Database extends MacroEntity<DatabaseDetail> {
140
147
  * Copy the database into a new one the caller owns, with its tables,
141
148
  * columns, views and rows. Its sharing, forms, webhooks and history stay
142
149
  * with this one. Viewing it is enough.
150
+ *
151
+ * @write
143
152
  */
144
153
  duplicate(options?: {
145
154
  /** The copy's name; by default, "<name> copy". */
@@ -147,13 +156,39 @@ export declare class Database extends MacroEntity<DatabaseDetail> {
147
156
  }): Promise<Database>;
148
157
  /** The databases the caller can see, each with the caller's access level. */
149
158
  static list(client: MacroClient): Promise<Database[]>;
150
- /** Run one SQL statement with this database as the default name scope. */
159
+ /**
160
+ * Run one SQL statement with this database as the default name scope.
161
+ *
162
+ * @destructive
163
+ */
151
164
  query(sql: string, options?: Omit<DatabaseQueryOptions, 'database'>): Promise<DatabaseQueryResult>;
152
- /** @internal Drop the schema snapshot after a successful SQL write. */
165
+ /**
166
+ * Save a `SELECT` as a live question and get its answer's block. Answer
167
+ * a question about the data, or a request for a chart, with this: run the
168
+ * SQL with {@link query} first, then save exactly that SQL. The server
169
+ * refuses anything but one `SELECT` that compiles here, and chart columns
170
+ * the `SELECT` does not return. Put {@link SavedQuery.toBlock} in a
171
+ * document verbatim; it re-runs for whoever views it, with their
172
+ * permissions. Pass `table` when the question is about one table.
173
+ *
174
+ * @write
175
+ */
176
+ saveQuery(options: SaveQueryOptions & {
177
+ /** The table the question is about. */
178
+ table?: DatabaseTable;
179
+ }): Promise<SavedQuery>;
180
+ /**
181
+ * @internal Drop the schema snapshot after a successful SQL write.
182
+ *
183
+ * @readonly
184
+ * @mcp-exclude Internal cache control with no server effect.
185
+ */
153
186
  invalidateSchema(): void;
154
187
  /**
155
188
  * The full schema: the database record, the caller's access, and every
156
189
  * table with its columns and views. Cached until the next write.
190
+ *
191
+ * @readonly
157
192
  */
158
193
  schema(): Promise<DatabaseDetail>;
159
194
  /** The database's display name. */
@@ -168,9 +203,17 @@ export declare class Database extends MacroEntity<DatabaseDetail> {
168
203
  readonly grant: () => Promise<import("../../../generated/storage").AccessLevel>;
169
204
  /** The database's tables, in tab order. */
170
205
  readonly tables: () => Promise<DatabaseTable[]>;
171
- /** The table with the given display name, or `undefined` if there is none. */
206
+ /**
207
+ * The table with the given display name, or `undefined` if there is none.
208
+ *
209
+ * @readonly
210
+ */
172
211
  table(name: string): Promise<DatabaseTable | undefined>;
173
- /** Create a table in the database, under an id minted here. */
212
+ /**
213
+ * Create a table in the database, under an id minted here.
214
+ *
215
+ * @write
216
+ */
174
217
  createTable(options: {
175
218
  name: string;
176
219
  }): Promise<DatabaseTable>;
@@ -183,63 +226,110 @@ export declare class Database extends MacroEntity<DatabaseDetail> {
183
226
  * mints, as a UUIDv7) can be named by the next. A refused op leaves the
184
227
  * whole batch unwritten and throws {@link MacroOpRefusedError}. Returns one
185
228
  * result per op, in the order sent.
229
+ *
230
+ * @destructive
186
231
  */
187
232
  applyOps(ops: DatabaseOp[], options?: ApplyOpsOptions): Promise<OpResult[]>;
188
233
  /**
189
234
  * Persist a new tab order. Pass every table of the database exactly once.
190
235
  * Returns the tables in their new order.
236
+ *
237
+ * @write
238
+ * @idempotent
191
239
  */
192
240
  reorderTables(tables: DatabaseTable[]): Promise<DatabaseTable[]>;
193
241
  /**
194
242
  * Delete one of the database's tables with its columns, rows, and views.
195
243
  * A database keeps at least one table, and a table another table's
196
244
  * relation column points at cannot be deleted.
245
+ *
246
+ * @destructive
247
+ * @idempotent
197
248
  */
198
249
  deleteTable(table: DatabaseTable): Promise<void>;
199
250
  /**
200
251
  * What changing a column to each type would do to its values. Changes
201
252
  * nothing.
253
+ *
254
+ * @readonly
202
255
  */
203
256
  columnCasts(column: DatabaseColumn): Promise<ColumnCast[]>;
204
- /** Where a board view's cards sit: each placed card's lane and key. */
257
+ /**
258
+ * Where a board view's cards sit: each placed card's lane and key.
259
+ *
260
+ * @readonly
261
+ */
205
262
  viewPositions(view: DatabaseView): Promise<CardPosition[]>;
206
263
  /**
207
264
  * A row's history: every committed change that touched it, newest first.
208
265
  * See {@link DatabaseRow.history}.
266
+ *
267
+ * @readonly
209
268
  */
210
269
  rowHistory(row: DatabaseRow): Promise<RowHistoryEntry[]>;
211
- /** Import text rows atomically. Keep requestId unchanged when retrying. */
270
+ /**
271
+ * Import text rows atomically. Keep requestId unchanged when retrying.
272
+ *
273
+ * @write
274
+ * @idempotent
275
+ */
212
276
  importTable(request: ImportTable): Promise<DatabaseTable>;
213
277
  private webhookOf;
214
- /** The database's webhooks, oldest first. Takes edit access. */
278
+ /**
279
+ * The database's webhooks, oldest first. Takes edit access.
280
+ *
281
+ * @readonly
282
+ */
215
283
  webhooks(): Promise<DatabaseWebhook[]>;
216
284
  /**
217
285
  * Create a webhook that inserts rows into `table`, writing with the
218
286
  * caller's access. POST a JSON object (one row) or an array of objects to
219
287
  * `/databases/webhooks/{token}` on the storage service; keys name columns.
220
288
  * The token is the whole credential and is answered only here.
289
+ *
290
+ * @write
221
291
  */
222
292
  createWebhook(table: DatabaseTable): Promise<{
223
293
  webhook: DatabaseWebhook;
224
294
  token: string;
225
295
  }>;
226
- /** Delete one of the database's webhooks; its URL stops working. */
296
+ /**
297
+ * Delete one of the database's webhooks; its URL stops working.
298
+ *
299
+ * @destructive
300
+ * @idempotent
301
+ * @mcp-exclude Takes a handle built from a listing record, which an MCP call can't reference.
302
+ */
227
303
  deleteWebhook(webhook: DatabaseWebhook): Promise<void>;
228
- /** Read direct recipients. Only the database owner can manage sharing. */
304
+ /**
305
+ * Read direct recipients. Only the database owner can manage sharing.
306
+ *
307
+ * @readonly
308
+ */
229
309
  sharePermissions(): Promise<SharePermissionV2>;
230
- /** Add, replace, or remove recipient grants without transferring ownership. */
310
+ /**
311
+ * Add, replace, or remove recipient grants without transferring ownership.
312
+ *
313
+ * @write
314
+ * @idempotent
315
+ */
231
316
  updateSharePermissions(request: UpdateSharePermissionRequestV2): Promise<SharePermissionV2>;
232
317
  /**
233
318
  * Change a column's type at the table version last read. Every value must
234
319
  * convert: one that does not refuses the change, naming how many and a few
235
320
  * of them, and nothing is written. To keep the original column, see
236
321
  * {@link Database.convertColumnIntoNewColumn}.
322
+ *
323
+ * @write
324
+ * @idempotent
237
325
  */
238
326
  changeColumnType(column: DatabaseColumn, options: ChangeColumnTypeOptions): Promise<OpResultOf<'column', 'type_changed'>>;
239
327
  /**
240
328
  * What a column's values become under another type: the values that
241
329
  * convert, the option labels a new select or tag column of that type needs,
242
330
  * and how many values do not convert. Changes nothing.
331
+ *
332
+ * @readonly
243
333
  */
244
334
  columnConversion(column: DatabaseColumn, to: ColumnType): Promise<ColumnConversion>;
245
335
  /**
@@ -247,35 +337,56 @@ export declare class Database extends MacroEntity<DatabaseDetail> {
247
337
  * values that convert, in one batch at the table version the conversion
248
338
  * was read at. The original column is left as it is; values that do not
249
339
  * convert stay only there.
340
+ *
341
+ * @write
250
342
  */
251
343
  convertColumnIntoNewColumn(column: DatabaseColumn, options: ConvertIntoNewColumnOptions): Promise<DatabaseColumn>;
252
344
  /**
253
345
  * Remove a column and its cells at the table version last read. Returns
254
346
  * the table's new version.
347
+ *
348
+ * @destructive
349
+ * @idempotent
255
350
  */
256
351
  deleteColumn(column: DatabaseColumn): Promise<TableVersion>;
257
352
  /**
258
353
  * Persist a complete column order at the table version last read. Pass
259
354
  * every column of the table exactly once.
260
355
  * Returns the table's new version.
356
+ *
357
+ * @write
358
+ * @idempotent
261
359
  */
262
360
  reorderColumns(table: DatabaseTable, columns: DatabaseColumn[]): Promise<TableVersion>;
263
361
  /**
264
362
  * Rename a table only if its last-read name is still current. Returns the
265
363
  * table's new version.
364
+ *
365
+ * @write
366
+ * @idempotent
266
367
  */
267
368
  renameTable(table: DatabaseTable, name: string): Promise<TableVersion>;
268
369
  /**
269
370
  * Rename this column placement, only if its last-read name is still
270
371
  * current, without changing its shared property definition. Returns the
271
372
  * table's new version.
373
+ *
374
+ * @write
375
+ * @idempotent
272
376
  */
273
377
  renameColumn(column: DatabaseColumn, name: string): Promise<TableVersion>;
274
- /** Adopt a first-value type only while the owned column is empty and inferable. */
378
+ /**
379
+ * Adopt a first-value type only while the owned column is empty and inferable.
380
+ *
381
+ * @write
382
+ * @idempotent
383
+ */
275
384
  inferColumnType(column: DatabaseColumn, options: InferColumnTypeOptions): Promise<InferColumnTypeOutcome>;
276
385
  /**
277
386
  * Add a column to one of the database's tables, under an id minted here,
278
387
  * either creating a property definition for it or binding an existing one.
388
+ *
389
+ * @write
279
390
  */
280
391
  addColumn(table: DatabaseTable, options: AddColumnOptions): Promise<DatabaseColumn>;
281
392
  /**
@@ -283,6 +394,9 @@ export declare class Database extends MacroEntity<DatabaseDetail> {
283
394
  * minted here. Labels the column already has are skipped, so the call is
284
395
  * safe to repeat; the result lists the options it did create. Only select
285
396
  * and tag columns accept options.
397
+ *
398
+ * @write
399
+ * @idempotent
286
400
  */
287
401
  addColumnOptions(column: DatabaseColumn, labels: string[]): Promise<OpResultOf<'column', 'options_added'>>;
288
402
  }
@@ -59,19 +59,31 @@ import { type DatabaseQueryOptions, type DatabaseQueryResult } from './query';
59
59
  *
60
60
  * **Verify.** After a change, read back the affected schema or rows before claiming success. After an ambiguous failure, inspect the current state before retrying a create or insert. Never describe a proposed change as saved.
61
61
  *
62
- * **Answers.** Answer a question about the data, or a request for a chart, with a saved live query block beside a sentence stating the answer, never with a block you wrote or edited yourself. A query result, a saved question, and a document containing its block are different outcomes: say which happened.
62
+ * **Answers.** Answer a question about the data, or a request for a chart, with a saved live query block beside a sentence stating the answer, never with a block you wrote or edited yourself: run the `SELECT` with `database.query`, save exactly that SQL with `database.saveQuery`, and put its `toBlock()` in the document. Restyle an answer with `withView`; to ask something else, save a new question. A query result, a saved question, and a document containing its block are different outcomes: say which happened.
63
63
  */
64
64
  export declare class DatabaseNamespace {
65
65
  private readonly client;
66
66
  constructor(client: MacroClient);
67
- /** Run one SQL statement over the caller's visible databases. Writes execute once. */
67
+ /**
68
+ * Run one SQL statement over the caller's visible databases. Writes execute once.
69
+ *
70
+ * @destructive
71
+ */
68
72
  query(sql: string, options?: DatabaseQueryOptions): Promise<DatabaseQueryResult>;
69
73
  /** A handle to a database by id. Details load on first access. */
70
74
  byId(id: string): Database;
71
- /** Create a database owned by the caller. */
75
+ /**
76
+ * Create a database owned by the caller.
77
+ *
78
+ * @write
79
+ */
72
80
  create(options: {
73
81
  name: string;
74
82
  }): Promise<Database>;
75
- /** The databases the caller can see. */
83
+ /**
84
+ * The databases the caller can see.
85
+ *
86
+ * @readonly
87
+ */
76
88
  list(): Promise<Database[]>;
77
89
  }
@@ -18,6 +18,8 @@ export declare class DatabaseRow {
18
18
  * Every committed change that touched the row, newest first: who made it,
19
19
  * when, how, and the values of the columns it touched before and after.
20
20
  * A removed row's history still reads.
21
+ *
22
+ * @readonly
21
23
  */
22
24
  history(): Promise<RowHistoryEntry[]>;
23
25
  toJSON(): {
@@ -0,0 +1,145 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ import type { Database } from './database';
3
+ import type { DatabaseTable } from './table';
4
+ /** Display modes that draw a chart, and so need {@link SavedQueryChart} columns. */
5
+ export declare const SAVED_QUERY_CHART_MODES: readonly ["bar", "line", "area", "scatter", "pie"];
6
+ /** A display mode that draws a chart. */
7
+ export type SavedQueryChartMode = (typeof SAVED_QUERY_CHART_MODES)[number];
8
+ /**
9
+ * How an answer is shown: `scalar` for one number, inline in text; `table`
10
+ * for rows; a chart mode to plot them.
11
+ */
12
+ export type SavedQueryDisplayMode = 'scalar' | 'table' | SavedQueryChartMode;
13
+ /** Most `y` columns one chart plots. */
14
+ export declare const SAVED_QUERY_MAX_SERIES = 5;
15
+ /** Smallest and largest height, in pixels, a block's results viewport takes. */
16
+ export declare const SAVED_QUERY_HEIGHT_RANGE: {
17
+ readonly min: 96;
18
+ readonly max: 1600;
19
+ };
20
+ /** Which result columns a chart plots, named exactly as the `SELECT` returns them. */
21
+ export type SavedQueryChart = {
22
+ /** The label column: the x axis, or the pie's slices. */
23
+ x: string;
24
+ /** One to five numeric result columns to plot, none equal to `x`. */
25
+ y: string[];
26
+ /** Chart heading. */
27
+ title?: string;
28
+ /** A column whose values split the one `y` series into a series per value. */
29
+ color?: string;
30
+ /** Stack bar or area series instead of setting them side by side. */
31
+ stack?: boolean;
32
+ };
33
+ /** How an answer is shown: a chart mode always carries its chart. */
34
+ export type SavedQueryDisplay = {
35
+ mode: 'scalar' | 'table';
36
+ } | {
37
+ mode: SavedQueryChartMode;
38
+ chart: SavedQueryChart;
39
+ };
40
+ /** Options for {@link Database.saveQuery} and {@link DatabaseTable.saveQuery}. */
41
+ export type SaveQueryOptions = {
42
+ /** One `SELECT`, exactly as it ran with `query`. */
43
+ sql: string;
44
+ /** Short heading shown with the answer, e.g. "Invites per party". */
45
+ title: string;
46
+ /** The question in the user's words; by default, the title. */
47
+ prompt?: string;
48
+ /** How the answer is shown. */
49
+ display: SavedQueryDisplay;
50
+ /** Preferred height of the results viewport, in pixels, from 96 to 1600. */
51
+ height?: number;
52
+ };
53
+ /** What {@link SavedQuery.withView} changes; everything else stays. */
54
+ export type SavedQueryView = {
55
+ /** The new display mode. A chart mode needs a chart, given here or already set. */
56
+ displayMode?: SavedQueryDisplayMode;
57
+ /** The new chart columns. */
58
+ chart?: SavedQueryChart;
59
+ /** The new heading. */
60
+ title?: string;
61
+ /** The new viewport height, in pixels, from 96 to 1600. */
62
+ height?: number;
63
+ };
64
+ /**
65
+ * A saved question: an immutable `SELECT` stored on the server, with how its
66
+ * answer is shown. Its block ({@link toBlock}) renders the answer live,
67
+ * re-running the question for whoever views it with their permissions, so it
68
+ * stays current as the data changes. The SQL never leaves the server inside
69
+ * the block; the block names the question by id.
70
+ *
71
+ * Changing the SQL means saving a new question. Changing how the answer
72
+ * looks does not: {@link withView} returns the same question shown another
73
+ * way.
74
+ *
75
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
76
+ */
77
+ export declare class SavedQuery {
78
+ private readonly client;
79
+ /** Identifier of the saved question. */
80
+ readonly id: string;
81
+ /** The database whose tables win name resolution, if one was given. */
82
+ readonly database: Database | undefined;
83
+ /** The table the question is about, when it was saved from one. */
84
+ readonly table: DatabaseTable | undefined;
85
+ private readonly presentation;
86
+ private constructor();
87
+ /**
88
+ * @internal Save a question. The server checks that the SQL is one
89
+ * `SELECT` that compiles against the caller's databases, and that every
90
+ * chart column is one it returns.
91
+ */
92
+ static save(client: MacroClient, scope: {
93
+ database: Database;
94
+ table?: DatabaseTable;
95
+ }, options: SaveQueryOptions): Promise<SavedQuery>;
96
+ /** The heading shown with the answer. */
97
+ get title(): string;
98
+ /** The question in the user's words. */
99
+ get prompt(): string;
100
+ /** How the answer is shown. */
101
+ get displayMode(): SavedQueryDisplayMode;
102
+ /** Which result columns the chart plots, if it has one. */
103
+ get chart(): SavedQueryChart | undefined;
104
+ /** Preferred height of the results viewport, in pixels, if set. */
105
+ get height(): number | undefined;
106
+ /**
107
+ * The saved `SELECT`, read from the server.
108
+ *
109
+ * @readonly
110
+ */
111
+ sql(): Promise<string>;
112
+ /**
113
+ * The same question shown another way: a new display mode, chart, title or
114
+ * height, as a document's block can be restyled in place. The question
115
+ * itself never changes; save a new one to ask something else.
116
+ *
117
+ * A chart mode needs chart columns, given here or already set. A `scalar`
118
+ * answer sits inline in text and every other mode is a block, so a
119
+ * question cannot switch between `scalar` and another mode; save it again
120
+ * with the mode it should have.
121
+ *
122
+ * @readonly
123
+ */
124
+ withView(view: SavedQueryView): SavedQuery;
125
+ /**
126
+ * The block that shows the live answer, to put verbatim in a document's
127
+ * Markdown or quote verbatim in edit instructions. Never write or edit a
128
+ * block by hand: it names the question by id, and the SQL stays on the
129
+ * server.
130
+ *
131
+ * @readonly
132
+ */
133
+ toBlock(): string;
134
+ toJSON(): {
135
+ id: string;
136
+ databaseId: string | undefined;
137
+ tableId: string | undefined;
138
+ title: string;
139
+ prompt: string;
140
+ displayMode: SavedQueryDisplayMode;
141
+ chart: SavedQueryChart | undefined;
142
+ height: number | undefined;
143
+ block: string;
144
+ };
145
+ }
@@ -2,6 +2,7 @@ import type { TableDetail, TableVersion } from '../../../generated/storage/types
2
2
  import { DatabaseColumn } from './column';
3
3
  import type { AddColumnOptions, Database } from './database';
4
4
  import { DatabaseRow } from './row';
5
+ import type { SavedQuery, SaveQueryOptions } from './saved-query';
5
6
  import { DatabaseView } from './view';
6
7
  import type { DatabaseWebhook } from './webhook';
7
8
  /**
@@ -22,37 +23,90 @@ export declare class DatabaseTable {
22
23
  /**
23
24
  * The table's record as the API returns it: the table, its columns, and
24
25
  * its views.
26
+ *
27
+ * @readonly
25
28
  */
26
29
  detail(): Promise<TableDetail>;
27
- /** The table's display name. */
30
+ /**
31
+ * The table's display name.
32
+ *
33
+ * @readonly
34
+ */
28
35
  name(): Promise<string>;
29
- /** Rename only if the last-read display name is still current. */
36
+ /**
37
+ * Rename only if the last-read display name is still current.
38
+ *
39
+ * @write
40
+ * @idempotent
41
+ */
30
42
  rename(name: string): Promise<DatabaseTable>;
31
43
  /**
32
44
  * The table's current version, bumped by every committed change to its
33
45
  * schema or rows. Schema edits such as {@link reorderColumns} send it as
34
46
  * the base version they were made against, so a table that moved since
35
47
  * refuses the edit with a 409.
48
+ *
49
+ * @readonly
36
50
  */
37
51
  version(): Promise<TableVersion>;
38
- /** The table's fractional index within the database's tab order. */
52
+ /**
53
+ * The table's fractional index within the database's tab order.
54
+ *
55
+ * @readonly
56
+ */
39
57
  position(): Promise<string>;
40
- /** The table's columns, in display order. */
58
+ /**
59
+ * The table's columns, in display order.
60
+ *
61
+ * @readonly
62
+ */
41
63
  columns(): Promise<DatabaseColumn[]>;
42
- /** Add a column to this table. See {@link Database.addColumn}. */
64
+ /**
65
+ * Add a column to this table. See {@link Database.addColumn}.
66
+ *
67
+ * @write
68
+ */
43
69
  addColumn(options: AddColumnOptions): Promise<DatabaseColumn>;
44
- /** Persist a new column order. See {@link Database.reorderColumns}. */
70
+ /**
71
+ * Persist a new column order. See {@link Database.reorderColumns}.
72
+ *
73
+ * @write
74
+ * @idempotent
75
+ */
45
76
  reorderColumns(columns: DatabaseColumn[]): Promise<DatabaseTable>;
46
- /** A handle to one of the table's rows, by the id an insert answered. */
77
+ /**
78
+ * A handle to one of the table's rows, by the id an insert answered.
79
+ *
80
+ * @readonly
81
+ */
47
82
  row(id: string): DatabaseRow;
48
- /** The table's views, in their order. */
83
+ /**
84
+ * The table's views, in their order.
85
+ *
86
+ * @readonly
87
+ */
49
88
  views(): Promise<DatabaseView[]>;
50
- /** Create a webhook that inserts rows here. See {@link Database.createWebhook}. */
89
+ /**
90
+ * Create a webhook that inserts rows here. See {@link Database.createWebhook}.
91
+ *
92
+ * @write
93
+ */
51
94
  createWebhook(): Promise<{
52
95
  webhook: DatabaseWebhook;
53
96
  token: string;
54
97
  }>;
55
- /** Delete this table. See {@link Database.deleteTable}. */
98
+ /**
99
+ * Save a `SELECT` about this table as a live question. See {@link Database.saveQuery}.
100
+ *
101
+ * @write
102
+ */
103
+ saveQuery(options: SaveQueryOptions): Promise<SavedQuery>;
104
+ /**
105
+ * Delete this table. See {@link Database.deleteTable}.
106
+ *
107
+ * @destructive
108
+ * @idempotent
109
+ */
56
110
  delete(): Promise<void>;
57
111
  toJSON(): {
58
112
  id: string;
@@ -17,20 +17,42 @@ export declare class DatabaseView {
17
17
  private constructor();
18
18
  /** A handle to a view by id, within a table. Details load on first access. */
19
19
  static byId(table: DatabaseTable, id: string): DatabaseView;
20
- /** The view's record as the API returns it. */
20
+ /**
21
+ * The view's record as the API returns it.
22
+ *
23
+ * @readonly
24
+ */
21
25
  detail(): Promise<DatabaseViewRecord>;
22
- /** The view's name, unique among its table's views ignoring case. */
26
+ /**
27
+ * The view's name, unique among its table's views ignoring case.
28
+ *
29
+ * @readonly
30
+ */
23
31
  name(): Promise<string>;
24
- /** The view's fractional index within its table's views. */
32
+ /**
33
+ * The view's fractional index within its table's views.
34
+ *
35
+ * @readonly
36
+ */
25
37
  position(): Promise<string>;
26
- /** How the view draws its rows: a table, or a board grouped by a column. */
38
+ /**
39
+ * How the view draws its rows: a table, or a board grouped by a column.
40
+ *
41
+ * @readonly
42
+ */
27
43
  layout(): Promise<ViewLayout>;
28
- /** Which rows the view shows, and in what order. */
44
+ /**
45
+ * Which rows the view shows, and in what order.
46
+ *
47
+ * @readonly
48
+ */
29
49
  query(): Promise<ViewQuery>;
30
50
  /**
31
51
  * Where a board's cards sit: each placed card's lane and its key there.
32
52
  * Cards without a place show after the placed ones of their lane, oldest
33
53
  * first.
54
+ *
55
+ * @readonly
34
56
  */
35
57
  positions(): Promise<CardPosition[]>;
36
58
  toJSON(): {
@@ -6,6 +6,8 @@ import type { DatabaseTable } from './table';
6
6
  * can POST JSON to, each object becoming a row, written with the access of
7
7
  * the user who created it. Its token is shown only when it is created; see
8
8
  * {@link Database.createWebhook}.
9
+ *
10
+ * @mcp-exclude Built from a listing record; no id-only reference an MCP call can pass.
9
11
  */
10
12
  export declare class DatabaseWebhook {
11
13
  /** The table its calls insert rows into. */
@@ -22,7 +24,12 @@ export declare class DatabaseWebhook {
22
24
  get tokenPrefix(): string;
23
25
  /** When it was created. */
24
26
  get createdAt(): string;
25
- /** Delete the webhook; its URL stops working. */
27
+ /**
28
+ * Delete the webhook; its URL stops working.
29
+ *
30
+ * @destructive
31
+ * @idempotent
32
+ */
26
33
  delete(): Promise<void>;
27
34
  toJSON(): {
28
35
  id: string;
@@ -50,3 +50,5 @@ export declare class DocumentEditRefusedError extends MacroApiError {
50
50
  }
51
51
  /** Run an instructions edit; `Document.edit` calls this. */
52
52
  export declare function editWithInstructions(client: MacroClient, document: Document, instructions: string, options: DocumentEditOptions): Promise<DocumentEditResult>;
53
+ /** Whether an error body is the editor's refusal. */
54
+ export declare function isRefusal(error: unknown): error is DocumentAiEditRefused;
@@ -22,8 +22,18 @@ export declare class DocumentAnchor extends MacroEntity<AnchorRecord> {
22
22
  readonly kind: () => Promise<"highlight" | "placeable">;
23
23
  /** Page containing the annotation. */
24
24
  readonly page: () => Promise<number>;
25
- /** Edit a placeable comment's position and display settings. */
25
+ /**
26
+ * Edit a placeable comment's position and display settings.
27
+ *
28
+ * @write
29
+ * @idempotent
30
+ */
26
31
  edit(options: Omit<EditPdfPlaceableCommentAnchorRequest, 'uuid'>): Promise<void>;
27
- /** Delete a standalone highlight annotation. */
32
+ /**
33
+ * Delete a standalone highlight annotation.
34
+ *
35
+ * @destructive
36
+ * @idempotent
37
+ */
28
38
  delete(): Promise<void>;
29
39
  }