@almateam/app-sdk 0.7.0 → 0.8.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.7.0
11
+ npm install --save-dev @alma/app-sdk@npm:@almateam/app-sdk@^0.8.0
12
12
  ```
13
13
 
14
14
  Alma builds an app's source with its own current copy of the SDK, whatever
@@ -113,23 +113,68 @@ const filter = await alma.state.get<{ stage: string }>("filter"); // or undefine
113
113
  await alma.state.delete("filter");
114
114
  ```
115
115
 
116
- If another person, a workflow or Alma needs to see or act on something, it is a
117
- record. If only this app's screen for this person needs it, it is app state.
116
+ If a workflow or Alma needs to see or act on something, or the workspace should
117
+ keep it for other people to find, it is a record. If everyone with the app open
118
+ sees it together, it is shared state (below). If only this app's screen for
119
+ this person needs it, it is app state.
118
120
 
119
121
  State is a small key/value store per installed app and per person: a filter, a
120
122
  collapsed column, a half-written draft. Only that person's sessions of that app
121
123
  read or write it. It needs no scope and no owner's approval, and declaring
122
124
  nothing for it does not widen a version. Nothing in it reaches a workflow run,
123
- search or anything Alma knows. What everyone viewing the app sees together (a
124
- board's column order, a vote, whose turn it is) goes in shared state instead:
125
- `sdk.shared`, which needs the `shared_state:write` scope, and whose `watch`
126
- tells every open copy of the app each change within a second or two. App state
127
- survives a reload and a new version of the app, and goes when the app is removed
128
- from the workspace or the person leaves it. Keys are letters, digits, `_` and
129
- `-` (up to 128 characters). A value is any JSON up to 16 KB, and one person
130
- holds at most 64 keys and 256 KB in one app; a `set` past a limit rejects with a
131
- refusal whose `code` is `app_state.value_too_large` or
132
- `app_state.quota_exceeded`.
125
+ search or anything Alma knows. App state survives a reload and a new version of
126
+ the app, and goes when the app is removed from the workspace or the person
127
+ leaves it. Keys are letters, digits, `_` and `-` (up to 128 characters). A
128
+ value is any JSON up to 16 KB, and one person holds at most 64 keys and 256 KB
129
+ in one installation; a `set` past a limit rejects with a refusal whose `code` is
130
+ `app_state.value_too_large` or `app_state.quota_exceeded`.
131
+
132
+ ## Shared state: what everyone with the app open sees
133
+
134
+ ```ts
135
+ const stop = alma.shared.watch((entry) => {
136
+ // { key, exists, value, revision }: every key once, then each change
137
+ });
138
+ const mine = "player-" + viewer.person_id;
139
+ const joined = await alma.shared.set(mine, { score: 0 }, { ifRevision: 0 });
140
+ try {
141
+ await alma.shared.set(mine, { score: 1 }, { ifRevision: joined.revision });
142
+ } catch (error) {
143
+ if (!isSharedStateConflict(error)) throw error;
144
+ // error.current is the key as it stands: apply the change to it, write again
145
+ }
146
+ ```
147
+
148
+ Shared state is one small key/value store per installed app that everyone who
149
+ can open it reads and writes: a leaderboard's scores, a board's column order, a
150
+ vote, whose turn it is. It survives a reload and needs the `shared_state:write`
151
+ scope. `get(key)` answers `{ key, exists, value, revision }`, with revision 0
152
+ for a key that holds nothing; `list()` answers every key, `set(key, value)` the
153
+ key as written, and `delete(key)` removes it. `watch(listener)` calls its
154
+ listener with every key, then with each key as it changes, whoever changed it,
155
+ within a second or two, and with `exists: false` for a key deleted; it returns
156
+ the unsubscribe. An app never polls: where the host cannot tell (an Alma tab
157
+ from before it, the check Alma runs on a new version, or a channel the server
158
+ refuses), `watch` reads by itself, every 5 seconds and less often while nothing
159
+ changes.
160
+
161
+ Keep what each person changes under a key of their own, so two people writing
162
+ at once never write over each other, and keep that key the same between visits
163
+ (an id kept in `alma.state` the first time). Send one write at a time and fold
164
+ changes made meanwhile into the next. With `{ ifRevision }`, a `set` writes only
165
+ over that revision (0: only where the key holds nothing) and otherwise rejects
166
+ with an error `isSharedStateConflict` recognizes, whose `current` is the key as
167
+ it stands.
168
+
169
+ Keys are letters, digits, `_` and `-` (up to 128 characters). A value is any
170
+ JSON up to 16 KB; one installation holds at most 128 keys and 256 KB, and
171
+ everyone using it together may write 60 times at once, then 10 a second (a
172
+ `delete` counts as a write, and so does a write refused for a conflict or the
173
+ quota). A write past a limit rejects with a refusal whose `code` is
174
+ `app_shared_state.value_too_large`, `app_shared_state.quota_exceeded` or
175
+ `app_shared_state.rate_limited`. `alma_get_app_builder_guide` hands out a
176
+ multiplayer leaderboard built this way, with presence and quick messages, as
177
+ `live.sample`.
133
178
 
134
179
  ## The viewer: which person is looking
135
180
 
@@ -152,9 +197,11 @@ answer, not a failure; an app that needs to know asks the person then (and can
152
197
  keep the answer in state). The host answers from its latest session, so the
153
198
  answer can change when the app is reopened.
154
199
 
155
- To show other people what each person did (a leaderboard that names its
156
- players), write records with a relationship to the `person` type: a record is
157
- the viewer's own where that relationship holds their `person_id`.
200
+ What everyone using the app sees of each person while they use it (a
201
+ leaderboard that names its players) goes in shared state, under a key per
202
+ person. What the workspace keeps of each person after the app closes is written
203
+ as records with a relationship to the `person` type: a record is the viewer's
204
+ own where that relationship holds their `person_id`.
158
205
 
159
206
  ## Who else is here
160
207
 
@@ -274,10 +321,16 @@ with): show the control disabled with that reason.
274
321
  owner granted the app **Can run** on its access list or the viewer can run it
