@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 +195 -24
- package/callError.d.ts +21 -0
- package/cli.js +404 -35
- package/generated/apiTypes.d.ts +11 -23
- package/index.d.ts +64 -50
- package/index.js +619 -21
- package/package.json +1 -1
- package/site.d.ts +267 -0
- package/siteRuntime.d.ts +69 -0
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.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
|
|
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), 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
|
-
|
|
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
|
|
|
@@ -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.
|
|
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
|
|
197
|
-
|
|
198
|
-
|
|
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
|
|
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.
|
|
344
|
-
several workspaces names one with
|
|
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
|
+
}
|