@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 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.4.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 will be refused. To say it yourself, pass
90
- `{ ifRevision }` (a revision from a read, a receipt's `revision` or a conflict's
91
- `current.revision`) or `{ ifValue }` (a value the field held, as its `text` was
92
- read, or `null` if it held nothing). The receipt names how the write ended in
93
- `outcome` (`applied`, `confirmed` or `unchanged`). To make a write safe to send
94
- twice, pass `{ idempotencyKey }`: the same key and request again answers with
95
- the first receipt and writes nothing, marked `superseded` if the field has
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; `runWorkflow(id, { topicId, input })` starts one as
145
- the viewer (`POST /v1/workflows/{id}/executions`), with nobody asked: the viewer
146
- must be in the app's audience and, on a record, able to edit it. The run acts as
147
- them. Follow it with `waitForExecution(run.id, { onUpdate })`, which polls
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.
@@ -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
- /** A lesson every later run of the workflow follows. Screened: wording
175
- * that reads as an instruction to Alma is refused with the reason. */
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.4.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",