@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.
@@ -1,12 +1,39 @@
1
- export interface AnalyticsEconomics {
2
- hands: number;
3
- meetings: number;
4
- reporting: number;
5
- duplicates: number;
6
- saas: number;
7
- baseline: number;
8
- run_cost: number;
9
- net: number;
1
+ export interface AppBroadcastSent {
2
+ sent: true;
3
+ }
4
+ /**
5
+ * A card for the app's viewer: a title and a flat list of blocks Alma
6
+ * draws itself in their Home. A `metric` is a number with its label, a
7
+ * `row` one thing as a line, a `field` a label and its text, and an
8
+ * `action` a button that opens the app at one of its own paths.
9
+ */
10
+ export interface AppCard {
11
+ title: string;
12
+ blocks: ({
13
+ type: "metric";
14
+ label: string;
15
+ value: number | string;
16
+ } | {
17
+ type: "row";
18
+ title: string;
19
+ subtitle?: string;
20
+ note?: string;
21
+ } | {
22
+ type: "field";
23
+ label: string;
24
+ value: string;
25
+ } | {
26
+ type: "action";
27
+ label: string;
28
+ path: string;
29
+ })[];
30
+ }
31
+ export interface AppCardPublished {
32
+ id: string;
33
+ }
34
+ export interface AppEventRaised {
35
+ event: string;
36
+ raised_at: string;
10
37
  }
11
38
  /** A run as the viewer who may read it reads it from an app. */
12
39
  export interface AppExecution {
@@ -17,6 +44,10 @@ export interface AppExecution {
17
44
  /** `waiting`: paused on people, whom `approvers` names. */
18
45
  status: "pending" | "running" | "waiting" | "completed" | "failed" | "cancelled";
19
46
  trigger_type: string;
47
+ /**
48
+ * What the run delivered, for the workflow's owners and editors. For
49
+ * anyone else who started it, the report the run submitted.
50
+ */
20
51
  response_content: string | null;
21
52
  /** Why it failed, in words the app may show. */
22
53
  error: string | null;
@@ -25,6 +56,12 @@ export interface AppExecution {
25
56
  id: string;
26
57
  name: string;
27
58
  }[];
59
+ /**
60
+ * What the run's writes to the record it was started on did, oldest first;
61
+ * empty for a run that made none. A run that `completed` did not
62
+ * necessarily change the record: read this, not `response_content`.
63
+ */
64
+ field_writes: AppRunFieldWrite[];
28
65
  started_at: string | null;
29
66
  completed_at: string | null;
30
67
  created_at: string;
@@ -59,6 +96,35 @@ export interface AppOutcome {
59
96
  /** Active workflows serving it that the viewer can open. */
60
97
  live_workflow_count: number;
61
98
  }
99
+ /**
100
+ * What one write by a run to the record it was started on did, read from
101
+ * the run's call ledger and not from what the run reported.
102
+ */
103
+ export interface AppRunFieldWrite {
104
+ field_key: string;
105
+ /**
106
+ * `applied`: the record holds the value. `proposed`: the record asks
107
+ * before updating, so the value is waiting for its reviewers and the
108
+ * record is unchanged; show it as awaiting review, never as done.
109
+ * `unchanged`: the record already held it. `refused`: nothing was written,
110
+ * and `refusal` says why. `unknown`: the write may have completed; read
111
+ * the record before repeating it.
112
+ */
113
+ outcome: "applied" | "proposed" | "unchanged" | "refused" | "unknown";
114
+ /**
115
+ * The value as the record stores it, on `applied` and `unchanged`, where
116
+ * the viewer can read the record. Never set on `proposed`.
117
+ */
118
+ value?: string;
119
+ /** With `value`: the field's revision after the write. */
120
+ revision?: string;
121
+ /** On `refused`: a stable code and a sentence to show as it is. */
122
+ refusal?: {
123
+ code: string;
124
+ reason: string;
125
+ };
126
+ at: string;
127
+ }
62
128
  /** A run an app started, as it started: poll `getExecution` with its `id`. */
63
129
  export interface AppRunReceipt {
64
130
  id: string;
@@ -66,6 +132,23 @@ export interface AppRunReceipt {
66
132
  status: string;
67
133
  created_at: string;
68
134
  }
135
+ /**
136
+ * One key of an installation's shared state: what everyone who can open
137
+ * the app reads and writes together.
138
+ */
139
+ export interface AppSharedStateEntry {
140
+ key: string;
141
+ /** Whether the key holds a value; one never set, or deleted, does not. */
142
+ exists: boolean;
143
+ /** The stored JSON; null when the key holds nothing. */
144
+ value: unknown;
145
+ /**
146
+ * The installation's revision when this value was written; 0 when the key
147
+ * holds nothing. Send it back as `if_revision` to write only over this
148
+ * value.
149
+ */
150
+ revision: number;
151
+ }
69
152
  /**
70
153
  * One key of an app's own state for its viewer: what only that person's
71
154
  * screen of that app needs between visits.
@@ -88,6 +171,18 @@ export interface AppTopicRecord {
88
171
  */
89
172
  revisions: Record<string, string>;
90
173
  }
174
+ /** A topic's page as its viewer reads it. */
175
+ export interface AppTopicSummary {
176
+ topic_id: string;
177
+ /**
178
+ * The page's markdown as the viewer reads it, with every passage about a
179
+ * property they may not read left out. Null before the topic has a page
180
+ * they can read.
181
+ */
182
+ content: string | null;
183
+ /** When the page's current revision was written. */
184
+ generated_at: string | null;
185
+ }
91
186
  /**
92
187
  * A row of the member Workflows list: a workflow the viewer reads the card
93
188
  * of, or one the app's manifest names that the viewer may start.
@@ -112,7 +207,7 @@ export interface AppWorkflowSummary {
112
207
  * must also be able to edit that record (its `can_edit`).
113
208
  */
114
209
  not_runnable?: {
115
- code: "workflow.off" | "app.not_in_audience";
210
+ code: "workflow.off" | "workflow.not_active" | "app.not_in_audience" | "workflow.not_granted";
116
211
  reason: string;
117
212
  };
118
213
  /** The facts the Workflows list sorts and filters by. */
@@ -135,10 +230,65 @@ export interface AppWorkflowSummary {
135
230
  };
136
231
  };
137
232
  }
233
+ export interface ClearTopicField {
234
+ /**
235
+ * What you read: the field's revision, from a record's `revisions` or an
236
+ * earlier receipt's `revision`. The clear is refused with `field.changed`
237
+ * if the field has changed since. Send this or `if_value`: a clear that
238
+ * sends neither is refused.
239
+ */
240
+ if_revision?: string;
241
+ /**
242
+ * What you read, by value: a value the field held (its `text` as read), or
243
+ * null if it held nothing. Refused with `field.changed` if it no longer
244
+ * does.
245
+ */
246
+ if_value?: string | null;
247
+ }
248
+ export interface CreateLesson {
249
+ content: string;
250
+ category?: string;
251
+ topic_id?: string;
252
+ workflow_id?: string;
253
+ }
254
+ export interface CreateTopic {
255
+ name: string;
256
+ description?: string;
257
+ icon?: string;
258
+ topic_type_id?: string;
259
+ access?: {
260
+ mode: "inherit" | "everyone";
261
+ everyone_level?: "read" | "read_write";
262
+ grants?: {
263
+ /** `person:<user id>` or `group:<group id>` */
264
+ subject: string;
265
+ level?: "read" | "read_write";
266
+ }[];
267
+ };
268
+ /**
269
+ * App sessions only. The record's first values, saved with it or not at
270
+ * all.
271
+ */
272
+ fields?: {
273
+ key: string;
274
+ value: string;
275
+ ref_topic_id?: string | null;
276
+ }[];
277
+ }
138
278
  export interface CreatedTopicRecord {
139
279
  id: string;
140
280
  name: string;
141
281
  topic_type_id: string | null;
282
+ /** Only when the request carried `fields`. */
283
+ values?: Record<string, {
284
+ text: string;
285
+ typed: TypedValue | null;
286
+ }[]>;
287
+ /**
288
+ * Only when the request carried `fields`: what a later write of each field
289
+ * names as `if_revision`.
290
+ */
291
+ revisions?: Record<string, string>;
142
292
  }
143
293
  /**
144
294
  * A value: its text as written, its typed reading where its field's type
@@ -166,40 +316,18 @@ export interface KnowledgeRecord {
166
316
  /** Whether the viewer may edit this topic's values. */
167
317
  viewer_can_edit: boolean;
168
318
  }
