@almateam/app-sdk 0.4.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 +33 -13
- package/generated/apiTypes.d.ts +67 -4
- package/index.d.ts +6 -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
|
|
@@ -51,6 +51,14 @@ act: it saves as them where they may edit that record and is refused where they
|
|
|
51
51
|
cannot. Nobody is asked and no dialog appears: the promise resolves with the
|
|
52
52
|
result, or rejects with the refusal's words.
|
|
53
53
|
|
|
54
|
+
A lesson added by a viewer who decides the workflow's lessons (its editors and
|
|
55
|
+
the workspace's owners) is live at once: `createWorkflowLesson` resolves with
|
|
56
|
+
`active: true` and the lesson is on the card's `lessons`. From any other viewer
|
|
57
|
+
it is a proposal: it resolves with `active: false`, is sent to the people who do
|
|
58
|
+
decide, and runs follow it only once one of them approves it in Tasks. Until
|
|
59
|
+
then it is on the card's `proposed_lessons`, for its author and for those
|
|
60
|
+
deciders.
|
|
61
|
+
|
|
54
62
|
The app talks to its host on one channel that belongs to the document the Space
|
|
55
63
|
loaded; the SDK finds it there. A document the frame navigates to has no
|
|
56
64
|
channel, and the host closes the Space when the frame leaves or reloads its
|
|
@@ -86,14 +94,14 @@ try {
|
|
|
86
94
|
```
|
|
87
95
|
|
|
88
96
|
Read the record before writing it, so the SDK has something to send: a write
|
|
89
|
-
that says nothing about what it read
|
|
90
|
-
`{ ifRevision }` (a revision from a
|
|
91
|
-
`
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
the
|
|
96
|
-
changed since.
|
|
97
|
+
that says nothing about what it read is refused (`precondition.required`) and
|
|
98
|
+
writes nothing. To say it yourself, pass `{ ifRevision }` (a revision from a
|
|
99
|
+
read, a receipt's `revision` or a conflict's `current.revision`) or
|
|
100
|
+
`{ ifValue }` (a value the field held, as its `text` was read, or `null` if it
|
|
101
|
+
held nothing). The receipt names how the write ended in `outcome` (`applied`,
|
|
102
|
+
`confirmed` or `unchanged`). To make a write safe to send twice, pass
|
|
103
|
+
`{ idempotencyKey }`: the same key and request again answers with the first
|
|
104
|
+
receipt and writes nothing, marked `superseded` if the field has changed since.
|
|
97
105
|
|
|
98
106
|
## State: what only this person's screen needs
|
|
99
107
|
|
|
@@ -141,13 +149,25 @@ declares.
|
|
|
141
149
|
An app's backend is the ordinary workflows its manifest names (`workflows`, by
|
|
142
150
|
id, with the `workflows:run` scope): workflows of the workspace, edited by their
|
|
143
151
|
managers and run as they stand. `listWorkflows()` marks them `runnable` where
|
|
144
|
-
the viewer may start them
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
152
|
+
the viewer may start them, and where they may not gives the reason in
|
|
153
|
+
`not_runnable` (`{ code, reason }`, the sentence `runWorkflow` would refuse
|
|
154
|
+
with): show the control disabled with that reason.
|
|
155
|
+
`runWorkflow(id, { topicId, input })` starts one as the viewer
|
|
156
|
+
(`POST /v1/workflows/{id}/executions`), with nobody asked: the viewer must be in
|
|
157
|
+
the app's audience and, on a record, able to edit it. The run acts as them.
|
|
158
|
+
Follow it with `waitForExecution(run.id, { onUpdate })`, which polls
|
|
148
159
|
`GET /v1/executions/{id}` with backoff: a run paused at an approval step reads
|
|
149
160
|
`waiting`, with the people it waits on in `approvers` (its Task is theirs, not
|
|
150
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.
|
|
151
171
|
`listRuns(id, { topicId })` finds the runs started on a record when the app is
|
|
152
172
|
opened again.
|
|
153
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;
|
|
@@ -37,6 +47,11 @@ export interface AppLesson {
|
|
|
37
47
|
id: string;
|
|
38
48
|
content: string;
|
|
39
49
|
workflow_id: string | null;
|
|
50
|
+
/**
|
|
51
|
+
* False while the lesson waits for the workflow's editors to approve it;
|
|
52
|
+
* runs follow it only once it is true.
|
|
53
|
+
*/
|
|
54
|
+
active: boolean;
|
|
40
55
|
/** Pass it back as `expected_revision` on the next save. */
|
|
41
56
|
edit_revision: string;
|
|
42
57
|
}
|
|
@@ -54,6 +69,37 @@ export interface AppOutcome {
|
|
|
54
69
|
/** Active workflows serving it that the viewer can open. */
|
|
55
70
|
live_workflow_count: number;
|
|
56
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
|
+
}
|
|
57
103
|
/** A run an app started, as it started: poll `getExecution` with its `id`. */
|
|
58
104
|
export interface AppRunReceipt {
|
|
59
105
|
id: string;
|
|
@@ -100,6 +146,16 @@ export interface AppWorkflowSummary {
|
|
|
100
146
|
* `runWorkflow`.
|
|
101
147
|
*/
|
|
102
148
|
runnable?: true;
|
|
149
|
+
/**
|
|
150
|
+
* A workflow the app's manifest names, which the viewer may not start now:
|
|
151
|
+
* why, as a stable `code` and the sentence `runWorkflow` would refuse
|
|
152
|
+
* with. Show the control disabled with `reason`. On a record, the viewer
|
|
153
|
+
* must also be able to edit that record (its `can_edit`).
|
|
154
|
+
*/
|
|
155
|
+
not_runnable?: {
|
|
156
|
+
code: "workflow.off" | "workflow.not_active" | "app.not_in_audience" | "workflow.not_granted";
|
|
157
|
+
reason: string;
|
|
158
|
+
};
|
|
103
159
|
/** The facts the Workflows list sorts and filters by. */
|
|
104
160
|
index?: {
|
|
105
161
|
createdAt: string;
|
|
@@ -282,7 +338,8 @@ export interface TopicFieldHistoryEntry {
|
|
|
282
338
|
value_json: TypedValue | null;
|
|
283
339
|
/**
|
|
284
340
|
* Who or what a history line names: a person (named where the viewer can
|
|
285
|
-
* 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).
|
|
286
343
|
*/
|
|
287
344
|
written_by: {
|
|
288
345
|
kind: "person";
|
|
@@ -291,6 +348,7 @@ export interface TopicFieldHistoryEntry {
|
|
|
291
348
|
kind: "alma";
|
|
292
349
|
} | {
|
|
293
350
|
kind: "workflow";
|
|
351
|
+
name: string | null;
|
|
294
352
|
};
|
|
295
353
|
/** Who had confirmed the value while it stood. */
|
|
296
354
|
verified_by: {
|
|
@@ -298,7 +356,7 @@ export interface TopicFieldHistoryEntry {
|
|
|
298
356
|
at: string;
|
|
299
357
|
} | null;
|
|
300
358
|
/** Why the value stopped standing. */
|
|
301
|
-
reason: "corrected" | "superseded" | "retracted" | "rejected" | "moved" | "unattributed";
|
|
359
|
+
reason: "corrected" | "superseded" | "retracted" | "rejected" | "moved" | "merged" | "unattributed";
|
|
302
360
|
/** The preset a person gave for removing it, when they gave one. */
|
|
303
361
|
rejection_reason: "wrong_entity" | "inaccurate" | "irrelevant" | "duplicate" | null;
|
|
304
362
|
/** Who or what made the change; null when no writer declared itself. */
|
|
@@ -309,6 +367,7 @@ export interface TopicFieldHistoryEntry {
|
|
|
309
367
|
kind: "alma";
|
|
310
368
|
} | {
|
|
311
369
|
kind: "workflow";
|
|
370
|
+
name: string | null;
|
|
312
371
|
} | null;
|
|
313
372
|
/** What took its place, when something did. */
|
|
314
373
|
replaced_by_value: string | null;
|
|
@@ -321,8 +380,6 @@ export interface TopicFieldReceipt {
|
|
|
321
380
|
* held as the caller's; `unchanged` found it already confirmed.
|
|
322
381
|
*/
|
|
323
382
|
outcome: "applied" | "confirmed" | "unchanged";
|
|
324
|
-
/** Deprecated: read `outcome` (`saved` is `applied`). */
|
|
325
|
-
status: "saved" | "confirmed" | "unchanged";
|
|
326
383
|
topic_id: string;
|
|
327
384
|
field_key: string;
|
|
328
385
|
fact_id: string;
|
|
@@ -439,6 +496,12 @@ export interface WorkflowCard {
|
|
|
439
496
|
/** Newest first. */
|
|
440
497
|
runs: WorkflowRun[];
|
|
441
498
|
lessons: WorkflowLesson[];
|
|
499
|
+
/**
|
|
500
|
+
* Lessons waiting for approval, which runs do not follow yet: all of them
|
|
501
|
+
* for a viewer who decides this workflow's lessons, the viewer's own
|
|
502
|
+
* otherwise.
|
|
503
|
+
*/
|
|
504
|
+
proposed_lessons: WorkflowLesson[];
|
|
442
505
|
can_edit_lessons: boolean;
|
|
443
506
|
connection_blocks?: {
|
|
444
507
|
step_id: string;
|
package/index.d.ts
CHANGED
|
@@ -97,7 +97,8 @@ export type FieldChangedError = AppCallError & {
|
|
|
97
97
|
};
|
|
98
98
|
export declare function isFieldChanged(error: unknown): error is FieldChangedError;
|
|
99
99
|
/** What a field write says the app read before writing. Left out, the SDK
|
|
100
|
-
* sends what its own last read of the record showed.
|
|
100
|
+
* sends what its own last read of the record showed. A write to a record
|
|
101
|
+
* the app never read, with none of these, is refused. */
|
|
101
102
|
export interface FieldWriteOptions {
|
|
102
103
|
/** The field's revision, from a record's `revisions`, a receipt's
|
|
103
104
|
* `revision` or a conflict's `current.revision`. */
|
|
@@ -171,8 +172,10 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
171
172
|
* `signal` to stop. */
|
|
172
173
|
waitForExecution: (executionId: string, options?: PollOptions) => Promise<Api.AppExecution>;
|
|
173
174
|
getWorkflowCard: (workflowId: string) => Promise<Api.WorkflowCard>;
|
|
174
|
-
/**
|
|
175
|
-
*
|
|
175
|
+
/** Propose a lesson for the workflow's later runs. It resolves with
|
|
176
|
+
* `active: false` and applies once someone who can edit the workflow
|
|
177
|
+
* approves it in Tasks. Screened: wording that reads as an instruction
|
|
178
|
+
* to Alma is refused with the reason. */
|
|
176
179
|
createWorkflowLesson: (workflowId: string, content: string) => Promise<Api.AppLesson>;
|
|
177
180
|
/** Pass the `edit_revision` the card gave; a save made meanwhile is
|
|
178
181
|
* refused rather than overwritten. */
|
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",
|