@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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@almateam/app-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "Types, host bridge and the alma-app dev command for apps that run in Alma. Alma builds every app with its own current copy of the SDK; install this for the types and the command.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://docs.alma.team/developers/apps",
|
package/site.d.ts
ADDED
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
/** The literal every absolute URL is written with at build time. A build
|
|
2
|
+
* does not know where its site will be served; publishing replaces this in
|
|
3
|
+
* every text file with the site's own origin. */
|
|
4
|
+
export declare const SITE_ORIGIN_TOKEN = "__ALMA_SITE_ORIGIN__";
|
|
5
|
+
/** The id `assetsFor` and a page's hydration data name the not-found page
|
|
6
|
+
* by. Every other page is named by its `path`, which starts with `/`. */
|
|
7
|
+
export declare const NOT_FOUND_PAGE_ID = "404";
|
|
8
|
+
/** A page's parameters, by the names its `path` gives them (`:slug`). */
|
|
9
|
+
export type SiteParams = Record<string, string>;
|
|
10
|
+
export type JsonValue = string | number | boolean | null | JsonValue[] | {
|
|
11
|
+
[key: string]: JsonValue;
|
|
12
|
+
};
|
|
13
|
+
export type JsonLd = {
|
|
14
|
+
[key: string]: JsonValue;
|
|
15
|
+
};
|
|
16
|
+
/** A title and description shown where a page is shared, when they are not
|
|
17
|
+
* the page's own. */
|
|
18
|
+
export interface SharedText {
|
|
19
|
+
title?: string;
|
|
20
|
+
description?: string;
|
|
21
|
+
}
|
|
22
|
+
/** What one page says about itself in its document head. */
|
|
23
|
+
export interface PageMeta {
|
|
24
|
+
title: string;
|
|
25
|
+
/** The title shown as it is, without the site's `titleTemplate`. */
|
|
26
|
+
absoluteTitle?: boolean;
|
|
27
|
+
description?: string;
|
|
28
|
+
/** The page's own address on this site (a path), when it is not the
|
|
29
|
+
* address it was served at. */
|
|
30
|
+
canonical?: string;
|
|
31
|
+
/** A path on this site (`/_files/cover.png`) or an absolute https URL. */
|
|
32
|
+
image?: string;
|
|
33
|
+
imageAlt?: string;
|
|
34
|
+
/** Open Graph `og:type`; `website` unless said. */
|
|
35
|
+
type?: "website" | "article";
|
|
36
|
+
/** What Open Graph shows, where it is not the page's title, description
|
|
37
|
+
* and image (or the site's `openGraph`). */
|
|
38
|
+
openGraph?: SharedText & {
|
|
39
|
+
image?: string;
|
|
40
|
+
};
|
|
41
|
+
/** What X shows, where it is not the page's title and description (or
|
|
42
|
+
* the site's `x`). */
|
|
43
|
+
x?: SharedText;
|
|
44
|
+
/** Kept out of search engines and the sitemap. */
|
|
45
|
+
noindex?: boolean;
|
|
46
|
+
jsonLd?: JsonLd | JsonLd[];
|
|
47
|
+
}
|
|
48
|
+
/** What the whole site says about itself, beneath every page's own meta. */
|
|
49
|
+
export interface SiteMeta {
|
|
50
|
+
name: string;
|
|
51
|
+
description?: string;
|
|
52
|
+
/** The document's `lang`; `en` unless said. */
|
|
53
|
+
lang?: string;
|
|
54
|
+
/** Open Graph `og:locale`, such as `en_US`. */
|
|
55
|
+
locale?: string;
|
|
56
|
+
/** How a page's title is shown, with `%s` where it goes. Without one a
|
|
57
|
+
* page's title is used as it is. */
|
|
58
|
+
titleTemplate?: string;
|
|
59
|
+
/** The image a page without its own shares with, and its size in
|
|
60
|
+
* pixels. */
|
|
61
|
+
image?: string;
|
|
62
|
+
imageAlt?: string;
|
|
63
|
+
imageWidth?: number;
|
|
64
|
+
imageHeight?: number;
|
|
65
|
+
/** What Open Graph and X show for a page that gives none of its own:
|
|
66
|
+
* without these, the page's title and description. */
|
|
67
|
+
openGraph?: SharedText;
|
|
68
|
+
x?: SharedText;
|
|
69
|
+
/** The site's account on X, such as `@alma`. */
|
|
70
|
+
twitter?: string;
|
|
71
|
+
/** One icon, or one for each colour scheme. */
|
|
72
|
+
favicon?: string | {
|
|
73
|
+
light: string;
|
|
74
|
+
dark: string;
|
|
75
|
+
};
|
|
76
|
+
themeColor?: string | {
|
|
77
|
+
light: string;
|
|
78
|
+
dark: string;
|
|
79
|
+
};
|
|
80
|
+
/** Addresses search engines are asked not to crawl. */
|
|
81
|
+
robots?: {
|
|
82
|
+
disallow?: string[];
|
|
83
|
+
};
|
|
84
|
+
jsonLd?: JsonLd | JsonLd[];
|
|
85
|
+
}
|
|
86
|
+
/** What a page component is rendered with. */
|
|
87
|
+
export interface PageProps<D = unknown> {
|
|
88
|
+
params: SiteParams;
|
|
89
|
+
data: D;
|
|
90
|
+
path: string;
|
|
91
|
+
}
|
|
92
|
+
export type PageComponent<D = unknown> = {
|
|
93
|
+
bivarianceHack(props: PageProps<D>): unknown;
|
|
94
|
+
}["bivarianceHack"];
|
|
95
|
+
export type SiteLayout = {
|
|
96
|
+
bivarianceHack(props: {
|
|
97
|
+
children: unknown;
|
|
98
|
+
path: string;
|
|
99
|
+
}): unknown;
|
|
100
|
+
}["bivarianceHack"];
|
|
101
|
+
export interface PageMetaContext<D = unknown> {
|
|
102
|
+
params: SiteParams;
|
|
103
|
+
data: D;
|
|
104
|
+
/** The address being described. */
|
|
105
|
+
path: string;
|
|
106
|
+
site: SiteMeta;
|
|
107
|
+
}
|
|
108
|
+
export interface SitemapOptions {
|
|
109
|
+
changeFrequency?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
|
|
110
|
+
/** From 0 to 1. */
|
|
111
|
+
priority?: number;
|
|
112
|
+
/** An ISO 8601 date. */
|
|
113
|
+
lastModified?: string;
|
|
114
|
+
}
|
|
115
|
+
export interface SitePage<D = unknown> {
|
|
116
|
+
/** `/`, `/about`, or a pattern with parameters such as `/blog/:slug`. */
|
|
117
|
+
path: string;
|
|
118
|
+
/** The page's own module, split from every other page's. */
|
|
119
|
+
component(): Promise<{
|
|
120
|
+
default: PageComponent<D>;
|
|
121
|
+
}>;
|
|
122
|
+
/** Every parameter set a pattern is built for. A page with parameters
|
|
123
|
+
* must list them: an address no page lists is not built. */
|
|
124
|
+
addresses?(): SiteParams[] | Promise<SiteParams[]>;
|
|
125
|
+
/** The page's data, read when the page is built and again when a visitor
|
|
126
|
+
* moves to it in the browser. It must be plain JSON. */
|
|
127
|
+
load?(params: SiteParams): D | Promise<D>;
|
|
128
|
+
meta(context: PageMetaContext<D>): PageMeta;
|
|
129
|
+
/** Left out of the sitemap with `false`; listed by default. */
|
|
130
|
+
sitemap?: boolean | SitemapOptions;
|
|
131
|
+
}
|
|
132
|
+
/** The statuses a redirect may answer with: 301 and 308 for a permanent
|
|
133
|
+
* move, 302 and 307 for a temporary one. */
|
|
134
|
+
export declare const SITE_REDIRECT_STATUSES: readonly [301, 302, 307, 308];
|
|
135
|
+
/** A move. `from` is one address, or a prefix ending `/*` that moves the
|
|
136
|
+
* prefix itself and every address under it. `to` is one address on this
|
|
137
|
+
* site or an absolute https URL, used as it is. */
|
|
138
|
+
export interface SiteRedirect {
|
|
139
|
+
from: string;
|
|
140
|
+
to: string;
|
|
141
|
+
status: (typeof SITE_REDIRECT_STATUSES)[number];
|
|
142
|
+
}
|
|
143
|
+
export interface SiteFont {
|
|
144
|
+
/** A path on this site, such as `/_files/inter.woff2`. */
|
|
145
|
+
href: string;
|
|
146
|
+
/** `font/woff2` unless said. */
|
|
147
|
+
type?: string;
|
|
148
|
+
}
|
|
149
|
+
/** A plain file the site serves, by its path (`llms.txt`). */
|
|
150
|
+
export type SiteFile = string | ((context: {
|
|
151
|
+
origin: string;
|
|
152
|
+
site: SiteMeta;
|
|
153
|
+
}) => string | Promise<string>);
|
|
154
|
+
export interface SiteDefinition {
|
|
155
|
+
pages: SitePage[];
|
|
156
|
+
/** Wraps every page, the not-found page included. */
|
|
157
|
+
layout?: SiteLayout;
|
|
158
|
+
/** The page served for an address no page has. */
|
|
159
|
+
notFound?: {
|
|
160
|
+
component(): Promise<{
|
|
161
|
+
default: PageComponent<null>;
|
|
162
|
+
}>;
|
|
163
|
+
meta?: PageMeta;
|
|
164
|
+
};
|
|
165
|
+
redirects?: SiteRedirect[];
|
|
166
|
+
meta: SiteMeta;
|
|
167
|
+
/** Run first in every page's head, before anything paints, to set the
|
|
168
|
+
* colour scheme. A site without one gets `DEFAULT_THEME_SCRIPT`. */
|
|
169
|
+
themeScript?: string;
|
|
170
|
+
/** Fonts every page preloads. */
|
|
171
|
+
fonts?: SiteFont[];
|
|
172
|
+
files?: Record<string, SiteFile>;
|
|
173
|
+
/** Origins the site's pages may frame, such as
|
|
174
|
+
* `https://calendar.google.com`. */
|
|
175
|
+
embeds?: string[];
|
|
176
|
+
}
|
|
177
|
+
/** Sets `<html data-theme>` from the visitor's saved choice
|
|
178
|
+
* (`localStorage["alma-site-theme"]`) or their system's scheme. */
|
|
179
|
+
export declare const DEFAULT_THEME_SCRIPT: string;
|
|
180
|
+
export declare function defineSite(site: SiteDefinition): SiteDefinition;
|
|
181
|
+
/** A page whose `load`, component and `meta` share one data type. */
|
|
182
|
+
export declare function definePage<D>(page: SitePage<D>): SitePage;
|
|
183
|
+
/** Thrown from a page's `load`: this address has no page. */
|
|
184
|
+
export declare function notFound(): Error;
|
|
185
|
+
export declare function isNotFound(error: unknown): boolean;
|
|
186
|
+
/** Why `address` is not a clean address (`/` or `/a/b`: no trailing slash,
|
|
187
|
+
* no empty, dot or `index.html` segment, no query or fragment), or null. */
|
|
188
|
+
export declare function siteAddressProblem(address: string): string | null;
|
|
189
|
+
/** The parameters `address` gives `pattern`, or null where it does not fit. */
|
|
190
|
+
export declare function matchPattern(pattern: string, address: string): SiteParams | null;
|
|
191
|
+
/** The address a pattern makes with `params`, each value encoded. */
|
|
192
|
+
export declare function fillPattern(pattern: string, params: SiteParams): string;
|
|
193
|
+
/** The redirect that moves `address`, as the edge applies them: one whose
|
|
194
|
+
* `from` is the address itself first, then the longest `/*` prefix that
|
|
195
|
+
* is the address or one of its parents. */
|
|
196
|
+
export declare function matchRedirect(redirects: readonly SiteRedirect[], address: string): SiteRedirect | null;
|
|
197
|
+
export type AddressMatch<P extends {
|
|
198
|
+
path: string;
|
|
199
|
+
} = SitePage> = {
|
|
200
|
+
kind: "page";
|
|
201
|
+
page: P;
|
|
202
|
+
params: SiteParams;
|
|
203
|
+
} | {
|
|
204
|
+
kind: "redirect";
|
|
205
|
+
redirect: SiteRedirect;
|
|
206
|
+
};
|
|
207
|
+
/** What a site serves at `address`: a page and its parameters, a redirect,
|
|
208
|
+
* or null for its not-found page. A page whose path is the address, and a
|
|
209
|
+
* redirect from exactly the address, are one key at the edge and so come
|
|
210
|
+
* first (a site may not have both); then a page whose pattern fits, a
|
|
211
|
+
* static segment winning over a parameter; then a `/*` redirect.
|
|
212
|
+
*
|
|
213
|
+
* The edge holds only the addresses the build listed. Given them as
|
|
214
|
+
* `listed`, a page with parameters fits only an address it listed, and any
|
|
215
|
+
* other falls through to the redirects, so the answer is the edge's own.
|
|
216
|
+
* Without them, every address that fits a pattern is that page's. */
|
|
217
|
+
export declare function matchAddress<P extends {
|
|
218
|
+
path: string;
|
|
219
|
+
}>(site: {
|
|
220
|
+
pages: readonly P[];
|
|
221
|
+
redirects?: readonly SiteRedirect[];
|
|
222
|
+
}, address: string, listed?: ReadonlySet<string>): AddressMatch<P> | null;
|
|
223
|
+
export interface ListedAddress {
|
|
224
|
+
page: SitePage;
|
|
225
|
+
params: SiteParams;
|
|
226
|
+
address: string;
|
|
227
|
+
}
|
|
228
|
+
/** Every address the site's pages list, in the order of its pages: a page
|
|
229
|
+
* without parameters at its path, one with them at each parameter set its
|
|
230
|
+
* `addresses` gives. Throws when an address is not clean, is listed twice,
|
|
231
|
+
* or would be served by another page or a redirect. */
|
|
232
|
+
export declare function listAddresses(site: SiteDefinition): Promise<ListedAddress[]>;
|
|
233
|
+
/** The content type a declared plain file is served with, or null for an
|
|
234
|
+
* extension a site cannot declare. */
|
|
235
|
+
export declare function siteFileContentType(path: string): string | null;
|
|
236
|
+
/** Everything wrong with a site's definition that can be told without
|
|
237
|
+
* running it, each as a sentence. Empty when there is nothing. */
|
|
238
|
+
export declare function siteDefinitionProblems(site: SiteDefinition): string[];
|
|
239
|
+
/** Whether `address` is one of the site's declared plain files rather than a
|
|
240
|
+
* page: `/llms.txt` for `llms.txt`, `/manifesto` for `manifesto/index.html`.
|
|
241
|
+
* The edge serves it as its own document, so moving there is a page load. */
|
|
242
|
+
export declare function isSiteFileAddress(site: Pick<SiteDefinition, "files">, address: string): boolean;
|
|
243
|
+
/** Where a page address is written in the site's output. */
|
|
244
|
+
export declare function outputPathOf(address: string): string;
|
|
245
|
+
/** `path` made absolute on `origin`; an absolute URL is kept as it is. */
|
|
246
|
+
export declare function absoluteUrl(origin: string, path: string): string;
|
|
247
|
+
export declare function escapeHtml(text: string): string;
|
|
248
|
+
/** JSON safe inside a `<script>` data block: nothing in it can close the
|
|
249
|
+
* element or end a line in a script. */
|
|
250
|
+
export declare function scriptJson(value: unknown): string;
|
|
251
|
+
/** A page's title as the site shows it. */
|
|
252
|
+
export declare function pageTitle(site: SiteMeta, meta: PageMeta): string;
|
|
253
|
+
/** The tags a page's head carries for what it says about itself: title,
|
|
254
|
+
* description, canonical, Open Graph, X, JSON-LD, icons, theme colour and
|
|
255
|
+
* font preloads. Every URL in them is absolute on `origin`. */
|
|
256
|
+
export declare function buildDocumentHead(input: {
|
|
257
|
+
site: SiteMeta;
|
|
258
|
+
meta: PageMeta;
|
|
259
|
+
address: string;
|
|
260
|
+
origin: string;
|
|
261
|
+
fonts?: readonly SiteFont[];
|
|
262
|
+
}): string;
|
|
263
|
+
export interface SitemapEntry extends SitemapOptions {
|
|
264
|
+
address: string;
|
|
265
|
+
}
|
|
266
|
+
export declare function buildSitemap(origin: string, entries: readonly SitemapEntry[]): string;
|
|
267
|
+
export declare function buildRobots(origin: string, robots?: SiteMeta["robots"]): string;
|
package/siteRuntime.d.ts
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { AppCallError } from "./callError";
|
|
2
|
+
import type { AppTransport } from "./index";
|
|
3
|
+
import { type AppNavigation } from "./navigation";
|
|
4
|
+
/** What a published site's raise returns to read its workflow's answer by:
|
|
5
|
+
* `token` for `result`, and `url`, a page of the site that reads it from
|
|
6
|
+
* its fragment. */
|
|
7
|
+
export interface EventResultTicket {
|
|
8
|
+
token: string;
|
|
9
|
+
url: string;
|
|
10
|
+
}
|
|
11
|
+
/** A raised event's answer so far: still `pending` (also for a token the
|
|
12
|
+
* site does not know), or `ready` with what the workflow answered. */
|
|
13
|
+
export type EventResult = {
|
|
14
|
+
status: "pending";
|
|
15
|
+
} | {
|
|
16
|
+
status: "ready";
|
|
17
|
+
result: unknown;
|
|
18
|
+
};
|
|
19
|
+
export interface WaitForResultOptions {
|
|
20
|
+
/** How long to keep reading before rejecting with `result.timeout`. */
|
|
21
|
+
timeoutMs?: number;
|
|
22
|
+
signal?: AbortSignal;
|
|
23
|
+
}
|
|
24
|
+
/** A visitor's raise the site refused for now: `visitor.rate_limited` (this
|
|
25
|
+
* visitor raised too many in the hour) or `site.paused` (the whole site
|
|
26
|
+
* is past its events for now). `retryAfterSeconds` says when to try
|
|
27
|
+
* again, when the site said. */
|
|
28
|
+
export declare class SiteRefusalError extends AppCallError {
|
|
29
|
+
readonly retryAfterSeconds: number | null;
|
|
30
|
+
constructor(message: string, code: "visitor.rate_limited" | "site.paused", retryAfterSeconds: number | null);
|
|
31
|
+
}
|
|
32
|
+
export declare function isSiteRefusal(error: unknown): error is SiteRefusalError;
|
|
33
|
+
/** The attribute every page of a published site carries on `<html>`. */
|
|
34
|
+
export declare const PUBLISHED_SITE_ATTRIBUTE = "data-alma-site";
|
|
35
|
+
/** This document as a published site, or null inside Alma's frame (or
|
|
36
|
+
* anywhere else). */
|
|
37
|
+
export declare function publishedSite(): {
|
|
38
|
+
origin: string;
|
|
39
|
+
} | null;
|
|
40
|
+
/** The result token a result page was opened with, from its fragment
|
|
41
|
+
* (`#<token>` or `#token=<token>`), or null. A fragment never reaches a
|
|
42
|
+
* server, so the token stays between the visitor and the page. */
|
|
43
|
+
export declare function readResultToken(hash?: string): string | null;
|
|
44
|
+
export interface SiteNavigation extends AppNavigation {
|
|
45
|
+
/** Moves to `path`, with `hash` as its fragment; `replace` takes the
|
|
46
|
+
* place of the current history entry instead of adding one. */
|
|
47
|
+
navigate(path: string, options?: {
|
|
48
|
+
hash?: string;
|
|
49
|
+
replace?: boolean;
|
|
50
|
+
}): void;
|
|
51
|
+
}
|
|
52
|
+
/** `AppNavigation` on the browser's history. A move this site makes adds an
|
|
53
|
+
* entry and is reported as `latest`; back and forward are the visitor's
|
|
54
|
+
* own and report null. */
|
|
55
|
+
export declare function siteNavigation(): SiteNavigation;
|
|
56
|
+
export interface SiteTransportOptions {
|
|
57
|
+
/** Where the site's `/_alma/` door is; the page's own origin unless
|
|
58
|
+
* said. */
|
|
59
|
+
base?: string;
|
|
60
|
+
fetch?: typeof fetch;
|
|
61
|
+
/** The waits before each retry of a raise that got no answer or a
|
|
62
|
+
* gateway error, which reuses the raise's idempotency key. */
|
|
63
|
+
retryDelaysMs?: readonly number[];
|
|
64
|
+
}
|
|
65
|
+
/** The transport a published site's SDK talks through. Raising an event is
|
|
66
|
+
* `POST /_alma/events`, and its workflow's answer `GET
|
|
67
|
+
* /_alma/results/:token`; there is no viewer or shell, and every other
|
|
68
|
+
* operation rejects with `site.no_viewer`. */
|
|
69
|
+
export declare function siteTransport(options?: SiteTransportOptions): AppTransport;
|