@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 +180 -17
- package/app.d.ts +297 -0
- package/callError.d.ts +21 -0
- package/cli.js +703 -37
- package/files.d.ts +25 -0
- package/index.d.ts +96 -38
- package/index.js +959 -22
- package/navigation.d.ts +44 -2
- package/package.json +1 -1
- package/siteRuntime.d.ts +96 -0
package/navigation.d.ts
CHANGED
|
@@ -7,17 +7,59 @@ export declare function applicationPath(value: unknown): string | null;
|
|
|
7
7
|
* from. An app follows the host's own moves, never an earlier echo, and a
|
|
8
8
|
* latest echo only when it is somewhere else (a host move crossed its own). */
|
|
9
9
|
export type AppNavigationEcho = "latest" | "earlier" | null;
|
|
10
|
+
export interface AppNavigateOptions {
|
|
11
|
+
/** The fragment to arrive at, without `#`. */
|
|
12
|
+
hash?: string;
|
|
13
|
+
/** Takes the place of the current history entry instead of adding one. */
|
|
14
|
+
replace?: boolean;
|
|
15
|
+
}
|
|
16
|
+
/** Where an app is and how it moves, the same in Alma's frame (the host's
|
|
17
|
+
* history) and at a published address (the browser's own). */
|
|
10
18
|
export interface AppNavigation {
|
|
11
19
|
getPath(): string;
|
|
12
|
-
/** Each path the host
|
|
20
|
+
/** Each path announced (the host's, or the browser's back and forward),
|
|
21
|
+
* and what the announcement answers. */
|
|
13
22
|
subscribe(listener: (path: string, echo: AppNavigationEcho) => void): () => void;
|
|
14
|
-
navigate(path: string): void;
|
|
23
|
+
navigate(path: string, options?: AppNavigateOptions): void;
|
|
24
|
+
/** Opens an address outside the app (`outsideUrl`) in a new tab. In
|
|
25
|
+
* Alma's frame the host opens it, and only on a person's click. */
|
|
26
|
+
openUrl(url: string): void;
|
|
27
|
+
/** Hands the person one of the app's own files: an uploaded one by its
|
|
28
|
+
* name, or a declared plain file's text under a name to save it as. At
|
|
29
|
+
* the published address the file opens in a new tab; in Alma's frame the
|
|
30
|
+
* host saves it, and only on a person's click. */
|
|
31
|
+
openFile(file: AppFileToOpen): void;
|
|
15
32
|
openApps(): void;
|
|
16
33
|
/** Tasks, or one of the viewer's own Tasks by id. */
|
|
17
34
|
openTasks(taskId?: string): void;
|
|
18
35
|
/** A topic, in the organization's Knowledge tab. */
|
|
19
36
|
openTopic(topicId: string): void;
|
|
20
37
|
}
|
|
38
|
+
/** The message an app in Alma's frame posts to ask the host to open an
|
|
39
|
+
* address outside the app in a new tab: `{ type, url }`, with `url` one
|
|
40
|
+
* `outsideUrl` accepts. The host answers nothing. */
|
|
41
|
+
export declare const OPEN_URL_MESSAGE = "alma:open-url";
|
|
42
|
+
/** One of an app's files to hand the person: an uploaded file by its name
|
|
43
|
+
* (`isAppFileName`), or a declared plain file (`files` in the definition)
|
|
44
|
+
* by its address and its text. */
|
|
45
|
+
export type AppFileToOpen = {
|
|
46
|
+
name: string;
|
|
47
|
+
} | {
|
|
48
|
+
address: string;
|
|
49
|
+
name: string;
|
|
50
|
+
text: string;
|
|
51
|
+
};
|
|
52
|
+
/** The message an app in Alma's frame posts to ask the host to save one of
|
|
53
|
+
* its files for the person: `{ type, name }` for an uploaded file, or
|
|
54
|
+
* `{ type, name, text }` for a declared plain file's text, at most
|
|
55
|
+
* `OPEN_FILE_TEXT_LIMIT` characters. The host answers nothing. */
|
|
56
|
+
export declare const OPEN_FILE_MESSAGE = "alma:open-file";
|
|
57
|
+
/** The longest declared plain file the frame hands its host to save. */
|
|
58
|
+
export declare const OPEN_FILE_TEXT_LIMIT = 5000000;
|
|
59
|
+
/** `value` as an address outside the app a person may be sent to (http,
|
|
60
|
+
* https, mail or phone, at most 2048 characters, no credentials), or
|
|
61
|
+
* null. */
|
|
62
|
+
export declare function outsideUrl(value: unknown): string | null;
|
|
21
63
|
/** A filtered host notification that something an app may reread changed.
|
|
22
64
|
* It carries only the kind and the id to reread; the app rereads canonical
|
|
23
65
|
* data through its ordinary scoped reads, so a notification discloses
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@almateam/app-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.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/siteRuntime.d.ts
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import type { AppPlace } from "./app";
|
|
2
|
+
import { AppCallError } from "./callError";
|
|
3
|
+
import type { TopicRecord } from "./generated/apiTypes";
|
|
4
|
+
import type { AppTransport } from "./index";
|
|
5
|
+
import { type AppNavigation } from "./navigation";
|
|
6
|
+
/** What a published site's raise returns to read its workflow's answer by:
|
|
7
|
+
* `token` for `result`, and `url`, a page of the site that reads it from
|
|
8
|
+
* its fragment. */
|
|
9
|
+
export interface EventResultTicket {
|
|
10
|
+
token: string;
|
|
11
|
+
url: string;
|
|
12
|
+
}
|
|
13
|
+
/** A raised event's answer so far: still `pending` (also for a token the
|
|
14
|
+
* site does not know), or `ready` with what the workflow answered. Where
|
|
15
|
+
* the token names the visitor's own entry (an add, or a raise whose result
|
|
16
|
+
* type the public reads as `own`), the answer is that entry, `OwnEntry`. */
|
|
17
|
+
export type EventResult = {
|
|
18
|
+
status: "pending";
|
|
19
|
+
} | {
|
|
20
|
+
status: "ready";
|
|
21
|
+
result: unknown;
|
|
22
|
+
};
|
|
23
|
+
/** The visitor's own entry, as a private link names it: its type's key and
|
|
24
|
+
* the entry in the shape `listTopics` gives (see `PUBLIC_RECORD_SHAPE`). */
|
|
25
|
+
export interface OwnEntry {
|
|
26
|
+
type: string;
|
|
27
|
+
record: TopicRecord;
|
|
28
|
+
}
|
|
29
|
+
export declare function isOwnEntry(value: unknown): value is OwnEntry;
|
|
30
|
+
/**
|
|
31
|
+
* The record shape one app's code reads in both places. A member's
|
|
32
|
+
* `listTopics` and a visitor's read through the door agree on `id`, `name`,
|
|
33
|
+
* `type.key`, `values` (each value's `text` and `typed`) and `created_at`;
|
|
34
|
+
* an app that reads only those runs unchanged at its published address.
|
|
35
|
+
* What only a member's read carries has a fixed answer there: `name` is ""
|
|
36
|
+
* where the version does not show it, `type.name` is the type's key, no
|
|
37
|
+
* `slug` or `icon`, `status` "active", each value's `ref` null (a visitor
|
|
38
|
+
* follows no reference), no `revisions` (a visitor writes no field), no
|
|
39
|
+
* unverified values, `can_edit` false, and `updated_at` the entry's
|
|
40
|
+
* `created_at`. `getTopicRecord` answers the same entry as a member's record
|
|
41
|
+
* read: `topic`, and `facts` from its values, each fact's `id` naming its
|
|
42
|
+
* place in the entry (`<entry>:<field>:<n>`), not a fact a call can name.
|
|
43
|
+
*/
|
|
44
|
+
export declare const PUBLIC_RECORD_SHAPE: readonly ["id", "name", "type.key", "values", "created_at"];
|
|
45
|
+
export interface WaitForResultOptions {
|
|
46
|
+
/** How long to keep reading before rejecting with `result.timeout`. */
|
|
47
|
+
timeoutMs?: number;
|
|
48
|
+
signal?: AbortSignal;
|
|
49
|
+
}
|
|
50
|
+
/** A visitor's raise the site refused for now: `visitor.rate_limited` (this
|
|
51
|
+
* visitor raised too many in the hour) or `site.paused` (the whole site
|
|
52
|
+
* is past its events for now). `retryAfterSeconds` says when to try
|
|
53
|
+
* again, when the site said. */
|
|
54
|
+
export declare class SiteRefusalError extends AppCallError {
|
|
55
|
+
readonly retryAfterSeconds: number | null;
|
|
56
|
+
constructor(message: string, code: "visitor.rate_limited" | "site.paused", retryAfterSeconds: number | null);
|
|
57
|
+
}
|
|
58
|
+
export declare function isSiteRefusal(error: unknown): error is SiteRefusalError;
|
|
59
|
+
/** The attribute every page of a published site carries on `<html>`. */
|
|
60
|
+
export declare const PUBLISHED_SITE_ATTRIBUTE = "data-alma-site";
|
|
61
|
+
/** This document as a published site, or null inside Alma's frame (or
|
|
62
|
+
* anywhere else). */
|
|
63
|
+
export declare function publishedSite(): {
|
|
64
|
+
origin: string;
|
|
65
|
+
} | null;
|
|
66
|
+
/** Where this document's app runs: at its published address, or in
|
|
67
|
+
* Alma's frame. */
|
|
68
|
+
export declare function appPlace(): AppPlace;
|
|
69
|
+
/** The result token a result page was opened with, from its fragment
|
|
70
|
+
* (`#<token>` or `#token=<token>`), or null. A fragment never reaches a
|
|
71
|
+
* server, so the token stays between the visitor and the page. */
|
|
72
|
+
export declare function readResultToken(hash?: string): string | null;
|
|
73
|
+
/** `AppNavigation` on the browser's history. A move this site makes adds an
|
|
74
|
+
* entry and is reported as `latest`; back and forward are the visitor's
|
|
75
|
+
* own and report null. */
|
|
76
|
+
export declare function siteNavigation(): AppNavigation;
|
|
77
|
+
export interface SiteTransportOptions {
|
|
78
|
+
/** Where the site's `/_alma/` door is; the page's own origin unless
|
|
79
|
+
* said. */
|
|
80
|
+
base?: string;
|
|
81
|
+
fetch?: typeof fetch;
|
|
82
|
+
/** The waits before each retry of a raise that got no answer or a
|
|
83
|
+
* gateway error, which reuses the raise's idempotency key. */
|
|
84
|
+
retryDelaysMs?: readonly number[];
|
|
85
|
+
}
|
|
86
|
+
/** The transport a published site's SDK talks through, to the site's own
|
|
87
|
+
* door: `raiseAppEvent` is `POST /_alma/events`; `createTopic` is `POST
|
|
88
|
+
* /_alma/records`, its type named by key; `listTopics` is `GET
|
|
89
|
+
* /_alma/records?type=`; `getTopicRecord` is `GET /_alma/records/:id?type=`;
|
|
90
|
+
* a result or the visitor's own entry is `GET /_alma/results/:token`. What
|
|
91
|
+
* the door shows is handed on in the shape a member's call answers with
|
|
92
|
+
* (`PUBLIC_RECORD_SHAPE`). There is no viewer or shell, and every other
|
|
93
|
+
* operation rejects with `site.no_viewer`, as does a read the door cannot
|
|
94
|
+
* serve as asked, before anything is sent. What the version's `public`
|
|
95
|
+
* does not offer the door refuses with the same code. */
|
|
96
|
+
export declare function siteTransport(options?: SiteTransportOptions): AppTransport;
|