@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 +71 -18
- package/generated/apiTypes.d.ts +11 -23
- package/index.d.ts +15 -15
- package/index.js +1 -4
- 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.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
|
|
117
|
-
|
|
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.
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
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
|
-
|
|
156
|
-
|
|
157
|
-
the
|
|
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
|
|
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
|
package/generated/apiTypes.d.ts
CHANGED
|
@@ -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<
|
|
541
|
+
}) => Promise<AppExecutionOf<T>[]>;
|
|
536
542
|
/** Polls a run with backoff until it finishes, and resolves with how it
|
|
537
|
-
* ended
|
|
538
|
-
* `signal` to
|
|
539
|
-
|
|
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.
|
|
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",
|