@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.
@@ -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 {
@@ -22,6 +49,12 @@ export interface AppExecution {
22
49
  * anyone else who started it, the report the run submitted.
23
50
  */
24
51
  response_content: string | null;
52
+ /**
53
+ * The JSON the run's last step returned, when that step ran as code and
54
+ * its program finished it; null otherwise, and when it came to more than
55
+ * 64 KB. Read as `response_content` is, and withheld with it.
56
+ */
57
+ result: unknown | null;
25
58
  /** Why it failed, in words the app may show. */
26
59
  error: string | null;
27
60
  /** Empty when anyone in the workspace may decide. */
@@ -55,20 +88,6 @@ export interface AppLesson {
55
88
  /** Pass it back as `expected_revision` on the next save. */
56
89
  edit_revision: string;
57
90
  }
58
- export interface AppOutcome {
59
- id: string;
60
- name: string;
61
- description: string | null;
62
- signal: string | null;
63
- parent_outcome_id: string | null;
64
- status: string;
65
- created_at: string;
66
- updated_at: string;
67
- /** The groups that own it, as the viewer reads them. */
68
- owning_groups: string[];
69
- /** Active workflows serving it that the viewer can open. */
70
- live_workflow_count: number;
71
- }
72
91
  /**
73
92
  * What one write by a run to the record it was started on did, read from
74
93
  * the run's call ledger and not from what the run reported.
@@ -84,8 +103,6 @@ export interface AppRunFieldWrite {
84
103
  * the record before repeating it.
85
104
  */
86
105
  outcome: "applied" | "proposed" | "unchanged" | "refused" | "unknown";
87
- /** The run had already made this write, and the field has changed since. */
88
- superseded?: true;
89
106
  /**
90
107
  * The value as the record stores it, on `applied` and `unchanged`, where
91
108
  * the viewer can read the record. Never set on `proposed`.
@@ -107,6 +124,23 @@ export interface AppRunReceipt {
107
124
  status: string;
108
125
  created_at: string;
109
126
  }
127
+ /**
128
+ * One key of an installation's shared state: what everyone who can open
129
+ * the app reads and writes together.
130
+ */
131
+ export interface AppSharedStateEntry {
132
+ key: string;
133
+ /** Whether the key holds a value; one never set, or deleted, does not. */
134
+ exists: boolean;
135
+ /** The stored JSON; null when the key holds nothing. */
136
+ value: unknown;
137
+ /**
138
+ * The installation's revision when this value was written; 0 when the key
139
+ * holds nothing. Send it back as `if_revision` to write only over this
140
+ * value.
141
+ */
142
+ revision: number;
143
+ }
110
144
  /**
111
145
  * One key of an app's own state for its viewer: what only that person's
112
146
  * screen of that app needs between visits.
@@ -129,6 +163,18 @@ export interface AppTopicRecord {
129
163
  */
130
164
  revisions: Record<string, string>;
131
165
  }
166
+ /** A topic's page as its viewer reads it. */
167
+ export interface AppTopicSummary {
168
+ topic_id: string;
169
+ /**
170
+ * The page's markdown as the viewer reads it, with every passage about a
171
+ * property they may not read left out. Null before the topic has a page
172
+ * they can read.
173
+ */
174
+ content: string | null;
175
+ /** When the page's current revision was written. */
176
+ generated_at: string | null;
177
+ }
132
178
  /**
133
179
  * A row of the member Workflows list: a workflow the viewer reads the card
134
180
  * of, or one the app's manifest names that the viewer may start.
@@ -176,10 +222,65 @@ export interface AppWorkflowSummary {
176
222
  };
177
223
  };
178
224
  }
225
+ export interface ClearTopicField {
226
+ /**
227
+ * What you read: the field's revision, from a record's `revisions` or an
228
+ * earlier receipt's `revision`. The clear is refused with `field.changed`
229
+ * if the field has changed since. Send this or `if_value`: a clear that
230
+ * sends neither is refused.
231
+ */
232
+ if_revision?: string;
233
+ /**
234
+ * What you read, by value: a value the field held (its `text` as read), or
235
+ * null if it held nothing. Refused with `field.changed` if it no longer
236
+ * does.
237
+ */
238
+ if_value?: string | null;
239
+ }
240
+ export interface CreateLesson {
241
+ content: string;
242
+ category?: string;
243
+ topic_id?: string;
244
+ workflow_id?: string;
245
+ }
246
+ export interface CreateTopic {
247
+ name: string;
248
+ description?: string;
249
+ icon?: string;
250
+ topic_type_id?: string;
251
+ access?: {
252
+ mode: "inherit" | "everyone";
253
+ everyone_level?: "read" | "read_write";
254
+ grants?: {
255
+ /** `person:<user id>` or `group:<group id>` */
256
+ subject: string;
257
+ level?: "read" | "read_write";
258
+ }[];
259
+ };
260
+ /**
261
+ * App sessions only. The record's first values, saved with it or not at
262
+ * all.
263
+ */
264
+ fields?: {
265
+ key: string;
266
+ value: string;
267
+ ref_topic_id?: string | null;
268
+ }[];
269
+ }
179
270
  export interface CreatedTopicRecord {
180
271
  id: string;
181
272
  name: string;
182
273
  topic_type_id: string | null;
274
+ /** Only when the request carried `fields`. */
275
+ values?: Record<string, {
276
+ text: string;
277
+ typed: TypedValue | null;
278
+ }[]>;
279
+ /**
280
+ * Only when the request carried `fields`: what a later write of each field
281
+ * names as `if_revision`.
282
+ */
283
+ revisions?: Record<string, string>;
183
284
  }
