@almateam/app-sdk 0.5.0 → 0.7.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.
- package/README.md +178 -22
- package/generated/apiTypes.d.ts +437 -50
- package/index.d.ts +486 -24
- package/index.js +865 -35
- package/navigation.d.ts +21 -0
- package/package.json +2 -2
package/index.d.ts
CHANGED
|
@@ -1,14 +1,28 @@
|
|
|
1
1
|
import type * as Api from "./generated/apiTypes";
|
|
2
2
|
export * from "./navigation";
|
|
3
3
|
export type * from "./generated/apiTypes";
|
|
4
|
-
/** Which records `listTopics` reads.
|
|
5
|
-
* `<field>:<op>:<value>` (op: eq, ne,
|
|
6
|
-
* field filter or sort needs `type`. `sort` is a field or `name`,
|
|
7
|
-
* `created_at`, `updated_at`; `-` in front sorts descending.
|
|
4
|
+
/** Which records `listTopics` reads. `schema` is the `schema.id` of a `type`
|
|
5
|
+
* another app keeps. A field filter is `<field>:<op>:<value>` (op: eq, ne,
|
|
6
|
+
* lt, lte, gt, gte, contains), and a field filter or sort needs `type`. `sort` is a field or `name`,
|
|
7
|
+
* `created_at`, `updated_at`; `-` in front sorts descending.
|
|
8
|
+
* `updated_after` (an ISO 8601 instant with its offset) reads only the
|
|
9
|
+
* records whose `updated_at` is at or after it. Only a change to the
|
|
10
|
+
* record or its own values moves `updated_at`: a record that joins or
|
|
11
|
+
* leaves the viewer's reach, or is archived or deleted, is never
|
|
12
|
+
* reported; a `watchTopics` the host tells about the type reports one
|
|
13
|
+
* archived, deleted, merged away or moved to another type as
|
|
14
|
+
* `removed`. */
|
|
8
15
|
export interface TopicQuery {
|
|
9
16
|
type?: string;
|
|
17
|
+
schema?: string;
|
|
10
18
|
filter?: string[];
|
|
11
19
|
sort?: string;
|
|
20
|
+
updated_after?: string;
|
|
21
|
+
cursor?: string;
|
|
22
|
+
limit?: number;
|
|
23
|
+
}
|
|
24
|
+
/** Where a page of a saved view starts and how many records it holds. */
|
|
25
|
+
export interface ViewPage {
|
|
12
26
|
cursor?: string;
|
|
13
27
|
limit?: number;
|
|
14
28
|
}
|
|
@@ -40,12 +54,21 @@ export interface PollOptions {
|
|
|
40
54
|
declare const APP_OPERATIONS: {
|
|
41
55
|
readonly listTopics: "read";
|
|
42
56
|
readonly createTopic: "change";
|
|
57
|
+
readonly deleteTopic: "change";
|
|
58
|
+
readonly restoreTopic: "change";
|
|
43
59
|
readonly listTopicTypes: "read";
|
|
44
60
|
readonly getTopicRecord: "read";
|
|
61
|
+
readonly listViews: "read";
|
|
62
|
+
readonly readView: "read";
|
|
63
|
+
readonly listTopicReferences: "read";
|
|
64
|
+
readonly countTopics: "read";
|
|
65
|
+
readonly listRelatedTopics: "read";
|
|
45
66
|
readonly getTopicFactDiscussion: "read";
|
|
46
67
|
readonly getTopicFieldHistory: "read";
|
|
68
|
+
readonly getTopicSummary: "read";
|
|
47
69
|
readonly downloadTopicFactAttachment: "read";
|
|
48
70
|
readonly setTopicField: "change";
|
|
71
|
+
readonly clearTopicField: "change";
|
|
49
72
|
readonly listWorkflows: "read";
|
|
50
73
|
readonly getWorkflowCard: "read";
|
|
51
74
|
readonly createLesson: "change";
|
|
@@ -54,10 +77,16 @@ declare const APP_OPERATIONS: {
|
|
|
54
77
|
readonly listWorkflowExecutions: "read";
|
|
55
78
|
readonly getExecution: "read";
|
|
56
79
|
readonly listOutcomes: "read";
|
|
57
|
-
readonly
|
|
80
|
+
readonly publishCard: "change";
|
|
81
|
+
readonly raiseAppEvent: "change";
|
|
58
82
|
readonly getAppState: "read";
|
|
59
83
|
readonly setAppState: "change";
|
|
60
84
|
readonly deleteAppState: "change";
|
|
85
|
+
readonly listAppSharedState: "read";
|
|
86
|
+
readonly getAppSharedState: "read";
|
|
87
|
+
readonly setAppSharedState: "change";
|
|
88
|
+
readonly deleteAppSharedState: "change";
|
|
89
|
+
readonly sendAppBroadcast: "change";
|
|
61
90
|
};
|
|
62
91
|
export type AppOperationId = keyof typeof APP_OPERATIONS;
|
|
63
92
|
export interface AppRequest {
|
|
@@ -80,13 +109,14 @@ export interface FieldState {
|
|
|
80
109
|
}
|
|
81
110
|
/** A refused call. `message` is the refusal's words, to show as they are.
|
|
82
111
|
* A refusal a program can act on also carries its `code`; `field.changed`
|
|
83
|
-
* carries the field as it stands in `current
|
|
112
|
+
* carries the field as it stands in `current`, and
|
|
113
|
+
* `app_shared_state.revision_conflict` the shared key. */
|
|
84
114
|
export declare class AppCallError extends Error {
|
|
85
115
|
readonly code: string | undefined;
|
|
86
|
-
readonly current: FieldState | undefined;
|
|
116
|
+
readonly current: FieldState | Api.AppSharedStateEntry | undefined;
|
|
87
117
|
constructor(message: string, detail?: {
|
|
88
118
|
code?: string;
|
|
89
|
-
current?: FieldState;
|
|
119
|
+
current?: FieldState | Api.AppSharedStateEntry;
|
|
90
120
|
});
|
|
91
121
|
}
|
|
92
122
|
/** A field write refused because the field changed after the app read it.
|
|
@@ -96,17 +126,165 @@ export type FieldChangedError = AppCallError & {
|
|
|
96
126
|
current: FieldState;
|
|
97
127
|
};
|
|
98
128
|
export declare function isFieldChanged(error: unknown): error is FieldChangedError;
|
|
129
|
+
/** A shared-state write refused because the key moved past the
|
|
130
|
+
* `ifRevision` it named. Nothing was written; `current` is what the key
|
|
131
|
+
* holds now. */
|
|
132
|
+
export type SharedStateConflictError = AppCallError & {
|
|
133
|
+
code: "app_shared_state.revision_conflict";
|
|
134
|
+
current: Api.AppSharedStateEntry;
|
|
135
|
+
};
|
|
136
|
+
export declare function isSharedStateConflict(error: unknown): error is SharedStateConflictError;
|
|
137
|
+
/** A record as `lastLooked` reads it: its id and its fields' revisions. */
|
|
138
|
+
export interface LookedRecord {
|
|
139
|
+
id: string;
|
|
140
|
+
revisions?: Record<string, string> | null;
|
|
141
|
+
}
|
|
142
|
+
/** Names one change request. Passed again on a later call (a double click,
|
|
143
|
+
* or a retry after an answer that never arrived), the same key answers
|
|
144
|
+
* with what the first call did and changes nothing. Left out, each call is
|
|
145
|
+
* its own request. */
|
|
146
|
+
export interface ChangeOptions {
|
|
147
|
+
idempotencyKey?: string;
|
|
148
|
+
}
|
|
99
149
|
/** What a field write says the app read before writing. Left out, the SDK
|
|
100
150
|
* sends what its own last read of the record showed. A write to a record
|
|
101
151
|
* the app never read, with none of these, is refused. */
|
|
102
|
-
export interface FieldWriteOptions {
|
|
152
|
+
export interface FieldWriteOptions extends ChangeOptions {
|
|
103
153
|
/** The field's revision, from a record's `revisions`, a receipt's
|
|
104
154
|
* `revision` or a conflict's `current.revision`. */
|
|
105
155
|
ifRevision?: string;
|
|
106
156
|
/** A value the field held, as its `text` was read; null if it held
|
|
107
157
|
* nothing. */
|
|
108
158
|
ifValue?: string | null;
|
|
109
|
-
|
|
159
|
+
}
|
|
160
|
+
/** One value a new record starts with: the field's key, the value as
|
|
161
|
+
* `setTopicField` takes it and, for a relationship, the record it points at.
|
|
162
|
+
* Naming a key twice gives a field that holds many both values. */
|
|
163
|
+
export interface NewRecordField {
|
|
164
|
+
key: string;
|
|
165
|
+
value: string;
|
|
166
|
+
refTopicId?: string;
|
|
167
|
+
}
|
|
168
|
+
export interface CreateTopicOptions extends ChangeOptions {
|
|
169
|
+
/** Saved with the record, or not at all. */
|
|
170
|
+
fields?: NewRecordField[];
|
|
171
|
+
}
|
|
172
|
+
/** Who is viewing the app, as Alma knows them: the record of type `person`
|
|
173
|
+
* that is the signed-in member in this workspace. */
|
|
174
|
+
export interface AppViewer {
|
|
175
|
+
person_id: string;
|
|
176
|
+
}
|
|
177
|
+
/** What one of Alma's templates shows and how, as the member added it: the
|
|
178
|
+
* type by id (find it in `listTopicTypes`), and fields by their keys. */
|
|
179
|
+
export interface AppShell {
|
|
180
|
+
record_type_id: string;
|
|
181
|
+
layout: "list" | "board" | "table" | "queue";
|
|
182
|
+
signature: "strip" | "timeline" | "status" | "none";
|
|
183
|
+
/** The date field a timeline marks, or the choice field a status dot
|
|
184
|
+
* reads; null for a strip or no signature. */
|
|
185
|
+
signature_field: string | null;
|
|
186
|
+
fields: string[];
|
|
187
|
+
/** The choice field a board's columns, or a list's groups, follow. */
|
|
188
|
+
group_by: string | null;
|
|
189
|
+
density: "comfortable" | "compact";
|
|
190
|
+
/** The app's accent, as one of Alma's tints; null keeps Alma's own. */
|
|
191
|
+
color: number | null;
|
|
192
|
+
/** Which records it keeps, by the values of one choice field: only those
|
|
193
|
+
* holding one of `values`, or every record but those. Null keeps all. */
|
|
194
|
+
filter: {
|
|
195
|
+
field: string;
|
|
196
|
+
mode: "only" | "hide";
|
|
197
|
+
values: string[];
|
|
198
|
+
} | null;
|
|
199
|
+
}
|
|
200
|
+
/** A question an app asks its host rather than Alma's API. The host
|
|
201
|
+
* answers it from the session it opened, which the server derived from the
|
|
202
|
+
* signed-in member; a host from before it refuses the name like any
|
|
203
|
+
* operation it does not have. */
|
|
204
|
+
export declare const VIEWER_QUESTION = "getViewer";
|
|
205
|
+
/** Another question for the host: what a template shows. Answered from the
|
|
206
|
+
* session like the viewer, and refused by a host from before it. */
|
|
207
|
+
export declare const SHELL_QUESTION = "getAppShell";
|
|
208
|
+
/** Another question for the host: to be told when topics the app read
|
|
209
|
+
* change. The host answers with the ones it will tell about; a host from
|
|
210
|
+
* before it refuses the name, and the app polls instead. */
|
|
211
|
+
export declare const WATCH_QUESTION = "watchTopicChanges";
|
|
212
|
+
/** Another question for the host: to be told when any record of a type the
|
|
213
|
+
* app listed changes or joins. A host from before it refuses the name, and
|
|
214
|
+
* the app watches each topic instead. */
|
|
215
|
+
export declare const WATCH_TYPES_QUESTION = "watchTypeChanges";
|
|
216
|
+
/** Another question for the host: to be told when a key of the app's shared
|
|
217
|
+
* state changes, with its value. The host answers whether it will tell; a
|
|
218
|
+
* host that cannot (the app check's) refuses the name, and `shared.watch`
|
|
219
|
+
* polls. */
|
|
220
|
+
export declare const WATCH_SHARED_QUESTION = "watchSharedState";
|
|
221
|
+
/** The message a host tells a shared-state change with, on the port. */
|
|
222
|
+
export declare const SHARED_STATE_MESSAGE = "alma:shared";
|
|
223
|
+
/** Another question for the host: to be told who has the app open. The host
|
|
224
|
+
* answers whether it will tell; one that cannot refuses the name, and
|
|
225
|
+
* `presence.watch` hears nothing. */
|
|
226
|
+
export declare const WATCH_PRESENCE_QUESTION = "watchPresence";
|
|
227
|
+
/** The message a host tells who has the app open with, on the port. */
|
|
228
|
+
export declare const PRESENCE_MESSAGE = "alma:presence";
|
|
229
|
+
/** Another question for the host: to be told each quick message sent to
|
|
230
|
+
* everyone with the app open. The host answers whether it will tell; one
|
|
231
|
+
* that cannot refuses the name, and `onBroadcast` hears nothing. */
|
|
232
|
+
export declare const WATCH_BROADCASTS_QUESTION = "watchBroadcasts";
|
|
233
|
+
/** The message a host tells a quick message with, on the port. */
|
|
234
|
+
export declare const BROADCAST_MESSAGE = "alma:broadcast";
|
|
235
|
+
/** Who has the app open right now, the viewer among them while Alma shows
|
|
236
|
+
* them as present: how many, and who, each person once, for an app that
|
|
237
|
+
* declares `viewer:read`. Without it `people` is null, and `count` counts
|
|
238
|
+
* the tabs open. */
|
|
239
|
+
export interface AppPresence {
|
|
240
|
+
count: number;
|
|
241
|
+
people: AppViewer[] | null;
|
|
242
|
+
}
|
|
243
|
+
/** What a host answers a presence watch with: whether it will tell, and how
|
|
244
|
+
* to stop hearing it. */
|
|
245
|
+
export interface PresenceWatch {
|
|
246
|
+
watching: boolean;
|
|
247
|
+
stop(): void;
|
|
248
|
+
}
|
|
249
|
+
/** What a host that tells changes answers a watch with: the ids it will
|
|
250
|
+
* tell about (`changed` hears each change), and how to stop hearing them. */
|
|
251
|
+
export interface TopicWatch {
|
|
252
|
+
watching: string[];
|
|
253
|
+
stop(): void;
|
|
254
|
+
}
|
|
255
|
+
/** What a host tells about the app's shared state: a key set at a revision,
|
|
256
|
+
* with its value unless the workspace keeps values off the push (then the
|
|
257
|
+
* SDK reads the key); a key deleted at a revision (`exists: false`); or that
|
|
258
|
+
* a change may have passed unheard. */
|
|
259
|
+
export type SharedStateTold = {
|
|
260
|
+
key: string;
|
|
261
|
+
revision: number;
|
|
262
|
+
value?: unknown;
|
|
263
|
+
} | {
|
|
264
|
+
key: string;
|
|
265
|
+
revision: number;
|
|
266
|
+
exists: false;
|
|
267
|
+
} | {
|
|
268
|
+
missed: true;
|
|
269
|
+
};
|
|
270
|
+
/** What a host answers a shared-state watch with: whether it will tell
|
|
271
|
+
* changes, and how to stop hearing them. */
|
|
272
|
+
export interface SharedStateWatch {
|
|
273
|
+
watching: boolean;
|
|
274
|
+
stop(): void;
|
|
275
|
+
}
|
|
276
|
+
/** A quick message as a host tells it: its event, its payload, and whether
|
|
277
|
+
* this open copy of the app sent it. */
|
|
278
|
+
export interface BroadcastTold {
|
|
279
|
+
event: string;
|
|
280
|
+
payload: unknown;
|
|
281
|
+
self: boolean;
|
|
282
|
+
}
|
|
283
|
+
/** What a host answers a broadcast watch with: whether it will tell
|
|
284
|
+
* messages, and how to stop hearing them. */
|
|
285
|
+
export interface BroadcastWatch {
|
|
286
|
+
watching: boolean;
|
|
287
|
+
stop(): void;
|
|
110
288
|
}
|
|
111
289
|
export interface AppTransport {
|
|
112
290
|
/** Resolves with the response's `data`, or `{ data, meta }` when the
|
|
@@ -114,13 +292,99 @@ export interface AppTransport {
|
|
|
114
292
|
* result where they may make it, and rejects with the refusal's words
|
|
115
293
|
* where they may not. */
|
|
116
294
|
call<T>(operationId: AppOperationId, request?: AppRequest): Promise<T>;
|
|
295
|
+
/** The viewer's person record, or null when the host knows none. A
|
|
296
|
+
* transport without it knows none. */
|
|
297
|
+
viewer?(): Promise<AppViewer | null>;
|
|
298
|
+
/** A template's shell, or null when the host knows none. A transport
|
|
299
|
+
* without it knows none. */
|
|
300
|
+
shell?(): Promise<AppShell | null>;
|
|
301
|
+
/** Be told when these topics change. A transport without it tells
|
|
302
|
+
* nothing, and `watchTopics` polls. */
|
|
303
|
+
watch?(topicIds: readonly string[], changed: (topicId: string) => void): Promise<TopicWatch>;
|
|
304
|
+
/** Be told when any record of these types changes or joins, and with
|
|
305
|
+
* `left` when one may have left: deleted, restored, archived, merged
|
|
306
|
+
* away or moved to another type. A transport without it tells nothing,
|
|
307
|
+
* and `watchTopics` watches each topic. */
|
|
308
|
+
watchTypes?(typeIds: readonly string[], changed: (typeId: string, left?: boolean) => void): Promise<TopicWatch>;
|
|
309
|
+
/** Be told when the app's shared state changes. A transport without it
|
|
310
|
+
* tells nothing, and `shared.watch` polls. */
|
|
311
|
+
watchShared?(told: (told: SharedStateTold) => void): Promise<SharedStateWatch>;
|
|
312
|
+
/** Be told who has the app open, each time that changes. A transport
|
|
313
|
+
* without it tells nothing. */
|
|
314
|
+
watchPresence?(told: (presence: AppPresence) => void): Promise<PresenceWatch>;
|
|
315
|
+
/** Be told each quick message sent to everyone with the app open. A
|
|
316
|
+
* transport without it tells nothing. */
|
|
317
|
+
watchBroadcasts?(told: (message: BroadcastTold) => void): Promise<BroadcastWatch>;
|
|
117
318
|
}
|
|
118
319
|
export declare function createAppSdk(transport: AppTransport): {
|
|
119
320
|
call: <T>(operationId: AppOperationId, request?: AppRequest) => Promise<T>;
|
|
321
|
+
/** The viewer's own person record (`person_id`, a record of type
|
|
322
|
+
* `person` the viewer can read), or null when Alma does not tell it:
|
|
323
|
+
* the app's manifest does not declare `viewer:read` (one of Alma's own
|
|
324
|
+
* is told under `topics:read`), no directory entry is linked to the
|
|
325
|
+
* viewer's account, they cannot read it, or the host predates the
|
|
326
|
+
* question or does not answer it promptly. Null is an answer, never a
|
|
327
|
+
* failure: an app that needs to know who its viewer is asks them then.
|
|
328
|
+
* The answer is the host's latest session's, so asking again after the
|
|
329
|
+
* app is reopened may differ. */
|
|
330
|
+
viewer: () => Promise<AppViewer | null>;
|
|
331
|
+
/** What this template shows and how, as the member added it, or null
|
|
332
|
+
* when it is not one of Alma's templates, or the host predates the
|
|
333
|
+
* question or does not answer it promptly. */
|
|
334
|
+
shell: () => Promise<AppShell | null>;
|
|
120
335
|
listTopics: (query?: TopicQuery) => Promise<{
|
|
121
336
|
data: Api.TopicRecord[];
|
|
122
337
|
meta: {
|
|
123
338
|
next_cursor: string | null;
|
|
339
|
+
type_id: string | null;
|
|
340
|
+
};
|
|
341
|
+
}>;
|
|
342
|
+
/**
|
|
343
|
+
* Told when a record this query reads changes (`kind: "topic"`: its
|
|
344
|
+
* `updated_at` moved since the watch last read it), and the first time
|
|
345
|
+
* the watch sees a record (`kind: "added"`): one created since, one
|
|
346
|
+
* an edit brought into the query, or one restored. A record on a page
|
|
347
|
+
* the watch had not read counts as added when it first shows up. The
|
|
348
|
+
* read is the viewer's own scoped read, so a record outside the app's
|
|
349
|
+
* scope or the viewer's reach is never reported.
|
|
350
|
+
*
|
|
351
|
+
* Where the host tells the app about a type's records (a query that
|
|
352
|
+
* names `type`), the SDK rereads only what changed since its last read,
|
|
353
|
+
* the moment any record of the type changes or joins. When one is
|
|
354
|
+
* deleted, restored, archived, merged away or moved to another type, it
|
|
355
|
+
* rereads the whole query, newest first, up to 1,000 records, and tells
|
|
356
|
+
* `kind: "removed"` for each record it had seen that is no longer
|
|
357
|
+
* there. Only that reread tells a removal, never the timed one. One
|
|
358
|
+
* past those 1,000 is not told. One an edit takes out of the query, or
|
|
359
|
+
* one whose type was not told (more than 8 types left in one change),
|
|
360
|
+
* is told at the next such reread, or when the app opens again.
|
|
361
|
+
* Without that host, a record that leaves the query is not reported.
|
|
362
|
+
* Where it tells about each topic instead, the SDK rereads the query
|
|
363
|
+
* the moment one of its topics changes, and otherwise only every five
|
|
364
|
+
* minutes, to pick up topics that joined it. Where it tells nothing (a
|
|
365
|
+
* host from before it, or more topics than it watches at once), the SDK
|
|
366
|
+
* polls on `intervalMs` (default 15 seconds, doubling to a minute while
|
|
367
|
+
* nothing changes). Returns the unsubscribe.
|
|
368
|
+
*/
|
|
369
|
+
watchTopics: (query: TopicQuery, listener: (event: {
|
|
370
|
+
kind: "topic" | "added" | "removed";
|
|
371
|
+
topic_id: string;
|
|
372
|
+
}) => void, options?: {
|
|
373
|
+
intervalMs?: number;
|
|
374
|
+
}) => (() => void);
|
|
375
|
+
/** The saved views of a type (its key) the viewer can open: the
|
|
376
|
+
* type's shared views, then their own. */
|
|
377
|
+
listViews: (type: string) => Promise<Api.TypeView[]>;
|
|
378
|
+
/** A page of one of a type's saved views as the viewer reads it: the
|
|
379
|
+
* view's own filters, search, sort and grouping, the columns it shows,
|
|
380
|
+
* and each record's values for them. A grouped view counts each group
|
|
381
|
+
* in `meta.groups`. */
|
|
382
|
+
readView: (type: string, key: string, page?: ViewPage) => Promise<{
|
|
383
|
+
data: Api.TopicRecord[];
|
|
384
|
+
meta: {
|
|
385
|
+
next_cursor: string | null;
|
|
386
|
+
total: number;
|
|
387
|
+
groups?: Api.TypeViewGroup[];
|
|
124
388
|
};
|
|
125
389
|
}>;
|
|
126
390
|
getTopicRecord: (topicId: string) => Promise<Api.AppTopicRecord>;
|
|
@@ -128,6 +392,82 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
128
392
|
/** A field's earlier values, newest first, as the viewer may read
|
|
129
393
|
* them. A record section's `earlier_values` says how many there are. */
|
|
130
394
|
getTopicFieldHistory: (topicId: string, fieldKey: string) => Promise<Api.TopicFieldHistory>;
|
|
395
|
+
/** The topic's page as the viewer reads it, as markdown: `content` and
|
|
396
|
+
* `generated_at` are null while it has no page the viewer can read. */
|
|
397
|
+
getTopicSummary: (topicId: string) => Promise<Api.AppTopicSummary>;
|
|
398
|
+
/** The records that name a record in a relationship field, a page at a
|
|
399
|
+
* time, with `meta.counts` over every one the viewer reaches. */
|
|
400
|
+
listTopicReferences: (topicId: string, query?: {
|
|
401
|
+
type?: string;
|
|
402
|
+
field?: string;
|
|
403
|
+
cursor?: string;
|
|
404
|
+
limit?: number;
|
|
405
|
+
}) => Promise<{
|
|
406
|
+
data: Api.ReferencingTopicRecord[];
|
|
407
|
+
meta: {
|
|
408
|
+
target: {
|
|
409
|
+
id: string;
|
|
410
|
+
name: string;
|
|
411
|
+
};
|
|
412
|
+
counts: {
|
|
413
|
+
type: string | null;
|
|
414
|
+
field: string;
|
|
415
|
+
n: number;
|
|
416
|
+
}[];
|
|
417
|
+
next_cursor: string | null;
|
|
418
|
+
complete: boolean;
|
|
419
|
+
};
|
|
420
|
+
}>;
|
|
421
|
+
/** A type's records counted as the viewer reaches them, filtered as
|
|
422
|
+
* `listTopics` filters, optionally grouped by a choice or relationship
|
|
423
|
+
* field. Never the workspace's total. */
|
|
424
|
+
countTopics: (query: {
|
|
425
|
+
type: string;
|
|
426
|
+
filter?: string[];
|
|
427
|
+
groupBy?: string;
|
|
428
|
+
limit?: number;
|
|
429
|
+
}) => Promise<{
|
|
430
|
+
data: Api.TopicCountBucket[];
|
|
431
|
+
meta: {
|
|
432
|
+
total: number;
|
|
433
|
+
other: number;
|
|
434
|
+
truncated_buckets: number;
|
|
435
|
+
complete: boolean;
|
|
436
|
+
incomplete_reason: "bucket_limit" | null;
|
|
437
|
+
};
|
|
438
|
+
}>;
|
|
439
|
+
/** The records reached from a record by relationship steps
|
|
440
|
+
* (`out:<field>`, `in:<type>.<field>`), up to four hops. `meta.complete`
|
|
441
|
+
* is false when the walk stopped at its depth or budget. */
|
|
442
|
+
listRelatedTopics: (topicId: string, query: {
|
|
443
|
+
step: string[];
|
|
444
|
+
depth?: number;
|
|
445
|
+
type?: string[];
|
|
446
|
+
filter?: string[];
|
|
447
|
+
cursor?: string;
|
|
448
|
+
limit?: number;
|
|
449
|
+
}) => Promise<{
|
|
450
|
+
data: Api.RelatedTopicRecord[];
|
|
451
|
+
meta: {
|
|
452
|
+
start: {
|
|
453
|
+
id: string;
|
|
454
|
+
name: string;
|
|
455
|
+
};
|
|
456
|
+
counts: {
|
|
457
|
+
type: string | null;
|
|
458
|
+
n: number;
|
|
459
|
+
}[];
|
|
460
|
+
unresolved: {
|
|
461
|
+
from_id: string;
|
|
462
|
+
field: string;
|
|
463
|
+
text: string;
|
|
464
|
+
}[];
|
|
465
|
+
unresolved_truncated: boolean;
|
|
466
|
+
next_cursor: string | null;
|
|
467
|
+
complete: boolean;
|
|
468
|
+
incomplete_reason: "depth" | "budget" | null;
|
|
469
|
+
};
|
|
470
|
+
}>;
|
|
131
471
|
/** The host downloads the file itself; the app receives only a receipt. */
|
|
132
472
|
downloadTopicFactAttachment: (topicId: string, factId: string, turn: {
|
|
133
473
|
kind: "message" | "queued";
|
|
@@ -145,19 +485,45 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
145
485
|
* write again against it by passing `ifRevision: error.current.revision`
|
|
146
486
|
* once the viewer has decided. */
|
|
147
487
|
setTopicField: (topicId: string, fieldKey: string, value: string, refTopicId?: string, options?: FieldWriteOptions) => Promise<Api.TopicFieldReceipt>;
|
|
148
|
-
/**
|
|
149
|
-
*
|
|
150
|
-
|
|
488
|
+
/** Empties one field as the viewer: every value it holds goes. Where
|
|
489
|
+
* they may not edit the topic it rejects with the refusal's words, and
|
|
490
|
+
* nobody is asked. Like `setTopicField` it says what this app last read
|
|
491
|
+
* of the field, and rejects with a `field.changed` error
|
|
492
|
+
* (`isFieldChanged`) if the field changed since. */
|
|
493
|
+
clearTopicField: (topicId: string, fieldKey: string, options?: FieldWriteOptions) => Promise<Api.TopicFieldClearReceipt>;
|
|
494
|
+
/** Creates a record as the viewer, with its `fields` if given. Who can
|
|
495
|
+
* see it follows the app's audience in Alma, never the app. The record and
|
|
496
|
+
* its values are saved together: if one value is refused nothing is
|
|
497
|
+
* created, and it rejects with the refusal's words, which start with the
|
|
498
|
+
* field's key. Each call is one request: calling again creates again. */
|
|
499
|
+
createTopic: (name: string, topicTypeId?: string, options?: CreateTopicOptions) => Promise<Api.CreatedTopicRecord>;
|
|
500
|
+
/** Deletes a record of one of this app's own types as the viewer. Alma
|
|
501
|
+
* keeps it for 30 days, when the person who deleted it can bring it back
|
|
502
|
+
* with `restoreTopic`, or from the app's Data if they edit the app. A
|
|
503
|
+
* record that is not this app's own rejects as not found, and one the
|
|
504
|
+
* viewer may not edit rejects with the refusal's words. */
|
|
505
|
+
deleteTopic: (topicId: string, options?: ChangeOptions) => Promise<{
|
|
506
|
+
success: boolean;
|
|
507
|
+
}>;
|
|
508
|
+
/** Brings back one of this app's records the viewer deleted, within 30
|
|
509
|
+
* days and while they can still edit it: the Undo behind `deleteTopic`.
|
|
510
|
+
* It answers with the values that did not come back (`cleared`), because
|
|
511
|
+
* they no longer fit the record's type. A record somebody else deleted
|
|
512
|
+
* rejects as not found, and one no longer theirs to edit rejects with the
|
|
513
|
+
* refusal's words. So does one past its 30 days, until Alma removes it
|
|
514
|
+
* for good; then it rejects as not found. */
|
|
515
|
+
restoreTopic: (topicId: string, options?: ChangeOptions) => Promise<Api.RestoredTopicRecord>;
|
|
151
516
|
/** Every type, its fields and its relationships. */
|
|
152
517
|
listTopicTypes: <T = Api.TopicType[]>() => Promise<T>;
|
|
153
518
|
listWorkflows: () => Promise<Api.AppWorkflowSummary[]>;
|
|
154
|
-
/** Starts a workflow the app's manifest names
|
|
155
|
-
*
|
|
156
|
-
* record, and rejects with the refusal's
|
|
519
|
+
/** Starts a workflow the app's manifest names. Nobody is asked: it starts
|
|
520
|
+
* where the workflow's owner granted the app, or the viewer may run it
|
|
521
|
+
* themselves, on a record they can see, and rejects with the refusal's
|
|
522
|
+
* words otherwise. The run acts as the workflow, not as the viewer. */
|
|
157
523
|
runWorkflow: (workflowId: string, run?: {
|
|
158
524
|
topicId?: string;
|
|
159
525
|
input?: Record<string, unknown>;
|
|
160
|
-
}) => Promise<Api.AppRunReceipt>;
|
|
526
|
+
}, options?: ChangeOptions) => Promise<Api.AppRunReceipt>;
|
|
161
527
|
/** A run the viewer started: running, waiting on people, or how it
|
|
162
528
|
* ended. */
|
|
163
529
|
getExecution: (executionId: string) => Promise<Api.AppExecution>;
|
|
@@ -172,14 +538,31 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
172
538
|
* `signal` to stop. */
|
|
173
539
|
waitForExecution: (executionId: string, options?: PollOptions) => Promise<Api.AppExecution>;
|
|
174
540
|
getWorkflowCard: (workflowId: string) => Promise<Api.WorkflowCard>;
|
|
175
|
-
/**
|
|
176
|
-
* `active:
|
|
541
|
+
/** Adds a lesson for the workflow's later runs. It is live at once
|
|
542
|
+
* (`active: true`) when the viewer can edit the workflow; otherwise it
|
|
543
|
+
* resolves with `active: false` and applies once someone who can
|
|
177
544
|
* approves it in Tasks. Screened: wording that reads as an instruction
|
|
178
545
|
* to Alma is refused with the reason. */
|
|
179
|
-
createWorkflowLesson: (workflowId: string, content: string) => Promise<Api.AppLesson>;
|
|
546
|
+
createWorkflowLesson: (workflowId: string, content: string, options?: ChangeOptions) => Promise<Api.AppLesson>;
|
|
180
547
|
/** Pass the `edit_revision` the card gave; a save made meanwhile is
|
|
181
|
-
* refused rather than overwritten.
|
|
182
|
-
|
|
548
|
+
* refused rather than overwritten. Only a viewer who can edit the
|
|
549
|
+
* workflow may reword its lessons. */
|
|
550
|
+
updateLesson: (lessonId: string, content: string, editRevision: string, options?: ChangeOptions) => Promise<Api.AppLesson>;
|
|
551
|
+
/** Sends the person using the app a card that Alma draws itself, in
|
|
552
|
+
* their Home, where this app's own screen never goes: a `metric` is a number with its label, a `row` one thing as a
|
|
553
|
+
* line, a `field` a label and its text, and an `action` a button that
|
|
554
|
+
* opens this app at one of its own paths ("/queue"). It needs no scope
|
|
555
|
+
* and reaches nobody else; an app may publish a few a day to one
|
|
556
|
+
* person, so publish one card with more on it rather than many. */
|
|
557
|
+
publishCard: (card: Api.AppCard) => Promise<Api.AppCardPublished>;
|
|
558
|
+
/** Raises one of the events this app's manifest declares (`events`),
|
|
559
|
+
* which needs the `events:raise` scope. Every workflow in the workspace
|
|
560
|
+
* that starts on this app's event of that name starts, as the workflow,
|
|
561
|
+
* with `payload` as data it does not trust. The answer is the same
|
|
562
|
+
* whether or not a workflow listens. An event the shared version does
|
|
563
|
+
* not declare rejects with `event.undeclared`; past the app's events for
|
|
564
|
+
* the hour, with `event.rate_limited` and when to try again. */
|
|
565
|
+
raiseEvent: (event: string, payload?: Record<string, unknown>, options?: ChangeOptions) => Promise<Api.AppEventRaised>;
|
|
183
566
|
/** This app's own state for its viewer: a small store for what only
|
|
184
567
|
* this person's screen of this app needs between visits, such as a
|
|
185
568
|
* filter, a collapsed column or a half-written draft. It needs no scope
|
|
@@ -193,6 +576,78 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
193
576
|
set: (key: string, value: unknown) => Promise<void>;
|
|
194
577
|
delete: (key: string) => Promise<void>;
|
|
195
578
|
};
|
|
579
|
+
/** The app's shared state: one small store per installation that
|
|
580
|
+
* everyone who can open the app reads and writes together, such as a
|
|
581
|
+
* board's column order, a vote, or whose turn it is. It needs the
|
|
582
|
+
* `shared_state:write` scope, and a change reaches every open copy of
|
|
583
|
+
* the app within a second or two (`watch`). Something a workflow, Alma
|
|
584
|
+
* or a search should see belongs in a record instead. Keys are letters,
|
|
585
|
+
* digits, `_` and `-`; values are any JSON, within a size limit, and an
|
|
586
|
+
* installation has a key limit and a write rate its viewers share,
|
|
587
|
+
* which a `set` past them rejects with. */
|
|
588
|
+
shared: {
|
|
589
|
+
/** A key as it stands: whether it holds a value, the value, and its
|
|
590
|
+
* revision, which is 0 when it holds nothing. */
|
|
591
|
+
get: (key: string) => Promise<Api.AppSharedStateEntry>;
|
|
592
|
+
/** Every key the installation holds. */
|
|
593
|
+
list: () => Promise<Api.AppSharedStateEntry[]>;
|
|
594
|
+
/** Writes a key and answers with it as written. With `ifRevision` it
|
|
595
|
+
* writes only over that revision (0: only where the key holds
|
|
596
|
+
* nothing), and otherwise rejects with an error `isSharedStateConflict`
|
|
597
|
+
* recognizes, whose `current` is the key as it stands. */
|
|
598
|
+
set: (key: string, value: unknown, options?: {
|
|
599
|
+
ifRevision?: number;
|
|
600
|
+
}) => Promise<Api.AppSharedStateEntry>;
|
|
601
|
+
delete: (key: string) => Promise<Api.AppSharedStateEntry>;
|
|
602
|
+
/**
|
|
603
|
+
* Calls `listener` with every key the installation holds, then with
|
|
604
|
+
* each key as it changes, whoever changed it, and with `exists: false`
|
|
605
|
+
* for a key deleted. A key is told once per revision, never an older
|
|
606
|
+
* one after a newer.
|
|
607
|
+
*
|
|
608
|
+
* Where the host tells changes, a change arrives with its value as it
|
|
609
|
+
* is written; where the workspace keeps values off the push, the SDK
|
|
610
|
+
* reads the key first. Every key is read again every five minutes, and
|
|
611
|
+
* whenever the host may have missed a change. Where the host tells
|
|
612
|
+
* nothing (a host from before it, or a channel the server refuses), the
|
|
613
|
+
* SDK polls on `intervalMs` (default 5 seconds, doubling to a minute
|
|
614
|
+
* while nothing changes). Returns the unsubscribe.
|
|
615
|
+
*/
|
|
616
|
+
watch: (listener: (entry: Api.AppSharedStateEntry) => void, options?: {
|
|
617
|
+
intervalMs?: number;
|
|
618
|
+
}) => (() => void);
|
|
619
|
+
};
|
|
620
|
+
/** Who else is here: everyone with this installation open right now. */
|
|
621
|
+
presence: {
|
|
622
|
+
/**
|
|
623
|
+
* Calls `listener` with who has the app open, at once where the host
|
|
624
|
+
* already knows, and again within a second or two of anyone opening or
|
|
625
|
+
* closing it. Names come only to an app that declares `viewer:read`.
|
|
626
|
+
* Where the host tells nothing (a host from before it, or a channel the
|
|
627
|
+
* server refuses), `listener` is never called. Returns the unsubscribe.
|
|
628
|
+
*/
|
|
629
|
+
watch: (listener: (presence: AppPresence) => void) => (() => void);
|
|
630
|
+
};
|
|
631
|
+
/**
|
|
632
|
+
* Sends a quick message to everyone with this installation open: a
|
|
633
|
+
* cursor, a ping, a reaction. It reaches each open copy's `onBroadcast`
|
|
634
|
+
* listeners for `event` within about a second and is never stored, so a
|
|
635
|
+
* copy that opens later never hears it; keep what it needs in `shared`.
|
|
636
|
+
* Needs `shared_state:write`. A payload over 8 KiB of JSON, or more than
|
|
637
|
+
* 10 messages a second after a burst of 20, rejects with an
|
|
638
|
+
* `AppCallError` whose `code` says which.
|
|
639
|
+
*/
|
|
640
|
+
broadcast: (event: string, payload?: unknown) => Promise<void>;
|
|
641
|
+
/**
|
|
642
|
+
* Calls `listener` with the payload of each quick message sent for
|
|
643
|
+
* `event` while the app is open. Messages this copy sent are left out
|
|
644
|
+
* unless `self` is set. Where the host tells nothing (a host from before
|
|
645
|
+
* it, an app without `shared_state:write`, or a channel the server
|
|
646
|
+
* refuses), `listener` is never called. Returns the unsubscribe.
|
|
647
|
+
*/
|
|
648
|
+
onBroadcast: (event: string, listener: (payload: unknown) => void, options?: {
|
|
649
|
+
self?: boolean;
|
|
650
|
+
}) => (() => void);
|
|
196
651
|
listOutcomes: (page?: {
|
|
197
652
|
limit?: number;
|
|
198
653
|
offset?: number;
|
|
@@ -200,7 +655,14 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
200
655
|
data: Api.AppOutcome[];
|
|
201
656
|
meta: Api.PageMeta;
|
|
202
657
|
}>;
|
|
203
|
-
/**
|
|
204
|
-
|
|
658
|
+
/** What changed in a record since its viewer last looked at it in this
|
|
659
|
+
* app. `mark` notes a record as they see it now (from `getTopicRecord`
|
|
660
|
+
* or `listTopics`); `changes` answers with the fields whose value moved
|
|
661
|
+
* since, or null for a record they never looked at. It lasts between
|
|
662
|
+
* visits and is theirs alone, kept in the app's own state for them. */
|
|
663
|
+
lastLooked: {
|
|
664
|
+
changes: (record: LookedRecord) => Promise<string[] | null>;
|
|
665
|
+
mark: (record: LookedRecord) => Promise<void>;
|
|
666
|
+
};
|
|
205
667
|
};
|
|
206
668
|
export declare function hostTransport(): AppTransport;
|