@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 +10 -1
- package/generated/apiTypes.d.ts +47 -3
- package/package.json +1 -1
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.
|
|
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
|
|
package/generated/apiTypes.d.ts
CHANGED
|
@@ -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.
|
|
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",
|