@almateam/app-sdk 0.5.0 → 0.7.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 +178 -22
- package/generated/apiTypes.d.ts +437 -50
- package/index.d.ts +486 -24
- package/index.js +865 -35
- package/navigation.d.ts +21 -0
- package/package.json +2 -2
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.7.0
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
Alma builds an app's source with its own current copy of the SDK, whatever
|
|
@@ -36,8 +36,9 @@ const receipt = await alma.setTopicField(topicId, "stage", "Signed");
|
|
|
36
36
|
|
|
37
37
|
Every call names an Alma `/v1` operation by its OpenAPI operationId
|
|
38
38
|
(`listTopics`, `createTopic`, `listTopicTypes`, `getTopicRecord`,
|
|
39
|
-
`
|
|
40
|
-
`runWorkflow`, `listWorkflowExecutions`, `getExecution`, …);
|
|
39
|
+
`getTopicSummary`, `getTopicFactDiscussion`, `downloadTopicFactAttachment`,
|
|
40
|
+
`setTopicField`, `runWorkflow`, `listWorkflowExecutions`, `getExecution`, …);
|
|
41
|
+
the typed helpers
|
|
41
42
|
wrap `alma.call(operationId, { params, query, body })`. These are the same
|
|
42
43
|
public routes an API key calls, so an app built on them could run off-platform.
|
|
43
44
|
The host refuses an unknown operation, a path parameter that is not a UUID (or,
|
|
@@ -46,10 +47,11 @@ for a field, a field key), and any operation outside the manifest's `scopes`
|
|
|
46
47
|
forwards only the query keys an operation declares.
|
|
47
48
|
|
|
48
49
|
A call resolves once it is done, within 30 seconds, or rejects. A change
|
|
49
|
-
(`setTopicField`, `
|
|
50
|
-
act: it saves as them where they may edit
|
|
51
|
-
cannot. Nobody is asked and no dialog
|
|
52
|
-
result, or rejects with the refusal's
|
|
50
|
+
(`setTopicField`, `deleteTopic`, `restoreTopic`, `createWorkflowLesson`,
|
|
51
|
+
`updateLesson`) is the viewer's own act: it saves as them where they may edit
|
|
52
|
+
that record and is refused where they cannot. Nobody is asked and no dialog
|
|
53
|
+
appears: the promise resolves with the result, or rejects with the refusal's
|
|
54
|
+
words.
|
|
53
55
|
|
|
54
56
|
A lesson added by a viewer who decides the workflow's lessons (its editors and
|
|
55
57
|
the workspace's owners) is live at once: `createWorkflowLesson` resolves with
|
|
@@ -118,7 +120,10 @@ State is a small key/value store per installed app and per person: a filter, a
|
|
|
118
120
|
collapsed column, a half-written draft. Only that person's sessions of that app
|
|
119
121
|
read or write it. It needs no scope and no owner's approval, and declaring
|
|
120
122
|
nothing for it does not widen a version. Nothing in it reaches a workflow run,
|
|
121
|
-
search or anything Alma knows
|
|
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
|
|
122
127
|
survives a reload and a new version of the app, and goes when the app is removed
|
|
123
128
|
from the workspace or the person leaves it. Keys are letters, digits, `_` and
|
|
124
129
|
`-` (up to 128 characters). A value is any JSON up to 16 KB, and one person
|
|
@@ -126,6 +131,78 @@ holds at most 64 keys and 256 KB in one app; a `set` past a limit rejects with a
|
|
|
126
131
|
refusal whose `code` is `app_state.value_too_large` or
|
|
127
132
|
`app_state.quota_exceeded`.
|
|
128
133
|
|
|
134
|
+
## The viewer: which person is looking
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
const viewer = await alma.viewer(); // { person_id } or null
|
|
138
|
+
const isMine = (owner: { topic_id: string } | null) =>
|
|
139
|
+
viewer !== null && owner?.topic_id === viewer.person_id;
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
`viewer()` names the viewer's own `person` record: the one the workspace's
|
|
143
|
+
directory links to their Alma account. The host answers it from the session the
|
|
144
|
+
server opened for the signed-in person, so nothing an app sends can change it.
|
|
145
|
+
An app is told only when its manifest declares the `viewer:read` scope, which an
|
|
146
|
+
owner sees when the app is shared like every other scope; Alma's own apps are
|
|
147
|
+
told under `topics:read`. Read the record itself with `getTopicRecord`, which
|
|
148
|
+
needs `topics:read`. `viewer()` is `null` for an app without the scope, and also
|
|
149
|
+
when no directory entry is linked to the viewer's account, they cannot open that
|
|
150
|
+
record, or the app is open in an Alma tab from before the question. `null` is an
|
|
151
|
+
answer, not a failure; an app that needs to know asks the person then (and can
|
|
152
|
+
keep the answer in state). The host answers from its latest session, so the
|
|
153
|
+
answer can change when the app is reopened.
|
|
154
|
+
|
|
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`.
|
|
158
|
+
|
|
159
|
+
## Who else is here
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
const stop = alma.presence.watch(({ count, people }) => {
|
|
163
|
+
// people: [{ person_id }] with viewer:read, null without it
|
|
164
|
+
});
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
`presence.watch` tells the app who has this installation open right now: once
|
|
168
|
+
the host knows, and again within a second or two of anyone opening or closing
|
|
169
|
+
it. `count` includes the viewer while they are shown. `people` names each
|
|
170
|
+
person once by their `person` record, and only to an app that declares
|
|
171
|
+
`viewer:read`, so `count` can be more than `people` holds when a copy open
|
|
172
|
+
elsewhere names no one; without it, `people` is `null` and `count` counts open
|
|
173
|
+
copies, so one person with two tabs counts twice. Someone is present only
|
|
174
|
+
while their "Show when I'm viewing a task" switch is on and they are not in Do
|
|
175
|
+
not disturb, and they still see who else is. Where the host cannot tell (an
|
|
176
|
+
Alma tab from before the question, or no live connection), the listener is
|
|
177
|
+
never called: no answer means not known, not nobody. It needs no scope.
|
|
178
|
+
|
|
179
|
+
## Quick messages to everyone viewing
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
await alma.broadcast("cursor", { x: 120, y: 48 });
|
|
183
|
+
const stop = alma.onBroadcast("cursor", (payload) => {
|
|
184
|
+
// another viewer's cursor moved
|
|
185
|
+
});
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
`broadcast` sends a quick message to everyone who has this installation open
|
|
189
|
+
right now, and `onBroadcast` calls its listener with the payload of each one
|
|
190
|
+
sent under that event name, within about a second. The sender's own listeners
|
|
191
|
+
are not called unless it passes `{ self: true }` as the third argument. Nothing
|
|
192
|
+
is kept: someone who opens the app later, or whose connection drops for a
|
|
193
|
+
moment, never hears it, so what a late viewer needs goes in shared state. An
|
|
194
|
+
event name is letters, digits, `_`, `.`, `:` and `-` (up to 128 characters),
|
|
195
|
+
and a payload is any JSON up to 8 KB. One viewer may send 20 at once in one
|
|
196
|
+
installation, then 10 a second. A send past a limit rejects with a refusal
|
|
197
|
+
whose `code` is `app_broadcast.payload_too_large` or
|
|
198
|
+
`app_broadcast.rate_limited`. Where the workspace's IP allowlist is in force,
|
|
199
|
+
no message is sent, because it cannot be checked against each listener's
|
|
200
|
+
address: a viewer on an approved network is refused with
|
|
201
|
+
`app_broadcast.ip_allowlist_in_force`, and one outside it is refused like any
|
|
202
|
+
other call. Both need the `shared_state:write` scope; without it, the listener
|
|
203
|
+
is never called.
|
|
204
|
+
`onBroadcast` returns the unsubscribe.
|
|
205
|
+
|
|
129
206
|
## Records: the workspace's typed topics
|
|
130
207
|
|
|
131
208
|
An app's records are the workspace's topics, of the types its manifest declares
|
|
@@ -136,13 +213,53 @@ and its `relationships` (a `label`, the key of the type it points at, such as
|
|
|
136
213
|
app, the workspace's type of that key is reused, gaining what it lacks, or
|
|
137
214
|
created. `listTopics({ type, filter, sort })` reads them as the viewer,
|
|
138
215
|
`setTopicField` changes one as the viewer, and `createTopic(name, typeId)` (the
|
|
139
|
-
id from `listTopicTypes()`) creates one
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
216
|
+
id from `listTopicTypes()`) creates one with the app's audience: who can see it
|
|
217
|
+
is set in Alma, never by the app. `createTopic(name, typeId, { fields })` saves
|
|
218
|
+
the record and its first values in one request, as the viewer's own confirmed
|
|
219
|
+
word, each entry a `key`, a `value` and, for a relationship, a `refTopicId`.
|
|
220
|
+
It needs no scope beyond `facts:confirm`. Nothing is created if one value is
|
|
221
|
+
refused, and the refusal starts with the field's key. A request denied whole,
|
|
222
|
+
such as one with a credential in a value, names no field.
|
|
223
|
+
`deleteTopic(topicId)` deletes one of the app's own records (a type declared
|
|
224
|
+
`"scope": "app"`, which a type naming no scope gets) as the viewer, where they
|
|
225
|
+
can edit it, and Alma keeps it for 30 days; any other record rejects as not
|
|
226
|
+
found. Retried under the same `idempotencyKey`, it answers with the first result
|
|
227
|
+
while the record stays deleted, and deletes it again once it has been restored.
|
|
228
|
+
`restoreTopic(topicId)` is its Undo: the person who deleted one of the app's
|
|
229
|
+
records brings it back within those 30 days, while they can still edit it, and
|
|
230
|
+
it resolves with `{ id, name, cleared }`, where `cleared` lists the values that
|
|
231
|
+
did not come back because they no longer fit the record's type. A record
|
|
232
|
+
somebody else deleted rejects as not found. One past its 30 days rejects with
|
|
233
|
+
the refusal's words until Alma removes it for good, then as not found. Retried
|
|
234
|
+
under the same `idempotencyKey`, it answers with the latest result while the
|
|
235
|
+
record stays restored, and restores it again once it has been deleted again. Someone who
|
|
236
|
+
edits the app can also restore a record from its Data. A relationship's values
|
|
237
|
+
sit under `rel_<label>__<type key>` (`rel_csm__person`). A version declaring a
|
|
238
|
+
type, field or relationship the shared version did not is wider and asks an
|
|
239
|
+
owner; while the app is installed, the workspace's schema editor lists it under
|
|
240
|
+
"Used by" and refuses to retype or remove what it declares.
|
|
241
|
+
|
|
242
|
+
## Views: a type's saved views
|
|
243
|
+
|
|
244
|
+
A type's saved views (the filters, search, sort, grouping and columns its grid
|
|
245
|
+
opens on) are the workspace's, saved in the grid or by Alma. `listViews(type)`
|
|
246
|
+
lists the ones the viewer can open, each `{ key, name, scope }`, and
|
|
247
|
+
`readView(type, key, { cursor, limit })` reads a page of one as the viewer:
|
|
248
|
+
`view`, the `columns` it shows, `data` with each record's values for them, and
|
|
249
|
+
`meta` with `next_cursor`, `total` and, for a grouped view, `groups` counting
|
|
250
|
+
each group. A type the manifest declares can declare its own `views`, made
|
|
251
|
+
shared on the type when the app is shared, so the app reads them by the keys it
|
|
252
|
+
chose.
|
|
253
|
+
|
|
254
|
+
```ts
|
|
255
|
+
const page = await alma.readView("account", "renewals-this-quarter");
|
|
256
|
+
for (const column of page.columns) console.info(column.name, column.kind);
|
|
257
|
+
const next = page.meta.next_cursor
|
|
258
|
+
? await alma.readView("account", "renewals-this-quarter", {
|
|
259
|
+
cursor: page.meta.next_cursor,
|
|
260
|
+
})
|
|
261
|
+
: null;
|
|
262
|
+
```
|
|
146
263
|
|
|
147
264
|
## Workflows: the app's backend
|
|
148
265
|
|
|
@@ -152,13 +269,24 @@ managers and run as they stand. `listWorkflows()` marks them `runnable` where
|
|
|
152
269
|
the viewer may start them, and where they may not gives the reason in
|
|
153
270
|
`not_runnable` (`{ code, reason }`, the sentence `runWorkflow` would refuse
|
|
154
271
|
with): show the control disabled with that reason.
|
|
155
|
-
`runWorkflow(id, { topicId, input })` starts one
|
|
156
|
-
(`POST /v1/workflows/{id}/executions`), with nobody asked
|
|
157
|
-
the app
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
272
|
+
`runWorkflow(id, { topicId, input })` starts one
|
|
273
|
+
(`POST /v1/workflows/{id}/executions`), with nobody asked, where the workflow's
|
|
274
|
+
owner granted the app **Can run** on its access list or the viewer can run it
|
|
275
|
+
themselves, and on a record the viewer can see. Naming a workflow grants the app
|
|
276
|
+
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 })`,
|
|
278
|
+
which polls `GET /v1/executions/{id}` with backoff: a run paused at an approval
|
|
279
|
+
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.
|
|
281
|
+
|
|
282
|
+
A run started on a record can set that record's fields itself, so an app does
|
|
283
|
+
not write a run's outcome. Each run carries `field_writes`: one entry for each
|
|
284
|
+
write the run made to its record, with an `outcome` taken from what the write
|
|
285
|
+
did, not from what the run said. `applied` and `unchanged` carry the stored
|
|
286
|
+
`value` and the field's `revision`; `proposed` means the record asks before
|
|
287
|
+
updating and nothing has changed yet, so show it as waiting for review and never
|
|
288
|
+
as done; `refused` carries `refusal: { code, reason }` to show; `unknown` means
|
|
289
|
+
the write may have completed. A `completed` run may have changed nothing.
|
|
162
290
|
`listRuns(id, { topicId })` finds the runs started on a record when the app is
|
|
163
291
|
opened again.
|
|
164
292
|
|
|
@@ -176,6 +304,34 @@ An attachment download returns only a receipt (`attachment_id`, `filename`,
|
|
|
176
304
|
`status`): the host fetches the file itself, and neither its URL nor the session
|
|
177
305
|
token reaches the app.
|
|
178
306
|
|
|
307
|
+
## Events: what the app tells workflows happened
|
|
308
|
+
|
|
309
|
+
An app can also say that something happened and let the workspace's workflows
|
|
310
|
+
decide what to do about it. The manifest declares each event the app raises
|
|
311
|
+
(`events: [{ name, description }]`, lowercase names such as `score.posted`), and
|
|
312
|
+
the owner approves them when sharing; adding one is a new version to approve.
|
|
313
|
+
`raiseEvent(name, payload)` (`POST /v1/app-events`, with the `events:raise`
|
|
314
|
+
scope) raises one for the viewer: every workflow whose trigger names this app
|
|
315
|
+
and this event starts, as the workflow, with `payload` (a JSON object of at most
|
|
316
|
+
16 KB) as data it does not trust. The answer is the same whether or not a
|
|
317
|
+
workflow listens, so an app cannot tell. The trigger lives on the workflow, so
|
|
318
|
+
raising an event no workflow listens to is fine.
|
|
319
|
+
|
|
320
|
+
An event the shared version does not declare rejects with `event.undeclared`,
|
|
321
|
+
and a draft raises nothing (`app.draft`). Everyone using the app together can
|
|
322
|
+
raise 30 events an hour, after a burst of 10; past that a raise rejects with
|
|
323
|
+
`event.rate_limited`, and its message says how many seconds to wait. Raise an
|
|
324
|
+
event for something a person did, not on a timer.
|
|
325
|
+
|
|
326
|
+
```ts
|
|
327
|
+
try {
|
|
328
|
+
await alma.raiseEvent("score.posted", { player: viewer.name, score });
|
|
329
|
+
} catch (error) {
|
|
330
|
+
if ((error as AppCallError).code === "event.rate_limited") showLater();
|
|
331
|
+
else throw error;
|
|
332
|
+
}
|
|
333
|
+
```
|
|
334
|
+
|
|
179
335
|
## Developing an app
|
|
180
336
|
|
|
181
337
|
The package carries the `alma-app` command, which runs under Node.
|