@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 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.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 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,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; `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.
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
 
@@ -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
- /** 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.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",