@almateam/app-sdk 0.6.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 {
@@ -84,8 +111,6 @@ export interface AppRunFieldWrite {
84
111
  * the record before repeating it.
85
112
  */
86
113
  outcome: "applied" | "proposed" | "unchanged" | "refused" | "unknown";
87
- /** The run had already made this write, and the field has changed since. */
88
- superseded?: true;
89
114
  /**
90
115
  * The value as the record stores it, on `applied` and `unchanged`, where
91
116
  * the viewer can read the record. Never set on `proposed`.
@@ -107,6 +132,23 @@ export interface AppRunReceipt {
107
132
  status: string;
108
133
  created_at: string;
109
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
+ }
110
152
  /**
111
153
  * One key of an app's own state for its viewer: what only that person's
112
154
  * screen of that app needs between visits.
@@ -129,6 +171,18 @@ export interface AppTopicRecord {
129
171
  */
130
172
  revisions: Record<string, string>;
131
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
+ }
132
186
  /**
133
187
  * A row of the member Workflows list: a workflow the viewer reads the card
134
188
  * of, or one the app's manifest names that the viewer may start.
@@ -176,10 +230,65 @@ export interface AppWorkflowSummary {
176
230
  };
177
231
  };
178
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
+ }
179
278
  export interface CreatedTopicRecord {
180
279
  id: string;
181
280
  name: string;
182
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>;
183
292
  }
184
293
  /**
185
294
  * A value: its text as written, its typed reading where its field's type
@@ -207,40 +316,18 @@ export interface KnowledgeRecord {
207
316
  /** Whether the viewer may edit this topic's values. */
208
317
  viewer_can_edit: boolean;
209
318
  }
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
319
  export interface PageMeta {
242
320
  hasMore: boolean;
243
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
+ }
244
331
  /** Who a record reaches, as its sharing mark says it — never the roster. */