169
- export interface OrganizationAnalytics {
170
- coverage: {
171
- sources: {
172
- slug: string;
173
- name: string;
174
- connected: boolean;
175
- }[];
176
- members_invited: number;
177
- members_connected: number;
178
- requested_sources: {
179
- name: string;
180
- }[];
181
- };
182
- outcomes: {
183
- committed: number;
184
- automated: number;
185
- blind_spots: number;
186
- };
187
- workflows: {
188
- operating: number;
189
- in_build: number;
190
- waiting_on_people: number;
191
- };
192
- roi: {
193
- operating_workflows: number;
194
- pending_workflows: number;
195
- realized: AnalyticsEconomics;
196
- potential_net: number;
197
- hidden_priced_count: number;
198
- } | null;
199
- }
200
319
  export interface PageMeta {
201
320
  hasMore: boolean;
202
321
  }
322
+ export interface RaiseAppEvent {
323
+ /** One of the events the app's shared version declares. */
324
+ event: string;
325
+ /**
326
+ * What happened, as a JSON object of at most 16384 bytes. Each workflow it
327
+ * starts reads it as untrusted data.
328
+ */
329
+ payload?: Record<string, unknown>;
330
+ }
203
331
  /** Who a record reaches, as its sharing mark says it — never the roster. */