275
322
  themselves, and on a record the viewer can see. Naming a workflow grants the app
276
323
  nothing. The run acts as the workflow, on its own permissions and step accounts,
277
- not as the viewer. Follow it with `waitForExecution(run.id, { onUpdate })`,
324
+ not as the viewer; only a step account set to whoever starts the run goes out
325
+ on the viewer's own connection. Follow it with `waitForExecution(run.id, { onUpdate })`,
278
326
  which polls `GET /v1/executions/{id}` with backoff: a run paused at an approval
279
327
  step reads `waiting`, with the people it waits on in `approvers` (its Task is
280
- theirs, not the viewer's), and a failed run's `error` is safe to show.
328
+ theirs, not the viewer's), and a failed run's `error` is safe to show. When the
329
+ workflow's last step runs as code and its program finishes it, the run's
330
+ `result` is the JSON the program returned (null otherwise, or past 64 KB);
331
+ `waitForExecution<T>(run.id)` and `listRuns<T>` type it as `T | null`. It is
332
+ read as `response_content` is: whoever started the run gets it unless the run
333
+ read something sensitive, and then gets neither.
281
334
 
282
335
  A run started on a record can set that record's fields itself, so an app does
283
336
  not write a run's outcome. Each run carries `field_writes`: one entry for each
@@ -49,6 +49,12 @@ export interface AppExecution {
49
49
  * anyone else who started it, the report the run submitted.
50
50
  */
51
51
  response_content: string | null;
52
+ /**
53
+ * The JSON the run's last step returned, when that step ran as code and
54
+ * its program finished it; null otherwise, and when it came to more than
55
+ * 64 KB. Read as `response_content` is, and withheld with it.
56
+ */
57
+ result: unknown | null;
52
58
  /** Why it failed, in words the app may show. */
53
59
  error: string | null;
54
60
  /** Empty when anyone in the workspace may decide. */
@@ -82,20 +88,6 @@ export interface AppLesson {
82
88
  /** Pass it back as `expected_revision` on the next save. */
83
89
  edit_revision: string;
84
90
  }
85
- export interface AppOutcome {
86
- id: string;
87
- name: string;
88
- description: string | null;
89
- signal: string | null;
90
- parent_outcome_id: string | null;
91
- status: string;
92
- created_at: string;
93
- updated_at: string;
94
- /** The groups that own it, as the viewer reads them. */
95
- owning_groups: string[];
96
- /** Active workflows serving it that the viewer can open. */
97
- live_workflow_count: number;
98
- }
99
91
  /**
100
92
  * What one write by a run to the record it was started on did, read from
101
93
  * the run's call ledger and not from what the run reported.
@@ -316,9 +308,6 @@ export interface KnowledgeRecord {
316
308
  /** Whether the viewer may edit this topic's values. */
317
309
  viewer_can_edit: boolean;
318
310
  }
319
- export interface PageMeta {
320
- hasMore: boolean;
321
- }
322
311
  export interface RaiseAppEvent {
323
312
  /** One of the events the app's shared version declares. */
324
313
  event: string;
@@ -669,7 +658,7 @@ export interface TopicType {
669
658
  description: string;
670
659
  schema: {
671
660
  id: string;
672
- kind: "workspace" | "app";
661
+ kind: "workspace" | "app" | "member";
673
662
  };
674
663
  app: {
675
664
  id: string;
@@ -772,6 +761,8 @@ export interface WorkflowLesson {
772
761
  id: string;
773
762
  text: string;
774
763
  added: string;
764
+ /** The recorded instant for an exact timestamp. */
765
+ created_at?: string;
775
766
  /** Present only when the viewer may edit it; pass it back on a save. */
776
767
  edit_revision?: string;
777
768
  }
@@ -779,6 +770,8 @@ export interface WorkflowRun {
779
770
  id: string;
780
771
  /** When it ran, on the organization's calendar. */
781
772
  when: string;
773
+ /** The recorded instant for an exact timestamp. */
774
+ created_at?: string;
782
775
  outcome: WorkflowRunOutcome;
783
776
  /** Present only where the viewer can open every topic the run touched. */
784
777
  summary?: string;
@@ -905,11 +898,6 @@ export interface AppOperationResults {
905
898
  createLesson: AppLesson;
906
899
  /** Update a lesson */
907
900
  updateLesson: AppLesson;
908
- /** List outcomes */
909
- listOutcomes: {
910
- data: AppOutcome[];
911
- meta: PageMeta;
912
- };
913
901
  /** Read a key of the app's state */
914
902
  getAppState: AppStateEntry;
915
903
  /** Publish a card to the app's viewer */
package/index.d.ts CHANGED
@@ -48,6 +48,12 @@ export interface PollOptions {
48
48
  * "Waiting for Lena". */
49
49
  onUpdate?: (execution: Api.AppExecution) => void;
50
50
  }
51
+ /** A run whose program returns a `result` of a shape the app knows, as
52
+ * `waitForExecution<T>` gives it. Unchecked: the app's own program is what
53
+ * vouches for `T`. */
54
+ export type AppExecutionOf<T> = Omit<Api.AppExecution, "result"> & {
55
+ result: T | null;
56
+ };
51
57
  /** Every Alma `/v1` operation an app may call, by OpenAPI operationId, and
52
58
  * whether it only reads or makes a change as its viewer. The host refuses
53
59
  * any other name and any operation outside the manifest's scopes. */
@@ -76,7 +82,6 @@ declare const APP_OPERATIONS: {
76
82
  readonly runWorkflow: "change";
77
83
  readonly listWorkflowExecutions: "read";
78
84
  readonly getExecution: "read";
79
- readonly listOutcomes: "read";
80
85
  readonly publishCard: "change";
81
86
  readonly raiseAppEvent: "change";
82
87
  readonly getAppState: "read";
@@ -519,7 +524,8 @@ export declare function createAppSdk(transport: AppTransport): {
519
524
  /** Starts a workflow the app's manifest names. Nobody is asked: it starts
520
525
  * where the workflow's owner granted the app, or the viewer may run it
521
526
  * themselves, on a record they can see, and rejects with the refusal's
522
- * words otherwise. The run acts as the workflow, not as the viewer. */
527
+ * words otherwise. The run acts as the workflow, not as the viewer: only
528
+ * a step account set to whoever starts the run is the viewer's own. */
523
529
  runWorkflow: (workflowId: string, run?: {
524
530
  topicId?: string;
525
531
  input?: Record<string, unknown>;
@@ -529,14 +535,15 @@ export declare function createAppSdk(transport: AppTransport): {
529
535
  getExecution: (executionId: string) => Promise<Api.AppExecution>;
530
536
  /** The newest runs of a workflow the app names that the viewer may read,
531
537
  * on one record when `topicId` names it: how an app opened again finds
532
- * the run it started. */
533
- listRuns: (workflowId: string, run?: {
538
+ * the run it started, with `result` typed as `T`. */
539
+ listRuns: <T = unknown>(workflowId: string, run?: {
534
540
  topicId?: string;
535
- }) => Promise<Api.AppExecution[]>;
541
+ }) => Promise<AppExecutionOf<T>[]>;
536
542
  /** Polls a run with backoff until it finishes, and resolves with how it
537
- * ended. A run waiting on an approver can wait for a long time; pass a
538
- * `signal` to stop. */
539
- waitForExecution: (executionId: string, options?: PollOptions) => Promise<Api.AppExecution>;
543
+ * ended, with `result` typed as `T` where its code step returns one. A
544
+ * run waiting on an approver can wait for a long time; pass a `signal` to
545
+ * stop. */
546
+ waitForExecution: <T = unknown>(executionId: string, options?: PollOptions) => Promise<AppExecutionOf<T>>;
540
547
  getWorkflowCard: (workflowId: string) => Promise<Api.WorkflowCard>;
541
548
  /** Adds a lesson for the workflow's later runs. It is live at once
542
549
  * (`active: true`) when the viewer can edit the workflow; otherwise it
@@ -648,13 +655,6 @@ export declare function createAppSdk(transport: AppTransport): {
648
655
  onBroadcast: (event: string, listener: (payload: unknown) => void, options?: {
649
656
  self?: boolean;
650
657
  }) => (() => void);
651
- listOutcomes: (page?: {
652
- limit?: number;
653
- offset?: number;
654
- }) => Promise<{
655
- data: Api.AppOutcome[];
656
- meta: Api.PageMeta;
657
- }>;
658
658
  /** What changed in a record since its viewer last looked at it in this
659
659
  * app. `mark` notes a record as they see it now (from `getTopicRecord`
660
660
  * or `listTopics`); `changes` answers with the fields whose value moved
package/index.js CHANGED
@@ -606,7 +606,7 @@ function createAppSdk(transport) {
606
606
  idempotencyKey: options.idempotencyKey ?? oneRequest()
607
607
  }),
608
608
  getExecution,
609
- listRuns: (workflowId, run = {}) => transport.call("listWorkflowExecutions", {
609
+ listRuns: async (workflowId, run = {}) => await transport.call("listWorkflowExecutions", {
610
610
  params: { id: workflowId },
611
611
  query: { topic_id: run.topicId }
612
612
  }),
@@ -842,9 +842,6 @@ function createAppSdk(transport) {
842
842
  watch?.stop();
843
843
  };
844
844
  },
845
- listOutcomes: (page = {}) => transport.call("listOutcomes", {
846
- query: { limit: page.limit, offset: page.offset }
847
- }),
848
845
  lastLooked: {
849
846
  changes: async (record) => {
850
847
  const before = (await lookedAt()).get(record.id);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@almateam/app-sdk",
3
- "version": "0.7.0",
3
+ "version": "0.8.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",