184
285
  /**
185
286
  * A value: its text as written, its typed reading where its field's type
@@ -207,39 +308,14 @@ export interface KnowledgeRecord {
207
308
  /** Whether the viewer may edit this topic's values. */
208
309
  viewer_can_edit: boolean;
209
310
  }
210
- export interface OrganizationAnalytics {
211
- coverage: {
212
- sources: {
213
- slug: string;
214
- name: string;
215
- connected: boolean;
216
- }[];
217
- members_invited: number;
218
- members_connected: number;
219
- requested_sources: {
220
- name: string;
221
- }[];
222
- };
223
- outcomes: {
224
- committed: number;
225
- automated: number;
226
- blind_spots: number;
227
- };
228
- workflows: {
229
- operating: number;
230
- in_build: number;
231
- waiting_on_people: number;
232
- };
233
- roi: {
234
- operating_workflows: number;
235
- pending_workflows: number;
236
- realized: AnalyticsEconomics;
237
- potential_net: number;
238
- hidden_priced_count: number;
239
- } | null;
240
- }
241
- export interface PageMeta {
242
- hasMore: boolean;
311
+ export interface RaiseAppEvent {
312
+ /** One of the events the app's shared version declares. */
313
+ event: string;
314
+ /**
315
+ * What happened, as a JSON object of at most 16384 bytes. Each workflow it
316
+ * starts reads it as untrusted data.
317
+ */
318
+ payload?: Record<string, unknown>;
243
319
  }
244
320
  /** Who a record reaches, as its sharing mark says it — never the roster. */
245
321
  export interface RecordAudience {
@@ -281,6 +357,123 @@ export interface RecordUpdate {
281
357
  count?: number;
282
358
  edited?: boolean;
283
359
  }
360
+ export interface ReferencingTopicRecord {
361
+ id: string;
362
+ name: string;
363
+ slug: string;
364
+ icon: string | null;
365
+ status: string;
366
+ type: {
367
+ key: string;
368
+ name: string;
369
+ icon: string | null;
370
+ } | null;
371
+ values: Record<string, FactValue[]>;
372
+ /**
373
+ * Each field's revision, by field key, for every field that holds a value.
374
+ * Send it back as `if_revision` when writing that field; a field absent
375
+ * here holds nothing (`if_value: null`).
376
+ */
377
+ revisions: Record<string, string>;
378
+ unverified_value_count: number;
379
+ can_edit: boolean;
380
+ created_at: string;
381
+ updated_at: string;
382
+ via: string[];
383
+ }
384
+ export interface RelatedTopicRecord {
385
+ id: string;
386
+ name: string;
387
+ slug: string;
388
+ icon: string | null;
389
+ status: string;
390
+ type: {
391
+ key: string;
392
+ name: string;
393
+ icon: string | null;
394
+ } | null;
395
+ values: Record<string, FactValue[]>;
396
+ /**
397
+ * Each field's revision, by field key, for every field that holds a value.
398
+ * Send it back as `if_revision` when writing that field; a field absent
399
+ * here holds nothing (`if_value: null`).
400
+ */
401
+ revisions: Record<string, string>;
402
+ unverified_value_count: number;
403
+ can_edit: boolean;
404
+ created_at: string;
405
+ updated_at: string;
406
+ depth: number;
407
+ via: {
408
+ from_id: string;
409
+ field: string;
410
+ direction: "out" | "in";
411
+ };
412
+ }
413
+ export interface RestoredTopicRecord {
414
+ id: string;
415
+ name: string;
416
+ /**
417
+ * Values that did not come back, because they no longer fit the record's
418
+ * type.
419
+ */
420
+ cleared: {
421
+ field_key: string;
422
+ value: string;
423
+ }[];
424
+ }
425
+ export interface SendAppBroadcast {
426
+ /** What the message is, for listeners to pick out: `cursor`, `ping`. */
427
+ event: string;
428
+ /** Any JSON value, at most 8192 bytes; null when left out. */
429
+ payload?: unknown;
430
+ /**
431
+ * Set by the Alma host: names the open copy that sent the message, so that
432
+ * copy can skip its own.
433
+ */
434
+ origin?: string;
435
+ }
436
+ export interface SetAppSharedState {
437
+ /** Any JSON value. */
438
+ value: unknown;
439
+ /**
440
+ * Write only when the key still holds this revision; 0 writes only when it
441
+ * holds nothing. Without it the write is unconditional.
442
+ */
443
+ if_revision?: number;
444
+ }
445
+ export interface SetAppState {
446
+ /** Any JSON value. */
447
+ value: unknown;
448
+ }
449
+ export interface SetTopicField {
450
+ value: string;
451
+ /** On a relationship: the topic the value refers to. */
452
+ ref_topic_id?: string | null;
453
+ /**
454
+ * What you read: the field's revision, from a record's `revisions` or an
455
+ * earlier receipt's `revision`. The write is refused with `field.changed`
456
+ * if the field has changed since. Send this or `if_value`: a write that
457
+ * sends neither is refused.
458
+ */
459
+ if_revision?: string;
460
+ /**
461
+ * What you read, by value: a value the field held (its `text` as read), or
462
+ * null if it held nothing. Refused with `field.changed` if it no longer
463
+ * does.
464
+ */
465
+ if_value?: string | null;
466
+ }
467
+ export interface TopicCountBucket {
468
+ key: {
469
+ value: string;
470
+ } | {
471
+ id: string;
472
+ name: string;
473
+ type: string | null;
474
+ };
475
+ count: number;
476
+ }
284
477
  export interface TopicDiscussion {
285
478
  topic_id: string;
286
479
  fact_id: string;
@@ -326,6 +519,27 @@ export interface TopicFact {
326
519
  value: FactValue;
327
520
  verified_at: string | null;
328
521
  }
522
+ export interface TopicFieldClearReceipt {
523
+ /** `cleared` emptied the field; `unchanged` found it already empty. */
524
+ outcome: "cleared" | "unchanged";
525
+ topic_id: string;
526
+ field_key: string;
527
+ /**
528
+ * The field's revision once it stood empty: the `if_revision` of the next
529
+ * write.
530
+ */
531
+ revision: string;
532
+ applied_at: string;
533
+ /** The call ledger row that records this clear. */
534
+ call_id: string | null;
535
+ /**
536
+ * On a retry under the same Idempotency-Key: the field has changed since
537
+ * this clear, and nothing was cleared again.
538
+ */
539
+ superseded?: true;
540
+ /** With `superseded`: the field's revision now. */
541
+ current_revision?: string;
542
+ }
329
543
  export interface TopicFieldHistory {
330
544
  topic_id: string;
331
545
  field_key: string;
@@ -338,8 +552,10 @@ export interface TopicFieldHistoryEntry {
338
552
  value_json: TypedValue | null;
339
553
  /**
340
554
  * Who or what a history line names: a person (named where the viewer can
341
- * still resolve them), Alma, or a workflow's run (the workflow named where
342
- * the viewer can read the run and the workflow; otherwise `name` is null).
555
+ * still resolve them), Alma, a workflow's run (the workflow named where
556
+ * the viewer can read the run and the workflow; otherwise `name` is null),
557
+ * or `computed`, a value a smart property's plan computed from the rest of
558
+ * the record.
343
559
  */
344
560
  written_by: {
345
561
  kind: "person";
@@ -349,6 +565,8 @@ export interface TopicFieldHistoryEntry {
349
565
  } | {
350
566
  kind: "workflow";
351
567
  name: string | null;
568
+ } | {
569
+ kind: "computed";
352
570
  };
353
571
  /** Who had confirmed the value while it stood. */
354
572
  verified_by: {
@@ -368,6 +586,8 @@ export interface TopicFieldHistoryEntry {
368
586
  } | {
369
587
  kind: "workflow";
370
588
  name: string | null;
589
+ } | {
590
+ kind: "computed";
371
591
  } | null;
372
592
  /** What took its place, when something did. */
373
593
  replaced_by_value: string | null;
@@ -409,8 +629,6 @@ export interface TopicRecord {
409
629
  slug: string;
410
630
  icon: string | null;
411
631
  status: string;
412
- parent_id: string | null;
413
- folder_id: string | null;
414
632
  type: {
415
633
  key: string;
416
634
  name: string;
@@ -438,6 +656,14 @@ export interface TopicType {
438
656
  name: string;
439
657
  icon: string | null;
440
658
  description: string;
659
+ schema: {
660
+ id: string;
661
+ kind: "workspace" | "app" | "member";
662
+ };
663
+ app: {
664
+ id: string;
665
+ name: string;
666
+ } | null;
441
667
  fields: {
442
668
  key: string;
443
669
  name: string;
@@ -454,6 +680,15 @@ export interface TopicType {
454
680
  holds: "one" | "many";
455
681
  }[];
456
682
  }
683
+ export interface TypeView {
684
+ key: string;
685
+ name: string;
686
+ scope: "shared" | "personal";
687
+ }
688
+ export interface TypeViewGroup {
689
+ value: string | null;
690
+ count: number;
691
+ }
457
692
  export type TypedValue = {
458
693
  type: "date";
459
694
  value: string;
@@ -468,6 +703,11 @@ export type TypedValue = {
468
703
  type: "choice";
469
704
  value: string;
470
705
  };
706
+ export interface UpdateLesson {
707
+ content?: string;
708
+ category?: string;
709
+ active?: boolean;
710
+ }
471
711
  export interface ValueDetail {
472
712
  label: string;
473
713
  value: string;
@@ -489,7 +729,8 @@ export interface WorkflowCard {
489
729
  name: string;
490
730
  does?: string;
491
731
  trigger?: string;
492
- sources: string[];
732
+ /** The integrations the workflow's tools act in, by name, sorted. */
733
+ tools: string[];
493
734
  steps: {
494
735
  title: string;
495
736
  }[];
@@ -508,6 +749,7 @@ export interface WorkflowCard {
508
749
  step_name: string;
509
750
  provider: string;
510
751
  owner_user_id: string | null;
752
+ connection_catalog_id?: string;
511
753
  account_name: string;
512
754
  reason: "missing" | "expired" | "revoked" | "identity_unverified" | "account_unavailable" | "credential_missing" | "scope_missing" | "requester_required";
513
755
  }[];
@@ -519,6 +761,8 @@ export interface WorkflowLesson {
519
761
  id: string;
520
762
  text: string;
521
763
  added: string;
764
+ /** The recorded instant for an exact timestamp. */
765
+ created_at?: string;
522
766
  /** Present only when the viewer may edit it; pass it back on a save. */
523
767
  edit_revision?: string;
524
768
  }
@@ -526,11 +770,13 @@ export interface WorkflowRun {
526
770
  id: string;
527
771
  /** When it ran, on the organization's calendar. */
528
772
  when: string;
773
+ /** The recorded instant for an exact timestamp. */
774
+ created_at?: string;
529
775
  outcome: WorkflowRunOutcome;
530
776
  /** Present only where the viewer can open every topic the run touched. */
531
777
  summary?: string;
532
- /** The viewer's own open Task on this run. */
533
- task_id?: string;
778
+ /** The viewer's own open Tasks on this run, newest first. */
779
+ task_ids?: string[];
534
780
  }
535
781
  export type WorkflowRunOutcome = "ran" | "edited" | "skipped" | "failed" | "running" | "waiting";
536
782
  export interface WorkflowTopic {
@@ -546,20 +792,98 @@ export interface AppOperationResults {
546
792
  data: TopicRecord[];
547
793
  meta: {
548
794
  next_cursor: string | null;
795
+ /**
796
+ * The type `type` named, null when the query named none. Present on an
797
+ * empty page too, so a reader can listen for the type's records before it
798
+ * has any.
799
+ */
800
+ type_id: string | null;
549
801
  };
550
802
  };
551
803
  /** Create a topic */
552
804
  createTopic: CreatedTopicRecord;
805
+ /** Delete a topic */
806
+ deleteTopic: {
807
+ success: boolean;
808
+ };
809
+ /** Restore a deleted record */
810
+ restoreTopic: RestoredTopicRecord;
553
811
  /** Read the field contract */
554
812
  listTopicTypes: TopicType[];
555
813
  /** Get a topic's record */
556
814
  getTopicRecord: AppTopicRecord;
815
+ /** List a type's saved views */
816
+ listViews: TypeView[];
817
+ /** Read a page of a saved view */
818
+ readView: {
819
+ data: TopicRecord[];
820
+ meta: {
821
+ next_cursor: string | null;
822
+ total: number;
823
+ groups?: TypeViewGroup[];
824
+ };
825
+ };
826
+ /** List the records that name a record */
827
+ listTopicReferences: {
828
+ data: ReferencingTopicRecord[];
829
+ meta: {
830
+ target: {
831
+ id: string;
832
+ name: string;
833
+ };
834
+ counts: {
835
+ type: string | null;
836
+ field: string;
837
+ n: number;
838
+ }[];
839
+ next_cursor: string | null;
840
+ complete: boolean;
841
+ };
842
+ };
843
+ /** Count a type's records */
844
+ countTopics: {
845
+ data: TopicCountBucket[];
846
+ meta: {
847
+ total: number;
848
+ other: number;
849
+ truncated_buckets: number;
850
+ complete: boolean;
851
+ incomplete_reason: "bucket_limit" | null;
852
+ };
853
+ };
854
+ /** List the records related to a record */
855
+ listRelatedTopics: {
856
+ data: RelatedTopicRecord[];
857
+ meta: {
858
+ start: {
859
+ id: string;
860
+ name: string;
861
+ };
862
+ counts: {
863
+ type: string | null;
864
+ n: number;
865
+ }[];
866
+ unresolved: {
867
+ from_id: string;
868
+ field: string;
869
+ text: string;
870
+ }[];
871
+ unresolved_truncated: boolean;
872
+ next_cursor: string | null;
873
+ complete: boolean;
874
+ incomplete_reason: "depth" | "budget" | null;
875
+ };
876
+ };
557
877
  /** Get a field's earlier values */
558
878
  getTopicFieldHistory: TopicFieldHistory;
879
+ /** Get a topic's rendered summary document */
880
+ getTopicSummary: AppTopicSummary;
559
881
  /** Get the discussion about a value */
560
882
  getTopicFactDiscussion: AppFactDiscussion;
561
883
  /** Set a field's value */
562
884
  setTopicField: TopicFieldReceipt;
885
+ /** Clear a field's values */
886
+ clearTopicField: TopicFieldClearReceipt;
563
887
  /** List workflows */
564
888
  listWorkflows: AppWorkflowSummary[];
565
889
  /** Read a workflow as a member reads it */
@@ -574,17 +898,24 @@ export interface AppOperationResults {
574
898
  createLesson: AppLesson;
575
899
  /** Update a lesson */
576
900
  updateLesson: AppLesson;
577
- /** List outcomes */
578
- listOutcomes: {
579
- data: AppOutcome[];
580
- meta: PageMeta;
581
- };
582
- /** Get the organization's defined aggregates */
583
- getOrganizationAnalytics: OrganizationAnalytics;
584
901
  /** Read a key of the app's state */
585
902
  getAppState: AppStateEntry;
903
+ /** Publish a card to the app's viewer */
904
+ publishCard: AppCardPublished;
586
905
  /** Set a key of the app's state */
587
906
  setAppState: AppStateEntry;
588
907
  /** Delete a key of the app's state */
589
908
  deleteAppState: AppStateEntry;
909
+ /** List the app's shared state */
910
+ listAppSharedState: AppSharedStateEntry[];
911
+ /** Read a key of the app's shared state */
912
+ getAppSharedState: AppSharedStateEntry;
913
+ /** Set a key of the app's shared state */
914
+ setAppSharedState: AppSharedStateEntry;
915
+ /** Delete a key of the app's shared state */
916
+ deleteAppSharedState: AppSharedStateEntry;
917
+ /** Send a quick message to everyone with the app open */
918
+ sendAppBroadcast: AppBroadcastSent;
919
+ /** Raise one of the app's events */
920
+ raiseAppEvent: AppEventRaised;
590
921
  }