@macro-inc/sdk 0.0.1 → 0.2.2

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 (165) hide show
  1. package/README.md +628 -21
  2. package/dist/{chunk-5HAKQN23.js → chunk-7LVVPVNT.js} +70 -57
  3. package/dist/{chunk-JXIQT5TH.js → chunk-7YJ6Y7HJ.js} +234 -16
  4. package/dist/chunk-LMJW65ML.js +836 -0
  5. package/dist/{chunk-SGAHIERJ.js → chunk-OGE7WXJE.js} +16 -0
  6. package/dist/chunk-PRUFPW3B.js +943 -0
  7. package/dist/{chunk-CTKR64MY.js → chunk-QVBNNMQS.js} +242 -367
  8. package/dist/{chunk-QNUS5BC5.js → chunk-SUINKDXF.js} +30 -84
  9. package/dist/{chunk-77EI4LSQ.js → chunk-ZQXOHNDB.js} +1518 -386
  10. package/dist/generated/agent-harness/index.d.ts +1 -1
  11. package/dist/generated/agent-harness/index.js +1 -1
  12. package/dist/generated/agent-harness/sdk.gen.d.ts +174 -4
  13. package/dist/generated/agent-harness/types.gen.d.ts +2511 -189
  14. package/dist/generated/auth/index.d.ts +1 -1
  15. package/dist/generated/auth/index.js +1 -1
  16. package/dist/generated/auth/sdk.gen.d.ts +106 -8
  17. package/dist/generated/auth/types.gen.d.ts +1473 -116
  18. package/dist/generated/calendar/client/client.gen.d.ts +2 -0
  19. package/dist/generated/calendar/client/index.d.ts +10 -0
  20. package/dist/generated/calendar/client/types.gen.d.ts +120 -0
  21. package/dist/generated/calendar/client/utils.gen.d.ts +37 -0
  22. package/dist/generated/calendar/client.gen.d.ts +12 -0
  23. package/dist/generated/calendar/core/auth.gen.d.ts +25 -0
  24. package/dist/generated/calendar/core/bodySerializer.gen.d.ts +25 -0
  25. package/dist/generated/calendar/core/params.gen.d.ts +43 -0
  26. package/dist/generated/calendar/core/pathSerializer.gen.d.ts +33 -0
  27. package/dist/generated/calendar/core/queryKeySerializer.gen.d.ts +18 -0
  28. package/dist/generated/calendar/core/serverSentEvents.gen.d.ts +71 -0
  29. package/dist/generated/calendar/core/types.gen.d.ts +83 -0
  30. package/dist/generated/calendar/core/utils.gen.d.ts +19 -0
  31. package/dist/generated/calendar/index.d.ts +2 -0
  32. package/dist/generated/calendar/index.js +6 -0
  33. package/dist/generated/calendar/sdk.gen.d.ts +95 -0
  34. package/dist/generated/calendar/types.gen.d.ts +1091 -0
  35. package/dist/generated/cognition/index.d.ts +1 -1
  36. package/dist/generated/cognition/index.js +1 -1
  37. package/dist/generated/cognition/sdk.gen.d.ts +6 -1
  38. package/dist/generated/cognition/types.gen.d.ts +304 -36
  39. package/dist/generated/connection/types.gen.d.ts +1 -1
  40. package/dist/generated/email/index.d.ts +1 -1
  41. package/dist/generated/email/index.js +1 -1
  42. package/dist/generated/email/sdk.gen.d.ts +32 -27
  43. package/dist/generated/email/types.gen.d.ts +586 -409
  44. package/dist/generated/notification/index.d.ts +1 -1
  45. package/dist/generated/notification/types.gen.d.ts +384 -19
  46. package/dist/generated/properties/types.gen.d.ts +8 -5
  47. package/dist/generated/scheduled-action/index.d.ts +1 -1
  48. package/dist/generated/scheduled-action/index.js +3 -842
  49. package/dist/generated/scheduled-action/sdk.gen.d.ts +3 -1
  50. package/dist/generated/scheduled-action/types.gen.d.ts +277 -41
  51. package/dist/generated/search/index.d.ts +1 -1
  52. package/dist/generated/search/types.gen.d.ts +262 -43
  53. package/dist/generated/storage/index.d.ts +1 -1
  54. package/dist/generated/storage/index.js +1 -1
  55. package/dist/generated/storage/sdk.gen.d.ts +678 -107
  56. package/dist/generated/storage/types.gen.d.ts +14827 -5995
  57. package/dist/generated/unfurl/index.d.ts +1 -1
  58. package/dist/generated/unfurl/index.js +3 -832
  59. package/dist/generated/unfurl/types.gen.d.ts +20 -0
  60. package/dist/src/config.d.ts +33 -13
  61. package/dist/src/entities/agent-sessions/agent-session.d.ts +150 -6
  62. package/dist/src/entities/agent-sessions/code-execution.d.ts +43 -0
  63. package/dist/src/entities/agent-sessions/conversation.d.ts +54 -0
  64. package/dist/src/entities/agent-sessions/namespace.d.ts +23 -5
  65. package/dist/src/entities/agent-sessions/queued-action.d.ts +46 -0
  66. package/dist/src/entities/agent-sessions/review.d.ts +107 -0
  67. package/dist/src/entities/agent-sessions/tool-approval.d.ts +21 -0
  68. package/dist/src/entities/agents/agent.d.ts +47 -0
  69. package/dist/src/entities/agents/namespace.d.ts +13 -0
  70. package/dist/src/entities/ai/namespace.d.ts +24 -0
  71. package/dist/src/entities/api-keys/api-key.d.ts +17 -0
  72. package/dist/src/entities/api-keys/namespace.d.ts +18 -0
  73. package/dist/src/entities/calendar/calendar.d.ts +35 -0
  74. package/dist/src/entities/calendar/event.d.ts +123 -0
  75. package/dist/src/entities/calendar/event.test.d.ts +1 -0
  76. package/dist/src/entities/calendar/namespace.d.ts +111 -0
  77. package/dist/src/entities/calendar/replacement.d.ts +15 -0
  78. package/dist/src/entities/calls/call-record.d.ts +62 -6
  79. package/dist/src/entities/calls/message.d.ts +33 -0
  80. package/dist/src/entities/channels/activity.d.ts +24 -0
  81. package/dist/src/entities/channels/channel.d.ts +44 -3
  82. package/dist/src/entities/channels/labels.d.ts +39 -0
  83. package/dist/src/entities/channels/message.d.ts +9 -17
  84. package/dist/src/entities/channels/namespace.d.ts +6 -0
  85. package/dist/src/entities/channels/picture.d.ts +11 -0
  86. package/dist/src/entities/channels/post.d.ts +1 -1
  87. package/dist/src/entities/channels/thread.d.ts +5 -0
  88. package/dist/src/entities/chats/chat.d.ts +11 -1
  89. package/dist/src/entities/chats/generation.d.ts +46 -0
  90. package/dist/src/entities/crm/comment.d.ts +55 -34
  91. package/dist/src/entities/crm/company.d.ts +42 -10
  92. package/dist/src/entities/crm/contact.d.ts +42 -10
  93. package/dist/src/entities/crm/namespace.d.ts +18 -1
  94. package/dist/src/entities/crm/pipeline.d.ts +122 -0
  95. package/dist/src/entities/crm/pipelines.d.ts +14 -0
  96. package/dist/src/entities/databases/column.d.ts +75 -0
  97. package/dist/src/entities/databases/database.d.ts +272 -0
  98. package/dist/src/entities/databases/namespace.d.ts +21 -0
  99. package/dist/src/entities/databases/query.d.ts +86 -0
  100. package/dist/src/entities/databases/row.d.ts +27 -0
  101. package/dist/src/entities/databases/table.d.ts +61 -0
  102. package/dist/src/entities/databases/view.d.ts +40 -0
  103. package/dist/src/entities/databases/webhook.d.ts +32 -0
  104. package/dist/src/entities/documents/anchor.d.ts +29 -0
  105. package/dist/src/entities/documents/comment.d.ts +25 -22
  106. package/dist/src/entities/documents/document.d.ts +60 -12
  107. package/dist/src/entities/documents/namespace.d.ts +30 -0
  108. package/dist/src/entities/documents/version.d.ts +22 -0
  109. package/dist/src/entities/email/draft.d.ts +79 -0
  110. package/dist/src/entities/email/filter.d.ts +34 -0
  111. package/dist/src/entities/email/link.d.ts +6 -4
  112. package/dist/src/entities/email/message.d.ts +12 -1
  113. package/dist/src/entities/email/namespace.d.ts +34 -1
  114. package/dist/src/entities/email/thread.d.ts +23 -1
  115. package/dist/src/entities/entity-mentions/mention.d.ts +16 -0
  116. package/dist/src/entities/entity-mentions/namespace.d.ts +12 -0
  117. package/dist/src/entities/entity.d.ts +7 -0
  118. package/dist/src/entities/favorites/namespace.d.ts +14 -2
  119. package/dist/src/entities/foreign/foreign-entity.d.ts +2 -0
  120. package/dist/src/entities/foreign/namespace.d.ts +40 -0
  121. package/dist/src/entities/forms/form.d.ts +227 -0
  122. package/dist/src/entities/forms/namespace.d.ts +18 -0
  123. package/dist/src/entities/forms/question.d.ts +37 -0
  124. package/dist/src/entities/forms/response.d.ts +32 -0
  125. package/dist/src/entities/forms/section.d.ts +19 -0
  126. package/dist/src/entities/github-pull-requests/namespace.d.ts +12 -0
  127. package/dist/src/entities/github-pull-requests/pull-request.d.ts +52 -0
  128. package/dist/src/entities/harnesses/harness.d.ts +19 -0
  129. package/dist/src/entities/harnesses/namespace.d.ts +33 -0
  130. package/dist/src/entities/harnesses/pairing.d.ts +39 -0
  131. package/dist/src/entities/initiatives/initiative.d.ts +50 -0
  132. package/dist/src/entities/initiatives/namespace.d.ts +13 -0
  133. package/dist/src/entities/meetings/meeting.d.ts +38 -0
  134. package/dist/src/entities/meetings/namespace.d.ts +18 -0
  135. package/dist/src/entities/messages/thread.d.ts +101 -0
  136. package/dist/src/entities/notifications/notification.d.ts +6 -3
  137. package/dist/src/entities/notifications/notification.test.d.ts +1 -0
  138. package/dist/src/entities/projects/project.d.ts +7 -0
  139. package/dist/src/entities/reference.d.ts +82 -0
  140. package/dist/src/entities/routines/namespace.d.ts +15 -0
  141. package/dist/src/entities/routines/routine.d.ts +115 -0
  142. package/dist/src/entities/sharing/access.d.ts +65 -0
  143. package/dist/src/entities/sharing/permissions.d.ts +13 -0
  144. package/dist/src/entities/tasks/namespace.d.ts +4 -0
  145. package/dist/src/entities/tasks/task.d.ts +6 -0
  146. package/dist/src/entities/unfurls/namespace.d.ts +10 -0
  147. package/dist/src/entities/webhooks/webhook.d.ts +3 -1
  148. package/dist/src/entities/workspace/items.d.ts +7 -0
  149. package/dist/src/entities/workspace/namespace.d.ts +83 -0
  150. package/dist/src/entities/workspace/query.d.ts +12 -0
  151. package/dist/src/entities/workspace/types.d.ts +96 -0
  152. package/dist/src/events/hydrate/agentSession.d.ts +192 -0
  153. package/dist/src/events/hydrate/channel.d.ts +2 -39
  154. package/dist/src/events/hydrate/message.d.ts +70 -0
  155. package/dist/src/events/receiver.d.ts +57 -19
  156. package/dist/src/events/types.d.ts +3 -1
  157. package/dist/src/macro.d.ts +80 -3
  158. package/dist/src/macro.js +8832 -2784
  159. package/dist/src/utils/activity.d.ts +11 -0
  160. package/dist/src/utils/activity.test.d.ts +1 -0
  161. package/dist/src/utils/client.d.ts +10 -1
  162. package/dist/src/utils/concurrency.d.ts +5 -0
  163. package/dist/src/utils/index.d.ts +1 -0
  164. package/dist/src/utils/pagination.d.ts +9 -4
  165. package/package.json +11 -3
