@almateam/app-sdk 0.8.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 +127 -9
- package/callError.d.ts +21 -0
- package/cli.js +404 -35
- package/index.d.ts +49 -35
- package/index.js +618 -17
- 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
|
|
@@ -155,8 +155,8 @@ listener with every key, then with each key as it changes, whoever changed it,
|
|
|
155
155
|
within a second or two, and with `exists: false` for a key deleted; it returns
|
|
156
156
|
the unsubscribe. An app never polls: where the host cannot tell (an Alma tab
|
|
157
157
|
from before it, the check Alma runs on a new version, or a channel the server
|
|
158
|
-
refuses),
|
|
159
|
-
changes.
|
|
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
160
|
|
|
161
161
|
Keep what each person changes under a key of their own, so two people writing
|
|
162
162
|
at once never write over each other, and keep that key the same between visits
|
|
@@ -237,12 +237,16 @@ right now, and `onBroadcast` calls its listener with the payload of each one
|
|
|
237
237
|
sent under that event name, within about a second. The sender's own listeners
|
|
238
238
|
are not called unless it passes `{ self: true }` as the third argument. Nothing
|
|
239
239
|
is kept: someone who opens the app later, or whose connection drops for a
|
|
240
|
-
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
|
|
241
243
|
event name is letters, digits, `_`, `.`, `:` and `-` (up to 128 characters),
|
|
242
244
|
and a payload is any JSON up to 8 KB. One viewer may send 20 at once in one
|
|
243
|
-
installation, then 10 a second
|
|
244
|
-
|
|
245
|
-
|
|
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,
|
|
246
250
|
no message is sent, because it cannot be checked against each listener's
|
|
247
251
|
address: a viewer on an approved network is refused with
|
|
248
252
|
`app_broadcast.ip_allowlist_in_force`, and one outside it is refused like any
|
|
@@ -385,6 +389,119 @@ try {
|
|
|
385
389
|
}
|
|
386
390
|
```
|
|
387
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
|
+
|
|
388
505
|
## Developing an app
|
|
389
506
|
|
|
390
507
|
The package carries the `alma-app` command, which runs under Node.
|
|
@@ -393,8 +510,9 @@ source (`manifest.json` beside `index.html`, and the `.tsx`, `.ts`, `.jsx`,
|
|
|
393
510
|
`.js`, `.mjs`, `.css`, `.html`, `.svg` and `.json` files around it, leaving out
|
|
394
511
|
`node_modules`, `dist`, `build`, dotfiles and lockfiles) as a new draft version
|
|
395
512
|
now and on every save, signed in as you in the browser; Alma builds it and your
|
|
396
|
-
draft moves to it.
|
|
397
|
-
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>`.
|
|
398
516
|
|
|
399
517
|
While you have your own app open, what it logs (`console`) and every error it
|
|
400
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
|
+
}
|