@almateam/app-sdk 0.4.0 → 0.5.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 +24 -13
- package/generated/apiTypes.d.ts +21 -2
- 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.5.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,10 +149,13 @@ 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.
|
package/generated/apiTypes.d.ts
CHANGED
|
@@ -37,6 +37,11 @@ export interface AppLesson {
|
|
|
37
37
|
id: string;
|
|
38
38
|
content: string;
|
|
39
39
|
workflow_id: string | null;
|
|
40
|
+
/**
|
|
41
|
+
* False while the lesson waits for the workflow's editors to approve it;
|
|
42
|
+
* runs follow it only once it is true.
|
|
43
|
+
*/
|
|
44
|
+
active: boolean;
|
|
40
45
|
/** Pass it back as `expected_revision` on the next save. */
|
|
41
46
|
edit_revision: string;
|
|
42
47
|
}
|
|
@@ -100,6 +105,16 @@ export interface AppWorkflowSummary {
|
|
|
100
105
|
* `runWorkflow`.
|
|
101
106
|
*/
|
|
102
107
|
runnable?: true;
|
|
108
|
+
/**
|
|
109
|
+
* A workflow the app's manifest names, which the viewer may not start now:
|
|
110
|
+
* why, as a stable `code` and the sentence `runWorkflow` would refuse
|
|
111
|
+
* with. Show the control disabled with `reason`. On a record, the viewer
|
|
112
|
+
* must also be able to edit that record (its `can_edit`).
|
|
113
|
+
*/
|
|
114
|
+
not_runnable?: {
|
|
115
|
+
code: "workflow.off" | "app.not_in_audience";
|
|
116
|
+
reason: string;
|
|
117
|
+
};
|
|
103
118
|
/** The facts the Workflows list sorts and filters by. */
|
|
104
119
|
index?: {
|
|
105
120
|
createdAt: string;
|
|
@@ -321,8 +336,6 @@ export interface TopicFieldReceipt {
|
|
|
321
336
|
* held as the caller's; `unchanged` found it already confirmed.
|
|
322
337
|
*/
|
|
323
338
|
outcome: "applied" | "confirmed" | "unchanged";
|
|
324
|
-
/** Deprecated: read `outcome` (`saved` is `applied`). */
|
|
325
|
-
status: "saved" | "confirmed" | "unchanged";
|
|
326
339
|
topic_id: string;
|
|
327
340
|
field_key: string;
|
|
328
341
|
fact_id: string;
|
|
@@ -439,6 +452,12 @@ export interface WorkflowCard {
|
|
|
439
452
|
/** Newest first. */
|
|
440
453
|
runs: WorkflowRun[];
|
|
441
454
|
lessons: WorkflowLesson[];
|
|
455
|
+
/**
|
|
456
|
+
* Lessons waiting for approval, which runs do not follow yet: all of them
|
|
457
|
+
* for a viewer who decides this workflow's lessons, the viewer's own
|
|
458
|
+
* otherwise.
|
|
459
|
+
*/
|
|
460
|
+
proposed_lessons: WorkflowLesson[];
|
|
442
461
|
can_edit_lessons: boolean;
|
|
443
462
|
connection_blocks?: {
|
|
444
463
|
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.5.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",
|