204
332
  export interface RecordAudience {
205
333
  scope: "everyone" | "tier" | "restricted";
@@ -240,6 +368,123 @@ export interface RecordUpdate {
240
368
  count?: number;
241
369
  edited?: boolean;
242
370
  }
371
+ export interface ReferencingTopicRecord {
372
+ id: string;
373
+ name: string;
374
+ slug: string;
375
+ icon: string | null;
376
+ status: string;
377
+ type: {
378
+ key: string;
379
+ name: string;
380
+ icon: string | null;
381
+ } | null;
382
+ values: Record<string, FactValue[]>;
383
+ /**
384
+ * Each field's revision, by field key, for every field that holds a value.
385
+ * Send it back as `if_revision` when writing that field; a field absent
386
+ * here holds nothing (`if_value: null`).
387
+ */
388
+ revisions: Record<string, string>;
389
+ unverified_value_count: number;
390
+ can_edit: boolean;
391
+ created_at: string;
392
+ updated_at: string;
393
+ via: string[];
394
+ }
395
+ export interface RelatedTopicRecord {
396
+ id: string;
397
+ name: string;
398
+ slug: string;
399
+ icon: string | null;
400
+ status: string;
401
+ type: {
402
+ key: string;
403
+ name: string;
404
+ icon: string | null;
405
+ } | null;
406
+ values: Record<string, FactValue[]>;
407
+ /**
408
+ * Each field's revision, by field key, for every field that holds a value.
409
+ * Send it back as `if_revision` when writing that field; a field absent
410
+ * here holds nothing (`if_value: null`).
411
+ */
412
+ revisions: Record<string, string>;
413
+ unverified_value_count: number;
414
+ can_edit: boolean;
415
+ created_at: string;
416
+ updated_at: string;
417
+ depth: number;
418
+ via: {
419
+ from_id: string;
420
+ field: string;
421
+ direction: "out" | "in";
422
+ };
423
+ }
424
+ export interface RestoredTopicRecord {
425
+ id: string;
426
+ name: string;
427
+ /**
428
+ * Values that did not come back, because they no longer fit the record's
429
+ * type.
430
+ */
431
+ cleared: {
432
+ field_key: string;
433
+ value: string;
434
+ }[];
435
+ }
436
+ export interface SendAppBroadcast {
437
+ /** What the message is, for listeners to pick out: `cursor`, `ping`. */
438
+ event: string;
439
+ /** Any JSON value, at most 8192 bytes; null when left out. */
440
+ payload?: unknown;
441
+ /**
442
+ * Set by the Alma host: names the open copy that sent the message, so that
443
+ * copy can skip its own.
444
+ */
445
+ origin?: string;
446
+ }
447
+ export interface SetAppSharedState {
448
+ /** Any JSON value. */
449
+ value: unknown;
450
+ /**
451
+ * Write only when the key still holds this revision; 0 writes only when it
452
+ * holds nothing. Without it the write is unconditional.
453
+ */
454
+ if_revision?: number;
455
+ }
456
+ export interface SetAppState {
457
+ /** Any JSON value. */
458
+ value: unknown;
459
+ }
460
+ export interface SetTopicField {
461
+ value: string;
462
+ /** On a relationship: the topic the value refers to. */
463
+ ref_topic_id?: string | null;
464
+ /**
465
+ * What you read: the field's revision, from a record's `revisions` or an
466
+ * earlier receipt's `revision`. The write is refused with `field.changed`
467
+ * if the field has changed since. Send this or `if_value`: a write that
468
+ * sends neither is refused.
469
+ */
470
+ if_revision?: string;
471
+ /**
472
+ * What you read, by value: a value the field held (its `text` as read), or
473
+ * null if it held nothing. Refused with `field.changed` if it no longer
474
+ * does.
475
+ */
476
+ if_value?: string | null;
477
+ }
478
+ export interface TopicCountBucket {
479
+ key: {
480
+ value: string;
481
+ } | {
482
+ id: string;
483
+ name: string;
484
+ type: string | null;
485
+ };
486
+ count: number;
487
+ }
243
488
  export interface TopicDiscussion {
244
489
  topic_id: string;
245
490
  fact_id: string;
@@ -285,6 +530,27 @@ export interface TopicFact {
285
530
  value: FactValue;
286
531
  verified_at: string | null;
287
532
  }
533
+ export interface TopicFieldClearReceipt {
534
+ /** `cleared` emptied the field; `unchanged` found it already empty. */
535
+ outcome: "cleared" | "unchanged";
536
+ topic_id: string;
537
+ field_key: string;
538
+ /**
539
+ * The field's revision once it stood empty: the `if_revision` of the next
540
+ * write.
541
+ */
542
+ revision: string;
543
+ applied_at: string;
544
+ /** The call ledger row that records this clear. */
545
+ call_id: string | null;
546
+ /**
547
+ * On a retry under the same Idempotency-Key: the field has changed since
548
+ * this clear, and nothing was cleared again.
549
+ */
550
+ superseded?: true;
551
+ /** With `superseded`: the field's revision now. */
552
+ current_revision?: string;
553
+ }
288
554
  export interface TopicFieldHistory {
289
555
  topic_id: string;
290
556
  field_key: string;
@@ -297,7 +563,10 @@ export interface TopicFieldHistoryEntry {
297
563
  value_json: TypedValue | null;
298
564
  /**
299
565
  * Who or what a history line names: a person (named where the viewer can
300
- * still resolve them), Alma, or a workflow's run.
566
+ * still resolve them), Alma, a workflow's run (the workflow named where
567
+ * the viewer can read the run and the workflow; otherwise `name` is null),
568
+ * or `computed`, a value a smart property's plan computed from the rest of
569
+ * the record.
301
570
  */
302
571
  written_by: {
303
572
  kind: "person";
@@ -306,6 +575,9 @@ export interface TopicFieldHistoryEntry {
306
575
  kind: "alma";
307
576
  } | {
308
577
  kind: "workflow";
578
+ name: string | null;
579
+ } | {
580
+ kind: "computed";
309
581
  };
310
582
  /** Who had confirmed the value while it stood. */
311
583
  verified_by: {
@@ -313,7 +585,7 @@ export interface TopicFieldHistoryEntry {
313
585
  at: string;
314
586
  } | null;
315
587
  /** Why the value stopped standing. */
316
- reason: "corrected" | "superseded" | "retracted" | "rejected" | "moved" | "unattributed";
588
+ reason: "corrected" | "superseded" | "retracted" | "rejected" | "moved" | "merged" | "unattributed";
317
589
  /** The preset a person gave for removing it, when they gave one. */
318
590
  rejection_reason: "wrong_entity" | "inaccurate" | "irrelevant" | "duplicate" | null;
319
591
  /** Who or what made the change; null when no writer declared itself. */
@@ -324,6 +596,9 @@ export interface TopicFieldHistoryEntry {
324
596
  kind: "alma";
325
597
  } | {
326
598
  kind: "workflow";
599
+ name: string | null;
600
+ } | {
601
+ kind: "computed";
327
602
  } | null;
328
603
  /** What took its place, when something did. */
329
604
  replaced_by_value: string | null;
@@ -365,8 +640,6 @@ export interface TopicRecord {
365
640
  slug: string;
366
641
  icon: string | null;
367
642
  status: string;
368
- parent_id: string | null;
369
- folder_id: string | null;
370
643
  type: {
371
644
  key: string;
372
645
  name: string;
@@ -394,6 +667,14 @@ export interface TopicType {
394
667
  name: string;
395
668
  icon: string | null;
396
669
  description: string;
670
+ schema: {
671
+ id: string;
672
+ kind: "workspace" | "app";
673
+ };
674
+ app: {
675
+ id: string;
676
+ name: string;
677
+ } | null;
397
678
  fields: {
398
679
  key: string;
399
680
  name: string;
@@ -410,6 +691,15 @@ export interface TopicType {
410
691
  holds: "one" | "many";
411
692
  }[];
412
693
  }
694
+ export interface TypeView {
695
+ key: string;
696
+ name: string;
697
+ scope: "shared" | "personal";
698
+ }
699
+ export interface TypeViewGroup {
700
+ value: string | null;
701
+ count: number;
702
+ }
413
703
  export type TypedValue = {
414
704
  type: "date";
415
705
  value: string;
@@ -424,6 +714,11 @@ export type TypedValue = {
424
714
  type: "choice";
425
715
  value: string;
426
716
  };
717
+ export interface UpdateLesson {
718
+ content?: string;
719
+ category?: string;
720
+ active?: boolean;
721
+ }
427
722
  export interface ValueDetail {
428
723
  label: string;
429
724
  value: string;
@@ -445,7 +740,8 @@ export interface WorkflowCard {
445
740
  name: string;
446
741
  does?: string;
447
742
  trigger?: string;
448
- sources: string[];
743
+ /** The integrations the workflow's tools act in, by name, sorted. */
744
+ tools: string[];
449
745
  steps: {
450
746
  title: string;
451
747
  }[];
@@ -464,6 +760,7 @@ export interface WorkflowCard {
464
760
  step_name: string;
465
761
  provider: string;
466
762
  owner_user_id: string | null;
763
+ connection_catalog_id?: string;
467
764
  account_name: string;
468
765
  reason: "missing" | "expired" | "revoked" | "identity_unverified" | "account_unavailable" | "credential_missing" | "scope_missing" | "requester_required";
469
766
  }[];
@@ -485,8 +782,8 @@ export interface WorkflowRun {
485
782
  outcome: WorkflowRunOutcome;
486
783
  /** Present only where the viewer can open every topic the run touched. */
487
784
  summary?: string;
488
- /** The viewer's own open Task on this run. */
489
- task_id?: string;
785
+ /** The viewer's own open Tasks on this run, newest first. */
786
+ task_ids?: string[];
490
787
  }
491
788
  export type WorkflowRunOutcome = "ran" | "edited" | "skipped" | "failed" | "running" | "waiting";
492
789
  export interface WorkflowTopic {
@@ -502,20 +799,98 @@ export interface AppOperationResults {
502
799
  data: TopicRecord[];
503
800
  meta: {
504
801
  next_cursor: string | null;
802
+ /**
803
+ * The type `type` named, null when the query named none. Present on an
804
+ * empty page too, so a reader can listen for the type's records before it
805
+ * has any.
806
+ */
807
+ type_id: string | null;
505
808
  };
506
809
  };
507
810
  /** Create a topic */
508
811
  createTopic: CreatedTopicRecord;
812
+ /** Delete a topic */
813
+ deleteTopic: {
814
+ success: boolean;
815
+ };
816
+ /** Restore a deleted record */
817
+ restoreTopic: RestoredTopicRecord;
509
818
  /** Read the field contract */
510
819
  listTopicTypes: TopicType[];
511
820
  /** Get a topic's record */
512
821
  getTopicRecord: AppTopicRecord;
822
+ /** List a type's saved views */
823
+ listViews: TypeView[];
824
+ /** Read a page of a saved view */
825
+ readView: {
826
+ data: TopicRecord[];
827
+ meta: {
828
+ next_cursor: string | null;
829
+ total: number;
830
+ groups?: TypeViewGroup[];
831
+ };
832
+ };
833
+ /** List the records that name a record */
834
+ listTopicReferences: {
835
+ data: ReferencingTopicRecord[];
836
+ meta: {
837
+ target: {
838
+ id: string;
839
+ name: string;
840
+ };
841
+ counts: {
842
+ type: string | null;
843
+ field: string;
844
+ n: number;
845
+ }[];
846
+ next_cursor: string | null;
847
+ complete: boolean;
848
+ };
849
+ };
850
+ /** Count a type's records */
851
+ countTopics: {
852
+ data: TopicCountBucket[];
853
+ meta: {
854
+ total: number;
855
+ other: number;
856
+ truncated_buckets: number;
857
+ complete: boolean;
858
+ incomplete_reason: "bucket_limit" | null;
859
+ };
860
+ };
861
+ /** List the records related to a record */
862
+ listRelatedTopics: {
863
+ data: RelatedTopicRecord[];
864
+ meta: {
865
+ start: {
866
+ id: string;
867
+ name: string;
868
+ };
869
+ counts: {
870
+ type: string | null;
871
+ n: number;
872
+ }[];
873
+ unresolved: {
874
+ from_id: string;
875
+ field: string;
876
+ text: string;
877
+ }[];
878
+ unresolved_truncated: boolean;
879
+ next_cursor: string | null;
880
+ complete: boolean;
881
+ incomplete_reason: "depth" | "budget" | null;
882
+ };
883
+ };
513
884
  /** Get a field's earlier values */
514
885
  getTopicFieldHistory: TopicFieldHistory;
886
+ /** Get a topic's rendered summary document */
887
+ getTopicSummary: AppTopicSummary;
515
888
  /** Get the discussion about a value */
516
889
  getTopicFactDiscussion: AppFactDiscussion;
517
890
  /** Set a field's value */
518
891
  setTopicField: TopicFieldReceipt;
892
+ /** Clear a field's values */
893
+ clearTopicField: TopicFieldClearReceipt;
519
894
  /** List workflows */
520
895
  listWorkflows: AppWorkflowSummary[];
521
896
  /** Read a workflow as a member reads it */
@@ -535,12 +910,24 @@ export interface AppOperationResults {
535
910
  data: AppOutcome[];
536
911
  meta: PageMeta;
537
912
  };
538
- /** Get the organization's defined aggregates */
539
- getOrganizationAnalytics: OrganizationAnalytics;
540
913
  /** Read a key of the app's state */
541
914
  getAppState: AppStateEntry;
915
+ /** Publish a card to the app's viewer */
916
+ publishCard: AppCardPublished;
542
917
  /** Set a key of the app's state */
543
918
  setAppState: AppStateEntry;
544
919
  /** Delete a key of the app's state */
545
920
  deleteAppState: AppStateEntry;
921
+ /** List the app's shared state */
922
+ listAppSharedState: AppSharedStateEntry[];
923
+ /** Read a key of the app's shared state */
924
+ getAppSharedState: AppSharedStateEntry;
925
+ /** Set a key of the app's shared state */
926
+ setAppSharedState: AppSharedStateEntry;
927
+ /** Delete a key of the app's shared state */
928
+ deleteAppSharedState: AppSharedStateEntry;
929
+ /** Send a quick message to everyone with the app open */
930
+ sendAppBroadcast: AppBroadcastSent;
931
+ /** Raise one of the app's events */
932
+ raiseAppEvent: AppEventRaised;
546
933
  }