@almateam/app-sdk 0.7.0 → 0.9.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.9.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), and while a slow connection is still joining, `watch` reads by
159
+ itself, every 5 seconds and less often while nothing 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
 
@@ -190,12 +237,16 @@ right now, and `onBroadcast` calls its listener with the payload of each one
190
237
  sent under that event name, within about a second. The sender's own listeners
191
238
  are not called unless it passes `{ self: true }` as the third argument. Nothing
192
239
  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
240
+ moment, never hears it, so what a late viewer needs goes in shared state. A
241
+ `missed` function in the same options is called when messages may have passed
242
+ unheard: the connection joined late, or dropped and came back. An
194
243
  event name is letters, digits, `_`, `.`, `:` and `-` (up to 128 characters),
195
244
  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,
245
+ installation, then 10 a second, and everyone using the installation together
246
+ may send 60 at once, then 30 a second. A send past a limit rejects with a
247
+ refusal whose `code` is `app_broadcast.payload_too_large`,
248
+ `app_broadcast.rate_limited` or `app_broadcast.installation_rate_limited`.
249
+ Where the workspace's IP allowlist is in force,
199
250
  no message is sent, because it cannot be checked against each listener's
200
251
  address: a viewer on an approved network is refused with
201
252
  `app_broadcast.ip_allowlist_in_force`, and one outside it is refused like any
@@ -274,10 +325,16 @@ with): show the control disabled with that reason.
274
325
  owner granted the app **Can run** on its access list or the viewer can run it
275
326
  themselves, and on a record the viewer can see. Naming a workflow grants the app
276
327
  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 })`,
328
+ not as the viewer; only a step account set to whoever starts the run goes out
329
+ on the viewer's own connection. Follow it with `waitForExecution(run.id, { onUpdate })`,
278
330
  which polls `GET /v1/executions/{id}` with backoff: a run paused at an approval
279
331
  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.
332
+ theirs, not the viewer's), and a failed run's `error` is safe to show. When the
333
+ workflow's last step runs as code and its program finishes it, the run's
334
+ `result` is the JSON the program returned (null otherwise, or past 64 KB);
335
+ `waitForExecution<T>(run.id)` and `listRuns<T>` type it as `T | null`. It is
336
+ read as `response_content` is: whoever started the run gets it unless the run
337
+ read something sensitive, and then gets neither.
281
338
 
282
339
  A run started on a record can set that record's fields itself, so an app does
283
340
  not write a run's outcome. Each run carries `field_writes`: one entry for each
@@ -332,6 +389,119 @@ try {
332
389
  }
333
390
  ```
334
391
 
