@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 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.8.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), `watch` reads by itself, every 5 seconds and less often while nothing
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. 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
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. A send past a limit rejects with a refusal
244
- whose `code` is `app_broadcast.payload_too_large` or
245
- `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,
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. Without `--app` the first push starts a new app; a member of
397
- 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>`.
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
+ }