@almateam/app-sdk 0.6.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 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.6.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
- `getTopicFactDiscussion`, `downloadTopicFactAttachment`, `setTopicField`,
40
- `runWorkflow`, `listWorkflowExecutions`, `getExecution`, …); the typed helpers
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`, `createWorkflowLesson`, `updateLesson`) is the viewer's own
50
- act: it saves as them where they may edit that record and is refused where they
51
- cannot. Nobody is asked and no dialog appears: the promise resolves with the
52
- result, or rejects with the refusal's words.
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; there is no store an app's people share. It
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: the host shows Alma's own access sheet,
140
- starting from the app's audience, and the viewer chooses who can see it. A
141
- relationship's values sit under `rel_<label>__<type key>` (`rel_csm__person`). A
142
- version declaring a type, field or relationship the shared version did not is
143
- wider and asks an owner; while the app is installed, the workspace's schema
144
- editor lists it under "Used by" and refuses to retype or remove what it
145
- declares.
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,15 @@ 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 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
159
- `GET /v1/executions/{id}` with backoff: a run paused at an approval step reads
160
- `waiting`, with the people it waits on in `approvers` (its Task is theirs, not
161
- the viewer's), and a failed run's `error` is safe to show.
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.
162
281
 
163
282
  A run started on a record can set that record's fields itself, so an app does
164
283
  not write a run's outcome. Each run carries `field_writes`: one entry for each
@@ -185,6 +304,34 @@ An attachment download returns only a receipt (`attachment_id`, `filename`,
185
304
  `status`): the host fetches the file itself, and neither its URL nor the session
186
305
  token reaches the app.
187
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
+
188
335
  ## Developing an app
189
336
 
190
337
  The package carries the `alma-app` command, which runs under Node.