245
332
  export interface RecordAudience {
246
333
  scope: "everyone" | "tier" | "restricted";
@@ -281,6 +368,123 @@ export interface RecordUpdate {
281
368
  count?: number;
282
369
  edited?: boolean;
283
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
+ }
284
488
  export interface TopicDiscussion {
285
489
  topic_id: string;
286
490
  fact_id: string;
@@ -326,6 +530,27 @@ export interface TopicFact {
326
530
  value: FactValue;
327
531
  verified_at: string | null;
328
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
+ }
329
554
  export interface TopicFieldHistory {
330
555
  topic_id: string;
331
556
  field_key: string;
@@ -338,8 +563,10 @@ export interface TopicFieldHistoryEntry {
338
563
  value_json: TypedValue | null;
339
564
  /**
340
565
  * 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).
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.
343
570
  */
344
571
  written_by: {
345
572
  kind: "person";
@@ -349,6 +576,8 @@ export interface TopicFieldHistoryEntry {
349
576
  } | {
350
577
  kind: "workflow";
351
578
  name: string | null;
579
+ } | {
580
+ kind: "computed";
352
581
  };
353
582
  /** Who had confirmed the value while it stood. */
354
583
  verified_by: {
@@ -368,6 +597,8 @@ export interface TopicFieldHistoryEntry {
368
597
  } | {
369
598
  kind: "workflow";
370
599
  name: string | null;
600
+ } | {
601
+ kind: "computed";
371
602
  } | null;
372
603
  /** What took its place, when something did. */
373
604
  replaced_by_value: string | null;
@@ -409,8 +640,6 @@ export interface TopicRecord {
409
640
  slug: string;
410
641
  icon: string | null;
411
642
  status: string;
412
- parent_id: string | null;
413
- folder_id: string | null;
414
643
  type: {
415
644
  key: string;
416
645
  name: string;
@@ -438,6 +667,14 @@ export interface TopicType {
438
667
  name: string;
439
668
  icon: string | null;
440
669
  description: string;
670
+ schema: {
671
+ id: string;
672
+ kind: "workspace" | "app";
673
+ };
674
+ app: {
675
+ id: string;
676
+ name: string;
677
+ } | null;
441
678
  fields: {
442
679
  key: string;
443
680
  name: string;
@@ -454,6 +691,15 @@ export interface TopicType {
454
691
  holds: "one" | "many";
455
692
  }[];
456
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
+ }
457
703
  export type TypedValue = {
458
704
  type: "date";
459
705
  value: string;
@@ -468,6 +714,11 @@ export type TypedValue = {
468
714
  type: "choice";
469
715
  value: string;
470
716
  };
717
+ export interface UpdateLesson {
718
+ content?: string;
719
+ category?: string;
720
+ active?: boolean;
721
+ }
471
722
  export interface ValueDetail {
472
723
  label: string;
473
724
  value: string;
@@ -489,7 +740,8 @@ export interface WorkflowCard {
489
740
  name: string;
490
741
  does?: string;
491
742
  trigger?: string;
492
- sources: string[];
743
+ /** The integrations the workflow's tools act in, by name, sorted. */
744
+ tools: string[];
493
745
  steps: {
494
746
  title: string;
495
747
  }[];
@@ -508,6 +760,7 @@ export interface WorkflowCard {
508
760
  step_name: string;
509
761
  provider: string;
510
762
  owner_user_id: string | null;
763
+ connection_catalog_id?: string;
511
764
  account_name: string;
512
765
  reason: "missing" | "expired" | "revoked" | "identity_unverified" | "account_unavailable" | "credential_missing" | "scope_missing" | "requester_required";
513
766
  }[];
@@ -529,8 +782,8 @@ export interface WorkflowRun {
529
782
  outcome: WorkflowRunOutcome;
530
783
  /** Present only where the viewer can open every topic the run touched. */
531
784
  summary?: string;
532
- /** The viewer's own open Task on this run. */
533
- task_id?: string;
785
+ /** The viewer's own open Tasks on this run, newest first. */
786
+ task_ids?: string[];
534
787
  }
535
788
  export type WorkflowRunOutcome = "ran" | "edited" | "skipped" | "failed" | "running" | "waiting";
536
789
  export interface WorkflowTopic {
@@ -546,20 +799,98 @@ export interface AppOperationResults {
546
799
  data: TopicRecord[];
547
800
  meta: {
548
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;
549
808
  };
550
809
  };
551
810
  /** Create a topic */
552
811
  createTopic: CreatedTopicRecord;
812
+ /** Delete a topic */
813
+ deleteTopic: {
814
+ success: boolean;
815
+ };
816
+ /** Restore a deleted record */
817
+ restoreTopic: RestoredTopicRecord;
553
818
  /** Read the field contract */
554
819
  listTopicTypes: TopicType[];
555
820
  /** Get a topic's record */
556
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
+ };
557
884
  /** Get a field's earlier values */
558
885
  getTopicFieldHistory: TopicFieldHistory;
886
+ /** Get a topic's rendered summary document */
887
+ getTopicSummary: AppTopicSummary;
559
888
  /** Get the discussion about a value */
560
889
  getTopicFactDiscussion: AppFactDiscussion;
561
890
  /** Set a field's value */
562
891
  setTopicField: TopicFieldReceipt;
892
+ /** Clear a field's values */
893
+ clearTopicField: TopicFieldClearReceipt;
563
894
  /** List workflows */
564
895
  listWorkflows: AppWorkflowSummary[];
565
896
  /** Read a workflow as a member reads it */
@@ -579,12 +910,24 @@ export interface AppOperationResults {
579
910
  data: AppOutcome[];
580
911
  meta: PageMeta;
581
912
  };
582
- /** Get the organization's defined aggregates */
583
- getOrganizationAnalytics: OrganizationAnalytics;
584
913
  /** Read a key of the app's state */
585
914
  getAppState: AppStateEntry;
915
+ /** Publish a card to the app's viewer */
916
+ publishCard: AppCardPublished;
586
917
  /** Set a key of the app's state */
587
918
  setAppState: AppStateEntry;
588
919
  /** Delete a key of the app's state */
589
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;
590
933
  }