@@ -0,0 +1,75 @@
1
+ import type { ColumnCast, ColumnConfig, ColumnDetail, DataType, PropertyDefinitionWithOptions } from '../../../generated/storage/types.gen';
2
+ import type { ChangeColumnTypeOptions, ConvertIntoNewColumnOptions, InferColumnTypeOptions, OpResultOf } from './database';
3
+ import type { DatabaseTable } from './table';
4
+ /**
5
+ * One column of a {@link DatabaseTable}: the placement of a property
6
+ * definition on the table.
7
+ *
8
+ * A column is not an entity of its own — it has no permissions and no
9
+ * endpoint to read it directly. The handle resolves through the owning
10
+ * database's schema, so a fresh read after a write sees the new value.
11
+ */
12
+ export declare class DatabaseColumn {
13
+ /** The table this column belongs to. */
14
+ readonly table: DatabaseTable;
15
+ /** Identifier of the column placement. */
16
+ readonly id: string;
17
+ private constructor();
18
+ /** A handle to a column by id, within a table. Details load on first access. */
19
+ static byId(table: DatabaseTable, id: string): DatabaseColumn;
20
+ /**
21
+ * The column's record as the API returns it: the placement and the bound
22
+ * property definition.
23
+ */
24
+ detail(): Promise<ColumnDetail>;
25
+ /** The placement's display name, falling back to its property definition. */
26
+ name(): Promise<string>;
27
+ /**
28
+ * Rename this placement, only if its last-read name is still current,
29
+ * without changing its shared property definition.
30
+ */
31
+ rename(name: string): Promise<DatabaseColumn>;
32
+ /** Settle the type of an empty column created with inferType enabled. */
33
+ inferType(options: InferColumnTypeOptions): Promise<DatabaseColumn>;
34
+ /** Change this column's type. See {@link Database.changeColumnType}. */
35
+ changeType(options: ChangeColumnTypeOptions): Promise<OpResultOf<'column', 'type_changed'>>;
36
+ /**
37
+ * Add a column of another type right after this one, filled with the
38
+ * values that convert, leaving this one as it is. See
39
+ * {@link Database.convertColumnIntoNewColumn}.
40
+ */
41
+ convertIntoNewColumn(options: ConvertIntoNewColumnOptions): Promise<DatabaseColumn>;
42
+ /**
43
+ * What changing this column to each type would do to its values: `safe`,
44
+ * `checked` (with how many would not convert, and a few of them), or
45
+ * `never` (with why). Changes nothing.
46
+ */
47
+ casts(): Promise<ColumnCast[]>;
48
+ /** Delete this placement and its cells at the table version last read. */
49
+ delete(): Promise<void>;
50
+ /** The value type the column holds. */
51
+ dataType(): Promise<DataType>;
52
+ /** Whether the column holds multiple values. */
53
+ isMultiSelect(): Promise<boolean>;
54
+ /** The column's fractional index within the table's column order. */
55
+ position(): Promise<string>;
56
+ /**
57
+ * The bound property definition together with its select options — the
58
+ * source of the column's name, type, and allowed values.
59
+ */
60
+ definition(): Promise<PropertyDefinitionWithOptions>;
61
+ /**
62
+ * Column-kind configuration (a link), or `undefined` for a plain
63
+ * value column.
64
+ */
65
+ config(): Promise<ColumnConfig | undefined>;
66
+ /**
67
+ * Add select options to the column. Labels it already has are skipped, so
68
+ * the call is safe to repeat. Only select and tag columns accept options.
69
+ */
70
+ addOptions(labels: string[]): Promise<DatabaseColumn>;
71
+ toJSON(): {
72
+ id: string;
73
+ tableId: string;
74
+ };
75
+ }
@@ -0,0 +1,272 @@
1
+ import type { CardPosition, ColumnCast, ColumnConversion, ColumnKind, DatabaseDetail, DatabaseOp, ImportTable, InferColumnTypeOutcome, InferColumnTypeRequest, OpRefusalResponse, OpResult, RowHistoryEntry, SharePermissionV2, TableVersion, TakenId, UpdateSharePermissionRequestV2 } from '../../../generated/storage/types.gen';
2
+ import { MacroApiError } from '../../utils';
3
+ import type { MacroClient } from '../../utils/client';
4
+ import { MacroEntity } from '../entity';
5
+ import type { PropertyDefinition } from '../properties/property-definition';
6
+ import { EntityAccess } from '../sharing/access';
7
+ import { User } from '../users/user';
8
+ import { DatabaseColumn } from './column';
9
+ import { type DatabaseQueryOptions, type DatabaseQueryResult } from './query';
10
+ import type { DatabaseRow } from './row';
11
+ import { DatabaseTable } from './table';
12
+ import type { DatabaseView } from './view';
13
+ import { DatabaseWebhook } from './webhook';
14
+ /** A result naming what happened to its resource: every kind but a reorder of the database's tables. */
15
+ type ChangedResult = Extract<OpResult, {
16
+ change: unknown;
17
+ }>;
18
+ /** What a result of each op kind can say happened. */
19
+ type ResultChanges = {
20
+ [Kind in ChangedResult['kind']]: Extract<ChangedResult, {
21
+ kind: Kind;
22
+ }>['change']['kind'];
23
+ };
24
+ /** The result of a `Kind` op whose change answered `Change`. */
25
+ export type OpResultOf<Kind extends keyof ResultChanges, Change extends ResultChanges[Kind]> = Extract<ChangedResult, {
26
+ kind: Kind;
27
+ }> & {
28
+ change: Extract<Extract<ChangedResult, {
29
+ kind: Kind;
30
+ }>['change'], {
31
+ kind: Change;
32
+ }>;
33
+ };
34
+ /**
35
+ * A type a column can have. A relation names the related table by handle;
36
+ * the table may live in any database the caller can reach.
37
+ */
38
+ export type ColumnType = Exclude<ColumnKind, {
39
+ type: 'relation';
40
+ }> | {
41
+ type: 'relation';
42
+ table: DatabaseTable;
43
+ };
44
+ /** Options for {@link Database.addColumn}. */
45
+ export type AddColumnOptions = ({
46
+ /** Display name of the column, unique within the table ignoring case. */
47
+ name: string;
48
+ /** What the column holds. */
49
+ type: ColumnType;
50
+ /**
51
+ * For a select or tag column, the labels it starts with. Without any it
52
+ * accepts nothing until {@link DatabaseColumn.addOptions} adds some.
53
+ */
54
+ options?: string[];
55
+ /** Let a plain, empty text column settle its type from its first value. */
56
+ inferType?: boolean;
57
+ } | {
58
+ /** An existing property definition to bind the column to. */
59
+ property: PropertyDefinition;
60
+ }) & {
61
+ /** The column the new one goes right after; by default, the last one. */
62
+ after?: DatabaseColumn;
63
+ };
64
+ /** Options for {@link Database.changeColumnType}. */
65
+ export type ChangeColumnTypeOptions = {
66
+ /** The type to change the column to. */
67
+ to: ColumnType;
68
+ };
69
+ /** Options for {@link Database.convertColumnIntoNewColumn}. */
70
+ export type ConvertIntoNewColumnOptions = {
71
+ /** The type of the new column. */
72
+ to: ColumnType;
73
+ /**
74
+ * Display name of the new column; by default the original's name followed
75
+ * by the type, as in `Due (Date)`.
76
+ */
77
+ name?: string;
78
+ };
79
+ /** Options for {@link Database.applyOps}. */
80
+ export type ApplyOpsOptions = {
81
+ /**
82
+ * The version each table must still be at, as the caller read it. A table
83
+ * that moved refuses the whole batch with a 409, so an edit made against
84
+ * what the caller saw does not overwrite another's.
85
+ */
86
+ baseVersions?: {
87
+ table: DatabaseTable;
88
+ version: TableVersion;
89
+ }[];
90
+ };
91
+ /** Settle an empty inferred column using the table version the caller read. */
92
+ export type InferColumnTypeOptions = {
93
+ dataType: 'STRING' | 'NUMBER' | 'ENTITY';
94
+ specificEntityType?: InferColumnTypeRequest['specificEntityType'];
95
+ baseVersion: TableVersion;
96
+ };
97
+ /**
98
+ * A batch of ops was refused (HTTP 400): nothing in it was written. Names the
99
+ * op at fault and, when the batch minted an id that already names something
100
+ * (a retry of a batch that committed, or an id minted twice), that id.
101
+ */
102
+ export declare class MacroOpRefusedError extends MacroApiError {
103
+ /** The refused op's index in the batch. */
104
+ readonly op: number;
105
+ /** The row's index within the op, when one row is at fault. */
106
+ readonly row: number | null;
107
+ /** The column placement at fault, when one is. */
108
+ readonly column: string | null;
109
+ /** The minted id that is already taken, when that is the reason. */
110
+ readonly taken: TakenId | null;
111
+ constructor(status: number, refusal: OpRefusalResponse);
112
+ }
113
+ /**
114
+ * A Macro database: a named collection of tables, owned and shared as one
115
+ * entity.
116
+ *
117
+ * A free-to-construct `(client, id)` handle like any other entity — the schema
118
+ * loads lazily on first field access and is dropped after any mutation.
119
+ */
120
+ export declare class Database extends MacroEntity<DatabaseDetail> {
121
+ /** Access requests and direct user grants. */
122
+ readonly access: EntityAccess;
123
+ protected fetch(): Promise<DatabaseDetail>;
124
+ private assertOwns;
125
+ /** A handle to a database by id. Details load on first access. */
126
+ static byId(client: MacroClient, id: string): Database;
127
+ /** Create a database owned by the caller. */
128
+ static create(client: MacroClient, options: {
129
+ name: string;
130
+ }): Promise<Database>;
131
+ /** The databases the caller can see, each with the caller's access level. */
132
+ static list(client: MacroClient): Promise<Database[]>;
133
+ /** Run one SQL statement with this database as the default name scope. */
134
+ query(sql: string, options?: Omit<DatabaseQueryOptions, 'database'>): Promise<DatabaseQueryResult>;
135
+ /** @internal Drop the schema snapshot after a successful SQL write. */
136
+ invalidateSchema(): void;
137
+ /**
138
+ * The full schema: the database record, the caller's access, and every
139
+ * table with its columns and views. Cached until the next write.
140
+ */
141
+ schema(): Promise<DatabaseDetail>;
142
+ /** The database's display name. */
143
+ readonly name: () => Promise<string>;
144
+ /** The user who owns the database. */
145
+ readonly owner: () => Promise<User>;
146
+ /** When the database was created. */
147
+ readonly createdAt: () => Promise<string>;
148
+ /** When the database was trashed, if it has been. */
149
+ readonly trashedAt: () => Promise<string | undefined>;
150
+ /** The caller's access on the database. */
151
+ readonly grant: () => Promise<import("../../../generated/storage").AccessLevel>;
152
+ /** The database's tables, in tab order. */
153
+ readonly tables: () => Promise<DatabaseTable[]>;
154
+ /** The table with the given display name, or `undefined` if there is none. */
155
+ table(name: string): Promise<DatabaseTable | undefined>;
156
+ /** Create a table in the database, under an id minted here. */
157
+ createTable(options: {
158
+ name: string;
159
+ }): Promise<DatabaseTable>;
160
+ /**
161
+ * Apply ops to the database in one transaction: create, rename, reorder,
162
+ * or delete tables and columns; change a column's type; add, edit, or
163
+ * delete select options; insert, update, or delete rows; create, change,
164
+ * reorder, or delete views; move board cards. Later ops see what earlier
165
+ * ones did, so a table or column created by one op (under an id the caller
166
+ * mints, as a UUIDv7) can be named by the next. A refused op leaves the
167
+ * whole batch unwritten and throws {@link MacroOpRefusedError}. Returns one
168
+ * result per op, in the order sent.
169
+ */
170
+ applyOps(ops: DatabaseOp[], options?: ApplyOpsOptions): Promise<OpResult[]>;
171
+ /**
172
+ * Persist a new tab order. Pass every table of the database exactly once.
173
+ * Returns the tables in their new order.
174
+ */
175
+ reorderTables(tables: DatabaseTable[]): Promise<DatabaseTable[]>;
176
+ /**
177
+ * Delete one of the database's tables with its columns, rows, and views.
178
+ * A database keeps at least one table, and a table another table's
179
+ * relation column points at cannot be deleted.
180
+ */
181
+ deleteTable(table: DatabaseTable): Promise<void>;
182
+ /**
183
+ * What changing a column to each type would do to its values. Changes
184
+ * nothing.
185
+ */
186
+ columnCasts(column: DatabaseColumn): Promise<ColumnCast[]>;
187
+ /** Where a board view's cards sit: each placed card's lane and key. */
188
+ viewPositions(view: DatabaseView): Promise<CardPosition[]>;
189
+ /**
190
+ * A row's history: every committed change that touched it, newest first.
191
+ * See {@link DatabaseRow.history}.
192
+ */
193
+ rowHistory(row: DatabaseRow): Promise<RowHistoryEntry[]>;
194
+ /** Import text rows atomically. Keep requestId unchanged when retrying. */
195
+ importTable(request: ImportTable): Promise<DatabaseTable>;
196
+ private webhookOf;
197
+ /** The database's webhooks, oldest first. Takes edit access. */
198
+ webhooks(): Promise<DatabaseWebhook[]>;
199
+ /**
200
+ * Create a webhook that inserts rows into `table`, writing with the
201
+ * caller's access. POST a JSON object (one row) or an array of objects to
202
+ * `/databases/webhooks/{token}` on the storage service; keys name columns.
203
+ * The token is the whole credential and is answered only here.
204
+ */
205
+ createWebhook(table: DatabaseTable): Promise<{
206
+ webhook: DatabaseWebhook;
207
+ token: string;
208
+ }>;
209
+ /** Delete one of the database's webhooks; its URL stops working. */
210
+ deleteWebhook(webhook: DatabaseWebhook): Promise<void>;
211
+ /** Read direct recipients. Only the database owner can manage sharing. */
212
+ sharePermissions(): Promise<SharePermissionV2>;
213
+ /** Add, replace, or remove recipient grants without transferring ownership. */
214
+ updateSharePermissions(request: UpdateSharePermissionRequestV2): Promise<SharePermissionV2>;
215
+ /**
216
+ * Change a column's type at the table version last read. Every value must
217
+ * convert: one that does not refuses the change, naming how many and a few
218
+ * of them, and nothing is written. To keep the original column, see
219
+ * {@link Database.convertColumnIntoNewColumn}.
220
+ */
221
+ changeColumnType(column: DatabaseColumn, options: ChangeColumnTypeOptions): Promise<OpResultOf<'column', 'type_changed'>>;
222
+ /**
223
+ * What a column's values become under another type: the values that
224
+ * convert, the option labels a new select or tag column of that type needs,
225
+ * and how many values do not convert. Changes nothing.
226
+ */
227
+ columnConversion(column: DatabaseColumn, to: ColumnType): Promise<ColumnConversion>;
228
+ /**
229
+ * Add a column of another type right after this one, filled with the
230
+ * values that convert, in one batch at the table version the conversion
231
+ * was read at. The original column is left as it is; values that do not
232
+ * convert stay only there.
233
+ */
234
+ convertColumnIntoNewColumn(column: DatabaseColumn, options: ConvertIntoNewColumnOptions): Promise<DatabaseColumn>;
235
+ /**
236
+ * Remove a column and its cells at the table version last read. Returns
237
+ * the table's new version.
238
+ */
239
+ deleteColumn(column: DatabaseColumn): Promise<TableVersion>;
240
+ /**
241
+ * Persist a complete column order at the table version last read. Pass
242
+ * every column of the table exactly once.
243
+ * Returns the table's new version.
244
+ */
245
+ reorderColumns(table: DatabaseTable, columns: DatabaseColumn[]): Promise<TableVersion>;
246
+ /**
247
+ * Rename a table only if its last-read name is still current. Returns the
248
+ * table's new version.
249
+ */
250
+ renameTable(table: DatabaseTable, name: string): Promise<TableVersion>;
251
+ /**
252
+ * Rename this column placement, only if its last-read name is still
253
+ * current, without changing its shared property definition. Returns the
254
+ * table's new version.
255
+ */
256
+ renameColumn(column: DatabaseColumn, name: string): Promise<TableVersion>;
257
+ /** Adopt a first-value type only while the owned column is empty and inferable. */
258
+ inferColumnType(column: DatabaseColumn, options: InferColumnTypeOptions): Promise<InferColumnTypeOutcome>;
259
+ /**
260
+ * Add a column to one of the database's tables, under an id minted here,
261
+ * either creating a property definition for it or binding an existing one.
262
+ */
263
+ addColumn(table: DatabaseTable, options: AddColumnOptions): Promise<DatabaseColumn>;
264
+ /**
265
+ * Add select options to one of the database's columns, each under an id
266
+ * minted here. Labels the column already has are skipped, so the call is
267
+ * safe to repeat; the result lists the options it did create. Only select
268
+ * and tag columns accept options.
269
+ */
270
+ addColumnOptions(column: DatabaseColumn, labels: string[]): Promise<OpResultOf<'column', 'options_added'>>;
271
+ }
272
+ export {};
@@ -0,0 +1,21 @@
1
+ import type { MacroClient } from '../../utils/client';
2
+ import { Database } from './database';
3
+ import { type DatabaseQueryOptions, type DatabaseQueryResult } from './query';
4
+ /**
5
+ * Macro databases: named collections of tables, owned and shared as one
6
+ * entity.
7
+ */
8
+ export declare class DatabaseNamespace {
9
+ private readonly client;
10
+ constructor(client: MacroClient);
11
+ /** Run one SQL statement over the caller's visible databases. Writes execute once. */
12
+ query(sql: string, options?: DatabaseQueryOptions): Promise<DatabaseQueryResult>;
13
+ /** A handle to a database by id. Details load on first access. */
14
+ byId(id: string): Database;
15
+ /** Create a database owned by the caller. */
16
+ create(options: {
17
+ name: string;
18
+ }): Promise<Database>;
19
+ /** The databases the caller can see. */
20
+ list(): Promise<Database[]>;
21
+ }
@@ -0,0 +1,86 @@
1
+ import type { ResultColumn, ResultSet, SqlStatement, TableVersion } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { DatabaseColumn } from './column';
4
+ import type { Database } from './database';
5
+ import { DatabaseRow } from './row';
6
+ import { DatabaseTable } from './table';
7
+ /** A version observed on a typed table handle, reusable as a write guard. */
8
+ export interface QueryTableVersion {
9
+ /** Table whose version was observed. */
10
+ table: DatabaseTable;
11
+ /** Opaque version to pass back as an optimistic write guard. */
12
+ version: TableVersion;
13
+ }
14
+ /** Scope and optimistic concurrency for one SQL statement. */
15
+ export interface DatabaseQueryOptions {
16
+ /** Default database for unqualified table names; visible databases remain joinable. */
17
+ database?: Database;
18
+ /** Refuse writes if these tables changed since they were read. */
19
+ baseVersions?: QueryTableVersion[];
20
+ }
21
+ /** Result column metadata, including a typed relation target when visible. */
22
+ export type QueryColumn = Omit<ResultColumn, 'relatedTable'> & {
23
+ /** Visible target table for a relation column. */
24
+ relatedTable?: DatabaseTable;
25
+ };
26
+ /** SQL returns dynamically shaped, discriminated cells and optional source row handles. */
27
+ export interface QueryResultSet {
28
+ /** Ordered metadata corresponding to each cell in a result row. */
29
+ columns: QueryColumn[];
30
+ /** Dynamic tagged cells in column order; empty cells are null. */
31
+ rows: ResultSet['rows'];
32
+ /** Persisted source table when results correspond to individual rows. */
33
+ sourceTable?: DatabaseTable;
34
+ /** Source row handles in result order; empty for aggregates and virtual tables. */
35
+ rowHandles: DatabaseRow[];
36
+ }
37
+ /** What ran, with typed handles for resources written by the statement. */
38
+ export type QueryStatement = Extract<SqlStatement, {
39
+ kind: 'select';
40
+ }> | {
41
+ /** Schema change discriminator. */
42
+ kind: 'schema';
43
+ /** Database whose schema changed. */
44
+ database: Database;
45
+ /** Human-readable description of the schema change. */
46
+ summary: string;
47
+ } | {
48
+ /** Row mutation discriminator. */
49
+ kind: 'insert' | 'update' | 'delete';
50
+ /** Table targeted by the mutation, including zero-match writes. */
51
+ table: DatabaseTable;
52
+ /** SQL name of the target table. */
53
+ tableName: string;
54
+ } | {
55
+ /** Column type change discriminator. */
56
+ kind: 'alterColumnType';
57
+ /** Table containing the changed column. */
58
+ table: DatabaseTable;
59
+ /** SQL name of the target table. */
60
+ tableName: string;
61
+ /** Column whose type changed. */
62
+ column: DatabaseColumn;
63
+ /** SQL name of the changed column. */
64
+ columnName: string;
65
+ /** SQL type requested by the statement. */
66
+ to: string;
67
+ };
68
+ /** The committed outcome of one statement; write calls are never automatically retried. */
69
+ export interface DatabaseQueryResult {
70
+ /** Returned result set, when the statement produces one. */
71
+ result?: QueryResultSet;
72
+ /** Number of changes committed by the statement. */
73
+ changesApplied: number;
74
+ /** Handles for newly inserted rows, in insertion order. */
75
+ insertedRows: DatabaseRow[];
76
+ /** Versions of tables after committed writes. */
77
+ newVersions: QueryTableVersion[];
78
+ /** Observed table versions, reusable as guards for a later write. */
79
+ readVersions: QueryTableVersion[];
80
+ /** SQL table names whose input hit the server row cap; aggregates may be partial. */
81
+ truncatedTables: string[];
82
+ /** Statement classification with typed handles for its targets. */
83
+ statement: QueryStatement;
84
+ }
85
+ /** @internal Execute through the generated client and hydrate resource references. */
86
+ export declare function queryDatabases(client: MacroClient, databaseById: typeof Database.byId, sql: string, options?: DatabaseQueryOptions): Promise<DatabaseQueryResult>;
@@ -0,0 +1,27 @@
1
+ import type { RowHistoryEntry } from '../../../generated/storage/types.gen';
2
+ import type { DatabaseTable } from './table';
3
+ /**
4
+ * One row of a {@link DatabaseTable}.
5
+ *
6
+ * A row is not an entity of its own — it is owned and shared as part of its
7
+ * database. Its cells are written with ops; see {@link Database.applyOps}.
8
+ */
9
+ export declare class DatabaseRow {
10
+ /** The table this row belongs to. */
11
+ readonly table: DatabaseTable;
12
+ /** Identifier of the row. */
13
+ readonly id: string;
14
+ private constructor();
15
+ /** A handle to a row by id, within a table. */
16
+ static byId(table: DatabaseTable, id: string): DatabaseRow;
17
+ /**
18
+ * Every committed change that touched the row, newest first: who made it,
19
+ * when, how, and the values of the columns it touched before and after.
20
+ * A removed row's history still reads.
21
+ */
22
+ history(): Promise<RowHistoryEntry[]>;
23
+ toJSON(): {
24
+ id: string;
25
+ tableId: string;
26
+ };
27
+ }
@@ -0,0 +1,61 @@
1
+ import type { TableDetail, TableVersion } from '../../../generated/storage/types.gen';
2
+ import { DatabaseColumn } from './column';
3
+ import type { AddColumnOptions, Database } from './database';
4
+ import { DatabaseRow } from './row';
5
+ import { DatabaseView } from './view';
6
+ import type { DatabaseWebhook } from './webhook';
7
+ /**
8
+ * One table (tab) of a {@link Database}.
9
+ *
10
+ * A table is not an entity of its own — it is owned and shared as part of its
11
+ * database, and has no endpoint to read it directly. The handle resolves
12
+ * through {@link Database.schema}, so reads after a write see the new state.
13
+ */
14
+ export declare class DatabaseTable {
15
+ /** The database this table belongs to. */
16
+ readonly database: Database;
17
+ /** Identifier of the table. */
18
+ readonly id: string;
19
+ private constructor();
20
+ /** A handle to a table by id, within a database. Details load on first access. */
21
+ static byId(database: Database, id: string): DatabaseTable;
22
+ /**
23
+ * The table's record as the API returns it: the table, its columns, and
24
+ * its views.
25
+ */
26
+ detail(): Promise<TableDetail>;
27
+ /** The table's display name. */
28
+ name(): Promise<string>;
29
+ /** Rename only if the last-read display name is still current. */
30
+ rename(name: string): Promise<DatabaseTable>;
31
+ /**
32
+ * The table's current version, bumped by every committed change to its
33
+ * schema or rows. Schema edits such as {@link reorderColumns} send it as
34
+ * the base version they were made against, so a table that moved since
35
+ * refuses the edit with a 409.
36
+ */
37
+ version(): Promise<TableVersion>;
38
+ /** The table's fractional index within the database's tab order. */
39
+ position(): Promise<string>;
40
+ /** The table's columns, in display order. */
41
+ columns(): Promise<DatabaseColumn[]>;
42
+ /** Add a column to this table. See {@link Database.addColumn}. */
43
+ addColumn(options: AddColumnOptions): Promise<DatabaseColumn>;
44
+ /** Persist a new column order. See {@link Database.reorderColumns}. */
45
+ reorderColumns(columns: DatabaseColumn[]): Promise<DatabaseTable>;
46
+ /** A handle to one of the table's rows, by the id an insert answered. */
47
+ row(id: string): DatabaseRow;
48
+ /** The table's views, in their order. */
49
+ views(): Promise<DatabaseView[]>;
50
+ /** Create a webhook that inserts rows here. See {@link Database.createWebhook}. */
51
+ createWebhook(): Promise<{
52
+ webhook: DatabaseWebhook;
53
+ token: string;
54
+ }>;
55
+ /** Delete this table. See {@link Database.deleteTable}. */
56
+ delete(): Promise<void>;
57
+ toJSON(): {
58
+ id: string;
59
+ databaseId: string;
60
+ };
61
+ }
@@ -0,0 +1,40 @@
1
+ import type { CardPosition, DatabaseView as DatabaseViewRecord, ViewLayout, ViewQuery } from '../../../generated/storage/types.gen';
2
+ import type { DatabaseTable } from './table';
3
+ /**
4
+ * One view of a {@link DatabaseTable}: which of its rows to show, in what
5
+ * order, drawn as a table or a board.
6
+ *
7
+ * A view is not an entity of its own — it is owned and shared as part of its
8
+ * database. The handle resolves through the database's schema, so a fresh
9
+ * read after a write sees the new value. Views are created, changed, and
10
+ * reordered with ops; see {@link Database.applyOps}.
11
+ */
12
+ export declare class DatabaseView {
13
+ /** The table this view shows. */
14
+ readonly table: DatabaseTable;
15
+ /** Identifier of the view. */
16
+ readonly id: string;
17
+ private constructor();
18
+ /** A handle to a view by id, within a table. Details load on first access. */
19
+ static byId(table: DatabaseTable, id: string): DatabaseView;
20
+ /** The view's record as the API returns it. */
21
+ detail(): Promise<DatabaseViewRecord>;
22
+ /** The view's name, unique among its table's views ignoring case. */
23
+ name(): Promise<string>;
24
+ /** The view's fractional index within its table's views. */
25
+ position(): Promise<string>;
26
+ /** How the view draws its rows: a table, or a board grouped by a column. */
27
+ layout(): Promise<ViewLayout>;
28
+ /** Which rows the view shows, and in what order. */
29
+ query(): Promise<ViewQuery>;
30
+ /**
31
+ * Where a board's cards sit: each placed card's lane and its key there.
32
+ * Cards without a place show after the placed ones of their lane, oldest
33
+ * first.
34
+ */
35
+ positions(): Promise<CardPosition[]>;
36
+ toJSON(): {
37
+ id: string;
38
+ tableId: string;
39
+ };
40
+ }
@@ -0,0 +1,32 @@
1
+ import type { DatabaseWebhookResponse } from '../../../generated/storage/types.gen';
2
+ import type { User } from '../users/user';
3
+ import type { DatabaseTable } from './table';
4
+ /**
5
+ * A webhook of a {@link DatabaseTable}: a secret URL that anyone holding it
6
+ * can POST JSON to, each object becoming a row, written with the access of
7
+ * the user who created it. Its token is shown only when it is created; see
8
+ * {@link Database.createWebhook}.
9
+ */
10
+ export declare class DatabaseWebhook {
11
+ /** The table its calls insert rows into. */
12
+ readonly table: DatabaseTable;
13
+ /** Identifier of the webhook. */
14
+ readonly id: string;
15
+ /** Who created it; its calls write with their access. */
16
+ readonly createdBy: User;
17
+ private readonly record;
18
+ private constructor();
19
+ /** A handle from the record the API answered. */
20
+ static fromRecord(table: DatabaseTable, createdBy: User, record: DatabaseWebhookResponse): DatabaseWebhook;
21
+ /** The token's first characters, to tell webhooks apart without the secret. */
22
+ get tokenPrefix(): string;
23
+ /** When it was created. */
24
+ get createdAt(): string;
25
+ /** Delete the webhook; its URL stops working. */
26
+ delete(): Promise<void>;
27
+ toJSON(): {
28
+ id: string;
29
+ tableId: string;
30
+ tokenPrefix: string;
31
+ };
32
+ }
@@ -0,0 +1,29 @@
1
+ import type { Anchor as AnchorRecord, EditPdfPlaceableCommentAnchorRequest } from '../../../generated/storage/types.gen';
2
+ import type { MacroClient } from '../../utils/client';
3
+ import { MacroEntity } from '../entity';
4
+ import type { Document } from './document';
5
+ /** A PDF annotation scoped to its document. */
6
+ export declare class DocumentAnchor extends MacroEntity<AnchorRecord> {
7
+ /** Owning document. */
8
+ readonly document: Document;
9
+ /** Serialize identity with its owning resource. */
10
+ toJSON(): {
11
+ documentId: string;
12
+ id: string;
13
+ detail?: import("../../../generated/storage").PdfAnchor | undefined;
14
+ };
15
+ private constructor();
16
+ /** Construct a document scoped annotation handle. */
17
+ static byId(client: MacroClient, document: Document, id: string): DocumentAnchor;
18
+ /** Seed an annotation from a document annotation listing. */
19
+ static from(client: MacroClient, document: Document, record: AnchorRecord): DocumentAnchor;
20
+ protected fetch(): Promise<AnchorRecord>;
21
+ /** Annotation kind. */
22
+ readonly kind: () => Promise<"highlight" | "placeable">;
23
+ /** Page containing the annotation. */
24
+ readonly page: () => Promise<number>;
25
+ /** Edit a placeable comment's position and display settings. */
26
+ edit(options: Omit<EditPdfPlaceableCommentAnchorRequest, 'uuid'>): Promise<void>;
27
+ /** Delete a standalone highlight annotation. */
28
+ delete(): Promise<void>;
29
+ }