@almateam/app-sdk 0.5.0 → 0.6.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/README.md CHANGED
@@ -8,7 +8,7 @@ An app imports the SDK as `@alma/app-sdk`. Install the published package under
8
8
  that name, for its types:
9
9
 
10
10
  ```sh
11
- npm install --save-dev @alma/app-sdk@npm:@almateam/app-sdk@^0.5.0
11
+ npm install --save-dev @alma/app-sdk@npm:@almateam/app-sdk@^0.6.0
12
12
  ```
13
13
 
14
14
  Alma builds an app's source with its own current copy of the SDK, whatever
@@ -159,6 +159,15 @@ Follow it with `waitForExecution(run.id, { onUpdate })`, which polls
159
159
  `GET /v1/executions/{id}` with backoff: a run paused at an approval step reads
160
160
  `waiting`, with the people it waits on in `approvers` (its Task is theirs, not
161
161
  the viewer's), and a failed run's `error` is safe to show.
162
+
163
+ A run started on a record can set that record's fields itself, so an app does
164
+ not write a run's outcome. Each run carries `field_writes`: one entry for each
165
+ write the run made to its record, with an `outcome` taken from what the write
166
+ did, not from what the run said. `applied` and `unchanged` carry the stored
167
+ `value` and the field's `revision`; `proposed` means the record asks before
168
+ updating and nothing has changed yet, so show it as waiting for review and never
169
+ as done; `refused` carries `refusal: { code, reason }` to show; `unknown` means
170
+ the write may have completed. A `completed` run may have changed nothing.
162
171
  `listRuns(id, { topicId })` finds the runs started on a record when the app is
163
172
  opened again.
164
173
 
@@ -17,6 +17,10 @@ export interface AppExecution {
17
17
  /** `waiting`: paused on people, whom `approvers` names. */
18
18
  status: "pending" | "running" | "waiting" | "completed" | "failed" | "cancelled";
19
19
  trigger_type: string;
20
+ /**
21
+ * What the run delivered, for the workflow's owners and editors. For
22
+ * anyone else who started it, the report the run submitted.
23
+ */
20
24
  response_content: string | null;
21
25
  /** Why it failed, in words the app may show. */
22
26
  error: string | null;
@@ -25,6 +29,12 @@ export interface AppExecution {
25
29
  id: string;
26
30
  name: string;
27
31
  }[];
32
+ /**
33
+ * What the run's writes to the record it was started on did, oldest first;
34
+ * empty for a run that made none. A run that `completed` did not
35
+ * necessarily change the record: read this, not `response_content`.
36
+ */
37
+ field_writes: AppRunFieldWrite[];
28
38
  started_at: string | null;
29
39
  completed_at: string | null;
30
40
  created_at: string;
@@ -59,6 +69,37 @@ export interface AppOutcome {
59
69
  /** Active workflows serving it that the viewer can open. */
60
70
  live_workflow_count: number;
61
71
  }
72
+ /**
73
+ * What one write by a run to the record it was started on did, read from
74
+ * the run's call ledger and not from what the run reported.
75
+ */
76
+ export interface AppRunFieldWrite {
77
+ field_key: string;
78
+ /**
79
+ * `applied`: the record holds the value. `proposed`: the record asks
80
+ * before updating, so the value is waiting for its reviewers and the
81
+ * record is unchanged; show it as awaiting review, never as done.
82
+ * `unchanged`: the record already held it. `refused`: nothing was written,
83
+ * and `refusal` says why. `unknown`: the write may have completed; read
84
+ * the record before repeating it.
85
+ */
86
+ outcome: "applied" | "proposed" | "unchanged" | "refused" | "unknown";
87
+ /** The run had already made this write, and the field has changed since. */
88
+ superseded?: true;
89
+ /**
90
+ * The value as the record stores it, on `applied` and `unchanged`, where
91
+ * the viewer can read the record. Never set on `proposed`.
92
+ */
93
+ value?: string;
94
+ /** With `value`: the field's revision after the write. */
95
+ revision?: string;
96
+ /** On `refused`: a stable code and a sentence to show as it is. */
97
+ refusal?: {
98
+ code: string;
99
+ reason: string;
100
+ };
101
+ at: string;
102
+ }
62
103
  /** A run an app started, as it started: poll `getExecution` with its `id`. */
63
104
  export interface AppRunReceipt {
64
105
  id: string;
@@ -112,7 +153,7 @@ export interface AppWorkflowSummary {
112
153
  * must also be able to edit that record (its `can_edit`).
113
154
  */
114
155
  not_runnable?: {
115
- code: "workflow.off" | "app.not_in_audience";
156
+ code: "workflow.off" | "workflow.not_active" | "app.not_in_audience" | "workflow.not_granted";
116
157
  reason: string;
117
158
  };
118
159
  /** The facts the Workflows list sorts and filters by. */
@@ -297,7 +338,8 @@ export interface TopicFieldHistoryEntry {
297
338
  value_json: TypedValue | null;
298
339
  /**
299
340
  * Who or what a history line names: a person (named where the viewer can
300
- * still resolve them), Alma, or a workflow's run.
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).
301
343
  */
302
344
  written_by: {
303
345
  kind: "person";
@@ -306,6 +348,7 @@ export interface TopicFieldHistoryEntry {
306
348
  kind: "alma";
307
349
  } | {
308
350
  kind: "workflow";
351
+ name: string | null;
309
352
  };
310
353
  /** Who had confirmed the value while it stood. */
311
354
  verified_by: {
@@ -313,7 +356,7 @@ export interface TopicFieldHistoryEntry {
313
356
  at: string;
314
357
  } | null;
315
358
  /** Why the value stopped standing. */
316
- reason: "corrected" | "superseded" | "retracted" | "rejected" | "moved" | "unattributed";
359
+ reason: "corrected" | "superseded" | "retracted" | "rejected" | "moved" | "merged" | "unattributed";
317
360
  /** The preset a person gave for removing it, when they gave one. */
318
361
  rejection_reason: "wrong_entity" | "inaccurate" | "irrelevant" | "duplicate" | null;
319
362
  /** Who or what made the change; null when no writer declared itself. */
@@ -324,6 +367,7 @@ export interface TopicFieldHistoryEntry {
324
367
  kind: "alma";
325
368
  } | {
326
369
  kind: "workflow";
370
+ name: string | null;
327
371
  } | null;
328
372
  /** What took its place, when something did. */
329
373
  replaced_by_value: string | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@almateam/app-sdk",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Types, host bridge and the alma-app dev command for apps that run in Alma. Alma builds every app with its own current copy of the SDK; install this for the types and the command.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://docs.alma.team/developers/apps",