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