@almateam/app-sdk 0.8.0 → 0.10.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,19 +8,18 @@ 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.10.0
12
12
  ```
13
13
 
14
14
  Alma builds an app's source with its own current copy of the SDK, whatever
15
15
  version the source installs or pins, so the copy you install never ships. The
16
16
  SDK's runtime has no dependency and holds no credential (the `alma-app` command
17
- uses the MCP client); an app runs in Alma's isolated frame and talks to its host
18
- through it:
17
+ uses the MCP client). An app is one set of screens (see "Screens" below); in
18
+ Alma's isolated frame its SDK, `useAlma()` from `@alma/app-ui`, talks to the
19
+ host as the member viewing it:
19
20
 
20
21
  ```ts
21
- import { createAppSdk, hostTransport } from "@alma/app-sdk";
22
-
23
- const alma = createAppSdk(hostTransport());
22
+ const alma = useAlma();
24
23
  const page = await alma.listTopics({
25
24
  type: "account",
26
25
  filter: ["stage:eq:Live"],
@@ -155,8 +154,8 @@ listener with every key, then with each key as it changes, whoever changed it,
155
154
  within a second or two, and with `exists: false` for a key deleted; it returns
156
155
  the unsubscribe. An app never polls: where the host cannot tell (an Alma tab
157
156
  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.
157
+ refuses), and while a slow connection is still joining, `watch` reads by
158
+ itself, every 5 seconds and less often while nothing changes.
160
159
 
161
160
  Keep what each person changes under a key of their own, so two people writing
162
161
  at once never write over each other, and keep that key the same between visits
@@ -237,12 +236,16 @@ right now, and `onBroadcast` calls its listener with the payload of each one
237
236
  sent under that event name, within about a second. The sender's own listeners
238
237
  are not called unless it passes `{ self: true }` as the third argument. Nothing
239
238
  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
239
+ moment, never hears it, so what a late viewer needs goes in shared state. A
240
+ `missed` function in the same options is called when messages may have passed
241
+ unheard: the connection joined late, or dropped and came back. An
241
242
  event name is letters, digits, `_`, `.`, `:` and `-` (up to 128 characters),
242
243
  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,
244
+ installation, then 10 a second, and everyone using the installation together
245
+ may send 60 at once, then 30 a second. A send past a limit rejects with a
246
+ refusal whose `code` is `app_broadcast.payload_too_large`,
247
+ `app_broadcast.rate_limited` or `app_broadcast.installation_rate_limited`.
248
+ Where the workspace's IP allowlist is in force,
246
249
  no message is sent, because it cannot be checked against each listener's
247
250
  address: a viewer on an approved network is refused with
248
251
  `app_broadcast.ip_allowlist_in_force`, and one outside it is refused like any
@@ -385,16 +388,176 @@ try {
385
388
  }
386
389
  ```
387
390
 
391
+ ## Screens: one app in Alma and on the web
392
+
393
+ An app is one module, `src/app.tsx` (or the module the manifest names in
394
+ `screens: { entry }`), that default-exports `defineApp`. Members see its
395
+ routes in Alma's frame; published, anyone sees them at
396
+ `<name>.sites.alma.team`, with no sign-in and no Alma around them. It is the
397
+ same source in both places:
398
+
399
+ ```tsx
400
+ import { defineApp, defineRoute } from "@alma/app-sdk";
401
+ import { Frame } from "./Frame";
402
+ import { posts } from "./posts";
403
+
404
+ export default defineApp({
405
+ meta: {
406
+ name: "Field Notes",
407
+ description: "Notes from the field.",
408
+ titleTemplate: "%s · Field Notes",
409
+ favicon: { light: "/_files/icon.png", dark: "/_files/icon-dark.png" },
410
+ },
411
+ layout: Frame,
412
+ routes: [
413
+ {
414
+ path: "/",
415
+ component: () => import("./pages/Home"),
416
+ meta: () => ({ title: "Home" }),
417
+ },
418
+ { path: "/desk", audience: "members", component: () => import("./Desk") },
419
+ defineRoute({
420
+ path: "/notes/:slug",
421
+ addresses: () => posts.map((post) => ({ slug: post.slug })),
422
+ load: ({ slug }) => posts.find((post) => post.slug === slug)!,
423
+ component: () => import("./pages/Note"),
424
+ meta: ({ data }) => ({ title: data.title, description: data.summary }),
425
+ }),
426
+ ],
427
+ redirects: [{ from: "/journal/*", to: "/", status: 301 }],
428
+ files: { "llms.txt": ({ origin }) => `Notes live at ${origin}/\n` },
429
+ embeds: ["https://calendar.google.com"],
430
+ });
431
+ ```
432
+
433
+ A route is for members and the public both, unless its `audience` says
434
+ `members` (only in Alma: never built at the published address) or `public`
435
+ (only there). One path may be a members' screen and a public one. `meta`,
436
+ `themeScript`, `fonts`, `files` and `embeds` describe the published address;
437
+ an app that only members see needs none of them.
438
+
439
+ Published, Alma builds every address of every public route to its own HTML
440
+ document when it builds the version: a route with parameters (`:slug`) is
441
+ built at each address its `addresses` lists, and only there (in Alma, every
442
+ address that fits is the route's). `load` runs then, and again in the browser
443
+ when a person moves to the route, so it returns plain JSON. Each public route
444
+ gets its title, description, canonical address, Open Graph and X tags from its
445
+ `meta`, which it must have, and the site gets `sitemap.xml`, `robots.txt` and
446
+ a `404.html` (`notFound`, or a plain one). An address names a route without a
447
+ trailing slash; where a static segment and a parameter could both fit, the
448
+ static one wins. A redirect's `from` is one address or a prefix ending `/*`,
449
+ which moves the prefix itself and everything under it; an address a route
450
+ lists is served by the route. `throw notFound()` from `load` shows the
451
+ not-found screen.
452
+
453
+ Alma's build starts the app with `startApp` from the kit: at the published
454
+ address it takes up the page the build rendered, over the site's transport
455
+ and the browser's history; in Alma's frame it renders the route at the
456
+ host's address, over the host's transport and history. Either way it moves
457
+ between routes without loading a document.
458
+
459
+ ```tsx
460
+ import {
461
+ Link,
462
+ Markdown,
463
+ useAlma,
464
+ useApp,
465
+ useFileUrl,
466
+ usePath,
467
+ } from "@alma/app-ui";
468
+ ```
469
+
470
+ `Link` moves within the app; to anywhere else it is an ordinary link at the
471
+ published address, and in Alma the host opens it in a new tab when a person
472
+ clicks it (the frame never loads a document of its own). `usePath` and
473
+ `useApp` say where the person is, in which place (`frame` or `public`) and on
474
+ which origin, and `Markdown` draws a `.md` file's tokens. A capitalised tag in
475
+ the Markdown (`<Callout kind="note">`) is one of the app's components, passed
476
+ in `components`; a name it was not given, or any other HTML, fails the build.
477
+
478
+ Neither build adds anything of Alma's look to an app that does not ask, so a
479
+ member and a visitor see what the author wrote. To stand on Alma's (its
480
+ tokens, Geist, the accent and the kit's Theme knobs, beneath the app's own
481
+ CSS, and Alma's tokens on its Tailwind utilities), import it once, in both
482
+ places alike:
483
+
484
+ ```ts
485
+ import "@alma/app-ui/base.css";
486
+ ```
487
+
488
+ In Alma, `useAlma()` is the member's SDK. A visitor is nobody Alma knows, so
489
+ at the published address it can only raise the events the version declares;
490
+ `viewer()` and `shell()` answer null, and everything else rejects with
491
+ `site.no_viewer`. Where an event's workflow answers the visitor, the raise
492
+ returns a `result` ticket: `waitForResult(result.token)` reads the answer, and
493
+ the ticket's `url` is a page that reads the token from its fragment
494
+ (`readResultToken()`). A visitor who raises too many rejects with
495
+ `visitor.rate_limited`, and a site past its events for now with `site.paused`;
496
+ both are a `SiteRefusalError` whose `retryAfterSeconds` says when to try again.
497
+
498
+ ```ts
499
+ const alma = useAlma();
500
+ try {
501
+ const raised = await alma.raiseEvent("signup.requested", { email });
502
+ if (raised.result) setAnswer(await alma.waitForResult(raised.result.token));
503
+ } catch (error) {
504
+ if (isSiteRefusal(error)) showLater(error.retryAfterSeconds);
505
+ else throw error;
506
+ }
507
+ ```
508
+
509
+ An app's pictures, fonts, PDFs and audio are files, not source. Put them in
510
+ one flat folder, `_site-files` in the app's folder by default (or name another
511
+ with `--files <folder>`), and show each with `useFileUrl("<name>")`, which is
512
+ `/_files/<name>` at the published address and, in Alma's frame (which reaches
513
+ no network), a blob: URL of the bytes the host hands over; Markdown's
514
+ `![…](/_files/<name>)` does the same. In the frame an `<img>`, `<audio>`,
515
+ `<video>` or `<source>` written with `src="/_files/<name>"`, and a stylesheet's
516
+ `url(/_files/<name>)` (a font's `@font-face`, a background), are pointed at the
517
+ same bytes, so the screens look the same in both places; a `Link` to
518
+ `/_files/<name>`, or to a declared plain file, saves the file there.
519
+ `_site-files/cover.webp` is `useFileUrl("cover.webp")`. A name is letters, digits,
520
+ dots, dashes and underscores, and a folder inside the folder is refused. The
521
+ types are `png`, `jpg`, `jpeg`, `gif`, `webp`, `avif`, `ico`, `woff2`, `woff`,
522
+ `ttf`, `otf`, `pdf`, `mp3`, `m4a`, `aac`, `ogg`, `oga`, `opus`, `wav`, `weba`
523
+ and `flac`; an SVG is imported from the source instead. A file is at most
524
+ 50 MB, and a site has at most 200 files and 200 MB.
525
+
526
+ `alma-app dev` and `alma-app push` upload the files that are new or changed
527
+ since `site-files.json` (in the app's folder), record them there, and then push
528
+ the source, so the build finds every `/_files/` address it refers to. A push
529
+ that starts a new app records the files, pushes, and uploads them all to the
530
+ app it created. A folder that is not there leaves the push as it is. Only the
531
+ command can upload these files: an AI client cannot. If `site-files.json`
532
+ already lists a file the app never received (it came from another app or
533
+ machine), take its entry out and push again.
534
+
535
+ ```sh
536
+ npx alma-app push ./app --files ./_site-files --org <organization id>
537
+ ```
538
+
539
+ Publishing a version follows the workspace's approval level for sharing apps;
540
+ going public counts as widening who sees it.
541
+
388
542
  ## Developing an app
389
543
 
390
544
  The package carries the `alma-app` command, which runs under Node.
391
545
  `npx alma-app dev [folder] --app <app id>` (or `bunx`) pushes the folder's
392
- source (`manifest.json` beside `index.html`, and the `.tsx`, `.ts`, `.jsx`,
393
- `.js`, `.mjs`, `.css`, `.html`, `.svg` and `.json` files around it, leaving out
394
- `node_modules`, `dist`, `build`, dotfiles and lockfiles) as a new draft version
546
+ source (`manifest.json` beside `src/`, and the `.tsx`, `.ts`, `.jsx`,
547
+ `.js`, `.mjs`, `.css`, `.html`, `.svg`, `.json`, `.md` and `.txt` files around
548
+ it, leaving out `node_modules`, `dist`, `build`, dotfiles and lockfiles) as a
549
+ new draft version
395
550
  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>`.
551
+ draft moves to it. `npx alma-app push` pushes once. Without `--app` the first
552
+ push starts a new app; a member of several workspaces names one with
553
+ `--org <organization id>`.
554
+
555
+ An app written as one page (`index.html` loading its own script) becomes an
556
+ app with screens with `npx alma-app convert [folder]`: the page's body and
557
+ scripts become the one members' route, on Alma's look as before, and the
558
+ manifest names `screens.entry`. An inline or outside script, or a head element
559
+ other than the title and the page's own stylesheets, is not carried over:
560
+ the command names each and changes nothing.
398
561
 
399
562
  While you have your own app open, what it logs (`console`) and every error it
400
563
  does not catch show in its Manage sheet, under Logs, beside how the workflows it
package/app.d.ts ADDED
@@ -0,0 +1,297 @@
1
+ /** The literal every absolute URL is written with at build time. A build
2
+ * does not know where its app will be published; publishing replaces this
3
+ * in every text file with the address's own origin. */
4
+ export declare const SITE_ORIGIN_TOKEN = "__ALMA_SITE_ORIGIN__";
5
+ /** The id `assetsFor` and a route's hydration data name the not-found
6
+ * screen by. Every route is named by its `path`, which starts with `/`. */
7
+ export declare const NOT_FOUND_ROUTE_ID = "404";
8
+ /** Where an app is running: inside Alma's frame for a member, or at its
9
+ * published address for anyone. */
10
+ export type AppPlace = "frame" | "public";
11
+ /** Who a route is for: `members` in Alma's frame only, `public` at the
12
+ * published address only. A route that names neither is in both. */
13
+ export type RouteAudience = "members" | "public";
14
+ /** A route's parameters, by the names its `path` gives them (`:slug`). */
15
+ export type RouteParams = Record<string, string>;
16
+ export type JsonValue = string | number | boolean | null | JsonValue[] | {
17
+ [key: string]: JsonValue;
18
+ };
19
+ export type JsonLd = {
20
+ [key: string]: JsonValue;
21
+ };
22
+ /** A title and description shown where a page is shared, when they are not
23
+ * the page's own. */
24
+ export interface SharedText {
25
+ title?: string;
26
+ description?: string;
27
+ }
28
+ /** What one route says about itself in its published document's head. */
29
+ export interface RouteMeta {
30
+ title: string;
31
+ /** The title shown as it is, without the app's `titleTemplate`. */
32
+ absoluteTitle?: boolean;
33
+ description?: string;
34
+ /** The route's own address (a path), when it is not the address it was
35
+ * served at. */
36
+ canonical?: string;
37
+ /** A path on the published address (`/_files/cover.png`) or an absolute
38
+ * https URL. */
39
+ image?: string;
40
+ imageAlt?: string;
41
+ /** Open Graph `og:type`; `website` unless said. */
42
+ type?: "website" | "article";
43
+ /** What Open Graph shows, where it is not the route's title, description
44
+ * and image (or the app's `openGraph`). */
45
+ openGraph?: SharedText & {
46
+ image?: string;
47
+ };
48
+ /** What X shows, where it is not the route's title and description (or
49
+ * the app's `x`). */
50
+ x?: SharedText;
51
+ /** Kept out of search engines and the sitemap. */
52
+ noindex?: boolean;
53
+ jsonLd?: JsonLd | JsonLd[];
54
+ }
55
+ /** What the whole app says about itself at its published address, beneath
56
+ * every route's own meta. */
57
+ export interface AppMeta {
58
+ name: string;
59
+ description?: string;
60
+ /** The document's `lang`; `en` unless said. */
61
+ lang?: string;
62
+ /** Open Graph `og:locale`, such as `en_US`. */
63
+ locale?: string;
64
+ /** How a route's title is shown, with `%s` where it goes. Without one a
65
+ * route's title is used as it is. */
66
+ titleTemplate?: string;
67
+ /** The image a route without its own shares with, and its size in
68
+ * pixels. */
69
+ image?: string;
70
+ imageAlt?: string;
71
+ imageWidth?: number;
72
+ imageHeight?: number;
73
+ /** What Open Graph and X show for a route that gives none of its own:
74
+ * without these, the route's title and description. */
75
+ openGraph?: SharedText;
76
+ x?: SharedText;
77
+ /** The app's account on X, such as `@alma`. */
78
+ twitter?: string;
79
+ /** One icon, or one for each colour scheme. */
80
+ favicon?: string | {
81
+ light: string;
82
+ dark: string;
83
+ };
84
+ themeColor?: string | {
85
+ light: string;
86
+ dark: string;
87
+ };
88
+ /** Addresses search engines are asked not to crawl. */
89
+ robots?: {
90
+ disallow?: string[];
91
+ };
92
+ jsonLd?: JsonLd | JsonLd[];
93
+ }
94
+ /** What a route's component is rendered with. */
95
+ export interface RouteProps<D = unknown> {
96
+ params: RouteParams;
97
+ data: D;
98
+ path: string;
99
+ }
100
+ export type RouteComponent<D = unknown> = {
101
+ bivarianceHack(props: RouteProps<D>): unknown;
102
+ }["bivarianceHack"];
103
+ export type AppLayout = {
104
+ bivarianceHack(props: {
105
+ children: unknown;
106
+ path: string;
107
+ }): unknown;
108
+ }["bivarianceHack"];
109
+ export interface RouteMetaContext<D = unknown> {
110
+ params: RouteParams;
111
+ data: D;
112
+ /** The address being described. */
113
+ path: string;
114
+ app: AppMeta;
115
+ }
116
+ export interface SitemapOptions {
117
+ changeFrequency?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
118
+ /** From 0 to 1. */
119
+ priority?: number;
120
+ /** An ISO 8601 date. */
121
+ lastModified?: string;
122
+ }
123
+ export interface AppRoute<D = unknown> {
124
+ /** `/`, `/about`, or a pattern with parameters such as `/blog/:slug`. */
125
+ path: string;
126
+ /** Who the route is for; members and the public both unless said. A
127
+ * route is not routable where its audience is not: a `members` route
128
+ * is never built at the published address, and a `public` one is not
129
+ * in Alma's frame. */
130
+ audience?: RouteAudience;
131
+ /** The route's own module, split from every other route's at the
132
+ * published address. */
133
+ component(): Promise<{
134
+ default: RouteComponent<D>;
135
+ }>;
136
+ /** Every parameter set a pattern is published at. A public route with
137
+ * parameters must list them: an address no route lists is not built.
138
+ * In Alma's frame every address that fits the pattern is the route's. */
139
+ addresses?(): RouteParams[] | Promise<RouteParams[]>;
140
+ /** The route's data, read when its public address is built, and in the
141
+ * browser whenever a person moves to it. It must be plain JSON. */
142
+ load?(params: RouteParams): D | Promise<D>;
143
+ /** The route's document head at the published address, which a public
144
+ * route must have. */
145
+ meta?(context: RouteMetaContext<D>): RouteMeta;
146
+ /** Left out of the sitemap with `false`; listed by default. */
147
+ sitemap?: boolean | SitemapOptions;
148
+ }
149
+ /** The statuses a redirect may answer with: 301 and 308 for a permanent
150
+ * move, 302 and 307 for a temporary one. */
151
+ export declare const SITE_REDIRECT_STATUSES: readonly [301, 302, 307, 308];
152
+ /** A move. `from` is one address, or a prefix ending `/*` that moves the
153
+ * prefix itself and every address under it. `to` is one address of this
154
+ * app or an absolute https URL, used as it is. */
155
+ export interface SiteRedirect {
156
+ from: string;
157
+ to: string;
158
+ status: (typeof SITE_REDIRECT_STATUSES)[number];
159
+ }
160
+ export interface SiteFont {
161
+ /** A path on the published address, such as `/_files/inter.woff2`. */
162
+ href: string;
163
+ /** `font/woff2` unless said. */
164
+ type?: string;
165
+ }
166
+ /** A plain file the published address serves, by its path (`llms.txt`). */
167
+ export type SiteFile = string | ((context: {
168
+ origin: string;
169
+ app: AppMeta;
170
+ }) => string | Promise<string>);
171
+ /** One app's screens, which `src/app.tsx` default-exports. Members see the
172
+ * routes for them in Alma's frame; visitors see the public ones at the
173
+ * published address, each prerendered. `meta`, `themeScript`, `fonts`,
174
+ * `files` and `embeds` describe the published address alone. */
175
+ export interface AppDefinition {
176
+ routes: AppRoute[];
177
+ /** Wraps every route, the not-found screen included. */
178
+ layout?: AppLayout;
179
+ /** The screen shown at an address no route has. */
180
+ notFound?: {
181
+ component(): Promise<{
182
+ default: RouteComponent<null>;
183
+ }>;
184
+ meta?: RouteMeta;
185
+ };
186
+ redirects?: SiteRedirect[];
187
+ /** The published address's name and head; an app needs it to publish. */
188
+ meta?: AppMeta;
189
+ /** Run first in every published document's head, before anything
190
+ * paints, to set the colour scheme. Without one it is
191
+ * `DEFAULT_THEME_SCRIPT`. */
192
+ themeScript?: string;
193
+ /** Fonts every published document preloads. */
194
+ fonts?: SiteFont[];
195
+ files?: Record<string, SiteFile>;
196
+ /** Origins the published routes may frame, such as
197
+ * `https://calendar.google.com`. */
198
+ embeds?: string[];
199
+ }
200
+ /** Sets `<html data-theme>` from the visitor's saved choice
201
+ * (`localStorage["alma-site-theme"]`) or their system's scheme. */
202
+ export declare const DEFAULT_THEME_SCRIPT: string;
203
+ export declare function defineApp(app: AppDefinition): AppDefinition;
204
+ /** A route whose `load`, component and `meta` share one data type. */
205
+ export declare function defineRoute<D>(route: AppRoute<D>): AppRoute;
206
+ /** The app as it is in `place`: only the routes whose audience is there. */
207
+ export declare function appIn(app: AppDefinition, place: AppPlace): AppDefinition;
208
+ /** Thrown from a route's `load`: this address has no route. */
209
+ export declare function notFound(): Error;
210
+ export declare function isNotFound(error: unknown): boolean;
211
+ /** Why `address` is not a clean address (`/` or `/a/b`: no trailing slash,
212
+ * no empty, dot or `index.html` segment, no query or fragment), or null. */
213
+ export declare function siteAddressProblem(address: string): string | null;
214
+ /** The parameters `address` gives `pattern`, or null where it does not fit. */
215
+ export declare function matchPattern(pattern: string, address: string): RouteParams | null;
216
+ /** The address a pattern makes with `params`, each value encoded. */
217
+ export declare function fillPattern(pattern: string, params: RouteParams): string;
218
+ /** The redirect that moves `address`, as the edge applies them: one whose
219
+ * `from` is the address itself first, then the longest `/*` prefix that
220
+ * is the address or one of its parents. */
221
+ export declare function matchRedirect(redirects: readonly SiteRedirect[], address: string): SiteRedirect | null;
222
+ export type AddressMatch<R extends {
223
+ path: string;
224
+ } = AppRoute> = {
225
+ kind: "route";
226
+ route: R;
227
+ params: RouteParams;
228
+ } | {
229
+ kind: "redirect";
230
+ redirect: SiteRedirect;
231
+ };
232
+ /** What an app shows at `address` among the routes it is given (one
233
+ * place's, from `appIn`): a route and its parameters, a redirect, or null
234
+ * for its not-found screen. A route whose path is the address, and a
235
+ * redirect from exactly the address, are one key at the edge and so come
236
+ * first (an app may not have both); then a route whose pattern fits, a
237
+ * static segment winning over a parameter; then a `/*` redirect.
238
+ *
239
+ * The edge holds only the addresses the build listed. Given them as
240
+ * `listed`, a route with parameters fits only an address it listed, and
241
+ * any other falls through to the redirects, so the answer is the edge's
242
+ * own. Without them, every address that fits a pattern is that route's. */
243
+ export declare function matchAddress<R extends {
244
+ path: string;
245
+ }>(app: {
246
+ routes: readonly R[];
247
+ redirects?: readonly SiteRedirect[];
248
+ }, address: string, listed?: ReadonlySet<string>): AddressMatch<R> | null;
249
+ export interface ListedAddress {
250
+ route: AppRoute;
251
+ params: RouteParams;
252
+ address: string;
253
+ }
254
+ /** Every address the given routes list (one place's, from `appIn`), in
255
+ * their order: a route without parameters at its path, one with them at
256
+ * each parameter set its `addresses` gives. Throws when an address is not
257
+ * clean, is listed twice, or would be served by another route or a
258
+ * redirect. */
259
+ export declare function listAddresses(app: Pick<AppDefinition, "routes" | "redirects">): Promise<ListedAddress[]>;
260
+ /** The content type a declared plain file is served with, or null for an
261
+ * extension the published address cannot declare. */
262
+ export declare function siteFileContentType(path: string): string | null;
263
+ /** Everything wrong with an app's definition that can be told without
264
+ * running it, each as a sentence, for the places named (both unless
265
+ * said). Empty when there is nothing. */
266
+ export declare function appDefinitionProblems(app: AppDefinition, places?: readonly AppPlace[]): string[];
267
+ /** Whether `address` is one of the app's declared plain files rather than
268
+ * a route: `/llms.txt` for `llms.txt`, `/manifesto` for
269
+ * `manifesto/index.html`. The edge serves it as its own document, so
270
+ * moving there is a page load. */
271
+ export declare function isSiteFileAddress(app: Pick<AppDefinition, "files">, address: string): boolean;
272
+ /** Where a route's address is written in the published output. */
273
+ export declare function outputPathOf(address: string): string;
274
+ /** `path` made absolute on `origin`; an absolute URL is kept as it is. */
275
+ export declare function absoluteUrl(origin: string, path: string): string;
276
+ export declare function escapeHtml(text: string): string;
277
+ /** JSON safe inside a `<script>` data block: nothing in it can close the
278
+ * element or end a line in a script. */
279
+ export declare function scriptJson(value: unknown): string;
280
+ /** A route's title as the published address shows it. */
281
+ export declare function pageTitle(app: AppMeta, meta: RouteMeta): string;
282
+ /** The tags a published document's head carries for what its route says
283
+ * about itself: title, description, canonical, Open Graph, X, JSON-LD,
284
+ * icons, theme colour and font preloads. Every URL in them is absolute on
285
+ * `origin`. */
286
+ export declare function buildDocumentHead(input: {
287
+ app: AppMeta;
288
+ meta: RouteMeta;
289
+ address: string;
290
+ origin: string;
291
+ fonts?: readonly SiteFont[];
292
+ }): string;
293
+ export interface SitemapEntry extends SitemapOptions {
294
+ address: string;
295
+ }
296
+ export declare function buildSitemap(origin: string, entries: readonly SitemapEntry[]): string;
297
+ export declare function buildRobots(origin: string, robots?: AppMeta["robots"]): string;
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
+ }