@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/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. A field filter is
5
- * `<field>:<op>:<value>` (op: eq, ne, lt, lte, gt, gte, contains), and a
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 getOrganizationAnalytics: "read";
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
- idempotencyKey?: string;
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
- /** Creates a record as the viewer. Who can see it is the viewer's
149
- * choice in Alma's own access sheet, never the app's. */
150
- createTopic: (name: string, topicTypeId?: string) => Promise<Api.CreatedTopicRecord>;
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 as the viewer. Nobody is
155
- * asked: it starts where they may run it and, on a record, edit that
156
- * record, and rejects with the refusal's words otherwise. */
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
- /** Propose a lesson for the workflow's later runs. It resolves with
176
- * `active: false` and applies once someone who can edit the workflow
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
- updateLesson: (lessonId: string, content: string, editRevision: string) => Promise<Api.AppLesson>;
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
- /** Alma's own package only, on an installation granted `analytics:org`. */
204
- getOrganizationAnalytics: () => Promise<Api.OrganizationAnalytics>;
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;