392
+ ## Publishing an app to the web
393
+
394
+ An app can also be a website anyone opens at `<name>.sites.alma.team`, with no
395
+ sign-in and no Alma around it. The manifest names the site's module
396
+ (`site: { entry: "src/site.tsx" }`), which default-exports `defineSite`:
397
+
398
+ ```tsx
399
+ import { defineSite, definePage } from "@alma/app-sdk";
400
+ import { Frame } from "./Frame";
401
+ import { posts } from "./posts";
402
+
403
+ export default defineSite({
404
+ meta: {
405
+ name: "Field Notes",
406
+ description: "Notes from the field.",
407
+ titleTemplate: "%s · Field Notes",
408
+ favicon: { light: "/_files/icon.png", dark: "/_files/icon-dark.png" },
409
+ },
410
+ layout: Frame,
411
+ pages: [
412
+ {
413
+ path: "/",
414
+ component: () => import("./pages/Home"),
415
+ meta: () => ({ title: "Home" }),
416
+ },
417
+ definePage({
418
+ path: "/notes/:slug",
419
+ addresses: () => posts.map((post) => ({ slug: post.slug })),
420
+ load: ({ slug }) => posts.find((post) => post.slug === slug)!,
421
+ component: () => import("./pages/Note"),
422
+ meta: ({ data }) => ({ title: data.title, description: data.summary }),
423
+ }),
424
+ ],
425
+ redirects: [{ from: "/journal/*", to: "/", status: 301 }],
426
+ files: { "llms.txt": ({ origin }) => `Notes live at ${origin}/\n` },
427
+ embeds: ["https://calendar.google.com"],
428
+ });
429
+ ```
430
+
431
+ Alma builds every address of every page to its own HTML document when it
432
+ builds the version: a page with parameters (`:slug`) is built at each address
433
+ its `addresses` lists, and only there. `load` runs then, and again in the
434
+ browser when a visitor moves to the page, so it returns plain JSON. Each page
435
+ gets its title, description, canonical address, Open Graph and X tags from its
436
+ `meta`, and the site gets `sitemap.xml`, `robots.txt` and a `404.html`
437
+ (`notFound`, or a plain one). An address names a page without a trailing slash;
438
+ where a static segment and a parameter could both fit, the static one wins. A
439
+ redirect's `from` is one address or a prefix ending `/*`, which moves the
440
+ prefix itself and everything under it; an address a page lists is served by
441
+ the page. `throw notFound()` from `load` sends the visitor to the not-found
442
+ page.
443
+
444
+ The site kit, `@alma/app-ui/site`, starts the site in the browser and moves
445
+ between pages without reloading. A site carries none of Alma's styles, theme or
446
+ fonts: it is the site's own CSS throughout.
447
+
448
+ ```tsx
449
+ import { Link, Markdown, useAlma, usePath, useSite } from "@alma/app-ui/site";
450
+ ```
451
+
452
+ `Link` moves within the site (and is an ordinary link to anywhere else),
453
+ `usePath` and `useSite` say where the visitor is and on which origin, and
454
+ `Markdown` draws a `.md` file's tokens. A capitalised tag in the Markdown
455
+ (`<Callout kind="note">`) is one of the site's components, passed in
456
+ `components`; a name it was not given, or any other HTML, fails the build.
457
+
458
+ A visitor is nobody Alma knows, so the SDK on a site (`useAlma()`, or
459
+ `createAppSdk(siteTransport())`) can only raise the events the version declares;
460
+ `viewer()` and `shell()` answer null, and everything else rejects with
461
+ `site.no_viewer`. Where an event's workflow answers the visitor, the raise
462
+ returns a `result` ticket: `waitForResult(result.token)` reads the answer, and
463
+ the ticket's `url` is a page that reads the token from its fragment
464
+ (`readResultToken()`). A visitor who raises too many rejects with
465
+ `visitor.rate_limited`, and a site past its events for now with `site.paused`;
466
+ both are a `SiteRefusalError` whose `retryAfterSeconds` says when to try again.
467
+
468
+ ```ts
469
+ const alma = useAlma();
470
+ try {
471
+ const raised = await alma.raiseEvent("signup.requested", { email });
472
+ if (raised.result) setAnswer(await alma.waitForResult(raised.result.token));
473
+ } catch (error) {
474
+ if (isSiteRefusal(error)) showLater(error.retryAfterSeconds);
475
+ else throw error;
476
+ }
477
+ ```
478
+
479
+ A site's pictures, fonts, PDFs and audio are files, not source. Put them in
480
+ one flat folder, `_site-files` in the app's folder by default (or name another
481
+ with `--files <folder>`), and refer to each from a page as `/_files/<name>`:
482
+ `_site-files/cover.webp` is `/_files/cover.webp`. A name is letters, digits,
483
+ dots, dashes and underscores, and a folder inside the folder is refused. The
484
+ types are `png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `ico`, `woff2`, `woff`,
485
+ `ttf`, `otf`, `pdf`, `mp3`, `m4a`, `aac`, `ogg`, `oga`, `opus`, `wav`, `weba`
486
+ and `flac`; an SVG is imported from the source instead. A file is at most
487
+ 50 MB, and a site has at most 200 files and 200 MB.
488
+
489
+ `alma-app dev` and `alma-app push` upload the files that are new or changed
490
+ since `site-files.json` (in the app's folder), record them there, and then push
491
+ the source, so the build finds every `/_files/` address it refers to. A push
492
+ that starts a new app records the files, pushes, and uploads them all to the
493
+ app it created. A folder that is not there leaves the push as it is. Only the
494
+ command can upload these files: an AI client cannot. If `site-files.json`
495
+ already lists a file the app never received (it came from another app or
496
+ machine), take its entry out and push again.
497
+
498
+ ```sh
499
+ npx alma-app push ./app --files ./_site-files --org <organization id>
500
+ ```
501
+
502
+ Sharing a version that has a site with "Anyone on the internet" needs a
503
+ workspace owner's approval, like every change to what it serves.
504
+
335
505
  ## Developing an app
336
506
 
337
507
  The package carries the `alma-app` command, which runs under Node.
@@ -340,8 +510,9 @@ source (`manifest.json` beside `index.html`, and the `.tsx`, `.ts`, `.jsx`,
340
510
  `.js`, `.mjs`, `.css`, `.html`, `.svg` and `.json` files around it, leaving out
341
511
  `node_modules`, `dist`, `build`, dotfiles and lockfiles) as a new draft version
342
512
  now and on every save, signed in as you in the browser; Alma builds it and your
343
- draft moves to it. Without `--app` the first push starts a new app; a member of
344
- several workspaces names one with `--org <organization id>`.
513
+ draft moves to it. `npx alma-app push` pushes once. Without `--app` the first
514
+ push starts a new app; a member of several workspaces names one with
515
+ `--org <organization id>`.
345
516
 
346
517
  While you have your own app open, what it logs (`console`) and every error it
347
518
  does not catch show in its Manage sheet, under Logs, beside how the workflows it
package/callError.d.ts ADDED
@@ -0,0 +1,21 @@
1
+ import type * as Api from "./generated/apiTypes";
2
+ /** A field as it stands: its revision and the values it holds. */
3
+ export interface FieldState {
4
+ revision: string;
5
+ values: {
6
+ text: string;
7
+ typed: Api.TypedValue | null;
8
+ }[];
9
+ }
10
+ /** A refused call. `message` is the refusal's words, to show as they are.
11
+ * A refusal a program can act on also carries its `code`; `field.changed`
12
+ * carries the field as it stands in `current`, and
13
+ * `app_shared_state.revision_conflict` the shared key. */
14
+ export declare class AppCallError extends Error {
15
+ readonly code: string | undefined;
16
+ readonly current: FieldState | Api.AppSharedStateEntry | undefined;
17
+ constructor(message: string, detail?: {
18
+ code?: string;
19
+ current?: FieldState | Api.AppSharedStateEntry;
20
+ });
21
+ }