@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/files.d.ts
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/** The bridge question an app in Alma's frame asks for one of its own
|
|
2
|
+
* files, as an `alma:operation` (`{ type, id, operation, params, query,
|
|
3
|
+
* body: { name } }`). The host answers `alma:result` with the same `id`
|
|
4
|
+
* and `data: { name, media_type, bytes }`, `bytes` an `ArrayBuffer` of
|
|
5
|
+
* the whole file; or with `error` and a `code` (`AppFileRefusalCode`).
|
|
6
|
+
* Only a file of the app version the frame is running is ever answered. */
|
|
7
|
+
export declare const APP_FILE_QUESTION = "getAppFile";
|
|
8
|
+
/** What a host refuses an app file with: `file.not_found` (the version has
|
|
9
|
+
* no file by that name), `file.invalid_name` (not a file name), or
|
|
10
|
+
* `file.unavailable` (the host could not read it now; asking again may
|
|
11
|
+
* succeed). */
|
|
12
|
+
export type AppFileRefusalCode = "file.not_found" | "file.invalid_name" | "file.unavailable";
|
|
13
|
+
/** The host's answer to `APP_FILE_QUESTION`. */
|
|
14
|
+
export interface AppFileAnswer {
|
|
15
|
+
name: string;
|
|
16
|
+
media_type: string;
|
|
17
|
+
bytes: ArrayBuffer;
|
|
18
|
+
}
|
|
19
|
+
/** Whether `name` is one an uploaded file may have: letters, digits, dots,
|
|
20
|
+
* dashes and underscores, at most 128, starting with a letter or digit,
|
|
21
|
+
* with no `..`. The same rule the upload and the build hold names to. */
|
|
22
|
+
export declare function isAppFileName(name: unknown): name is string;
|
|
23
|
+
/** The file name an address on the published address names
|
|
24
|
+
* (`/_files/cover.png` is `cover.png`), or null. */
|
|
25
|
+
export declare function appFileNameOf(address: string): string | null;
|
package/index.d.ts
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
|
+
import { AppCallError, type FieldState } from "./callError";
|
|
1
2
|
import type * as Api from "./generated/apiTypes";
|
|
3
|
+
import type { AppPlace } from "./app";
|
|
4
|
+
import { type EventResult, type EventResultTicket, type OwnEntry, type WaitForResultOptions } from "./siteRuntime";
|
|
5
|
+
export { AppCallError, type FieldState } from "./callError";
|
|
6
|
+
export * from "./app";
|
|
7
|
+
export * from "./files";
|
|
2
8
|
export * from "./navigation";
|
|
9
|
+
export * from "./siteRuntime";
|
|
3
10
|
export type * from "./generated/apiTypes";
|
|
4
11
|
/** Which records `listTopics` reads. `schema` is the `schema.id` of a `type`
|
|
5
12
|
* another app keeps. A field filter is `<field>:<op>:<value>` (op: eq, ne,
|
|
@@ -104,26 +111,6 @@ export interface AppRequest {
|
|
|
104
111
|
* arrived) answers with what the first attempt did and changes nothing. */
|
|
105
112
|
idempotencyKey?: string;
|
|
106
113
|
}
|
|
107
|
-
/** A field as it stands: its revision and the values it holds. */
|
|
108
|
-
export interface FieldState {
|
|
109
|
-
revision: string;
|
|
110
|
-
values: {
|
|
111
|
-
text: string;
|
|
112
|
-
typed: Api.TypedValue | null;
|
|
113
|
-
}[];
|
|
114
|
-
}
|
|
115
|
-
/** A refused call. `message` is the refusal's words, to show as they are.
|
|
116
|
-
* A refusal a program can act on also carries its `code`; `field.changed`
|
|
117
|
-
* carries the field as it stands in `current`, and
|
|
118
|
-
* `app_shared_state.revision_conflict` the shared key. */
|
|
119
|
-
export declare class AppCallError extends Error {
|
|
120
|
-
readonly code: string | undefined;
|
|
121
|
-
readonly current: FieldState | Api.AppSharedStateEntry | undefined;
|
|
122
|
-
constructor(message: string, detail?: {
|
|
123
|
-
code?: string;
|
|
124
|
-
current?: FieldState | Api.AppSharedStateEntry;
|
|
125
|
-
});
|
|
126
|
-
}
|
|
127
114
|
/** A field write refused because the field changed after the app read it.
|
|
128
115
|
* Nothing was written; `current` is what the field holds now. */
|
|
129
116
|
export type FieldChangedError = AppCallError & {
|
|
@@ -273,18 +260,23 @@ export type SharedStateTold = {
|
|
|
273
260
|
missed: true;
|
|
274
261
|
};
|
|
275
262
|
/** What a host answers a shared-state watch with: whether it will tell
|
|
276
|
-
* changes,
|
|
263
|
+
* changes, whether it is still joining (it tells `missed` once it is in,
|
|
264
|
+
* and changes from then on), and how to stop hearing them. */
|
|
277
265
|
export interface SharedStateWatch {
|
|
278
266
|
watching: boolean;
|
|
267
|
+
joining?: boolean;
|
|
279
268
|
stop(): void;
|
|
280
269
|
}
|
|
281
270
|
/** A quick message as a host tells it: its event, its payload, and whether
|
|
282
|
-
* this open copy of the app sent it
|
|
283
|
-
|
|
271
|
+
* this open copy of the app sent it; or that messages may have passed
|
|
272
|
+
* unheard. */
|
|
273
|
+
export type BroadcastTold = {
|
|
284
274
|
event: string;
|
|
285
275
|
payload: unknown;
|
|
286
276
|
self: boolean;
|
|
287
|
-
}
|
|
277
|
+
} | {
|
|
278
|
+
missed: true;
|
|
279
|
+
};
|
|
288
280
|
/** What a host answers a broadcast watch with: whether it will tell
|
|
289
281
|
* messages, and how to stop hearing them. */
|
|
290
282
|
export interface BroadcastWatch {
|
|
@@ -292,6 +284,10 @@ export interface BroadcastWatch {
|
|
|
292
284
|
stop(): void;
|
|
293
285
|
}
|
|
294
286
|
export interface AppTransport {
|
|
287
|
+
/** Where the transport runs: `public` at the app's published address,
|
|
288
|
+
* where a type is named by its key. A transport without it is Alma's
|
|
289
|
+
* frame. */
|
|
290
|
+
place?: AppPlace;
|
|
295
291
|
/** Resolves with the response's `data`, or `{ data, meta }` when the
|
|
296
292
|
* response pages. A change is the viewer's own act: it resolves with the
|
|
297
293
|
* result where they may make it, and rejects with the refusal's words
|
|
@@ -320,6 +316,15 @@ export interface AppTransport {
|
|
|
320
316
|
/** Be told each quick message sent to everyone with the app open. A
|
|
321
317
|
* transport without it tells nothing. */
|
|
322
318
|
watchBroadcasts?(told: (message: BroadcastTold) => void): Promise<BroadcastWatch>;
|
|
319
|
+
/** What a raised event's workflow has answered so far, by the `token` a
|
|
320
|
+
* published site's raise returned. A transport without it has no
|
|
321
|
+
* results to read. */
|
|
322
|
+
result?(token: string): Promise<EventResult>;
|
|
323
|
+
/** An address the app's own uploaded file `name` shows from: at once
|
|
324
|
+
* where the address is known (`/_files/<name>` at a published
|
|
325
|
+
* address), or once the host has handed over its bytes (a blob: URL in
|
|
326
|
+
* Alma's frame). A transport without it has no files. */
|
|
327
|
+
fileUrl?(name: string): string | Promise<string>;
|
|
323
328
|
}
|
|
324
329
|
export declare function createAppSdk(transport: AppTransport): {
|
|
325
330
|
call: <T>(operationId: AppOperationId, request?: AppRequest) => Promise<T>;
|
|
@@ -392,7 +397,13 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
392
397
|
groups?: Api.TypeViewGroup[];
|
|
393
398
|
};
|
|
394
399
|
}>;
|
|
395
|
-
|
|
400
|
+
/** A record as the viewer reads it. At a published address it is an
|
|
401
|
+
* entry of a type the version lets visitors read in full, named with
|
|
402
|
+
* `type` (its key), in the same shape (see `PUBLIC_RECORD_SHAPE`); in
|
|
403
|
+
* Alma's frame `type` is not needed. */
|
|
404
|
+
getTopicRecord: (topicId: string, options?: {
|
|
405
|
+
type?: string;
|
|
406
|
+
}) => Promise<Api.AppTopicRecord>;
|
|
396
407
|
getTopicFactDiscussion: (topicId: string, factId: string) => Promise<Api.AppFactDiscussion>;
|
|
397
408
|
/** A field's earlier values, newest first, as the viewer may read
|
|
398
409
|
* them. A record section's `earlier_values` says how many there are. */
|
|
@@ -500,8 +511,15 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
500
511
|
* see it follows the app's audience in Alma, never the app. The record and
|
|
501
512
|
* its values are saved together: if one value is refused nothing is
|
|
502
513
|
* created, and it rejects with the refusal's words, which start with the
|
|
503
|
-
* field's key. Each call is one request: calling again creates again.
|
|
504
|
-
|
|
514
|
+
* field's key. Each call is one request: calling again creates again.
|
|
515
|
+
* The type is its id, or its key as the manifest names it; at a
|
|
516
|
+
* published address it is a type the version lets visitors add to, by
|
|
517
|
+
* key, `name` is its `name` field (empty lets Alma name it after the
|
|
518
|
+
* type), and the answer carries `result`, the visitor's private link to
|
|
519
|
+
* the entry, when the version lets them read their own. */
|
|
520
|
+
createTopic: (name: string, topicTypeId?: string, options?: CreateTopicOptions) => Promise<OperationResult<"createTopic"> & {
|
|
521
|
+
result?: EventResultTicket;
|
|
522
|
+
}>;
|
|
505
523
|
/** Deletes a record of one of this app's own types as the viewer. Alma
|
|
506
524
|
* keeps it for 30 days, when the person who deleted it can bring it back
|
|
507
525
|
* with `restoreTopic`, or from the app's Data if they edit the app. A
|
|
@@ -568,8 +586,43 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
568
586
|
* with `payload` as data it does not trust. The answer is the same
|
|
569
587
|
* whether or not a workflow listens. An event the shared version does
|
|
570
588
|
* not declare rejects with `event.undeclared`; past the app's events for
|
|
571
|
-
* the hour, with `event.rate_limited` and when to try again.
|
|
572
|
-
|
|
589
|
+
* the hour, with `event.rate_limited` and when to try again. On a
|
|
590
|
+
* published site the answer also carries `result` when the event's
|
|
591
|
+
* workflow answers the visitor, and a refusal for now is a
|
|
592
|
+
* `SiteRefusalError` (`visitor.rate_limited`, `site.paused`). */
|
|
593
|
+
raiseEvent: (event: string, payload?: Record<string, unknown>, options?: ChangeOptions) => Promise<Api.AppEventRaised & {
|
|
594
|
+
result?: EventResultTicket;
|
|
595
|
+
}>;
|
|
596
|
+
/** On a published site, what the workflow a raise started has answered
|
|
597
|
+
* so far, by the `result.token` the raise returned (or the token a
|
|
598
|
+
* result page reads from its address with `readResultToken`). Rejects
|
|
599
|
+
* with `result.unavailable` where the transport has no results. */
|
|
600
|
+
result: (token: string) => Promise<EventResult>;
|
|
601
|
+
/** The address to show the app's own uploaded file `name` from (an
|
|
602
|
+
* `<img src>`, a font, an audio source): `/_files/<name>` at the
|
|
603
|
+
* published address, a blob: URL of its bytes in Alma's frame.
|
|
604
|
+
* Rejects with `file.not_found`, `file.invalid_name` or
|
|
605
|
+
* `file.unavailable`. */
|
|
606
|
+
fileUrl: (name: string) => Promise<string>;
|
|
607
|
+
/** At a published address, the visitor's own entry, named by the
|
|
608
|
+
* private link this page was opened with: `#<token>` in its address
|
|
609
|
+
* (`navigate(path, { hash: result.token })` after `createTopic` or
|
|
610
|
+
* `raiseEvent` leads there; the token stays in the fragment, which no
|
|
611
|
+
* server and no log sees). Null when the address names none; `pending`
|
|
612
|
+
* until the entry is there, also for a token the site does not know;
|
|
613
|
+
* else the entry, in the shape `listTopics` gives. Rejects with
|
|
614
|
+
* `result.unavailable` in Alma's frame, where a member has no private
|
|
615
|
+
* link. */
|
|
616
|
+
ownEntry: (hash?: string) => Promise<{
|
|
617
|
+
status: "pending";
|
|
618
|
+
} | ({
|
|
619
|
+
status: "ready";
|
|
620
|
+
} & OwnEntry) | null>;
|
|
621
|
+
/** Reads a result until it is ready, after 1, 2, 4 and then every 8
|
|
622
|
+
* seconds, and resolves with what the workflow answered. Rejects with
|
|
623
|
+
* `result.timeout` once `timeoutMs` (default two minutes) passes with
|
|
624
|
+
* the result still pending. */
|
|
625
|
+
waitForResult: (token: string, options?: WaitForResultOptions) => Promise<unknown>;
|
|
573
626
|
/** This app's own state for its viewer: a small store for what only
|
|
574
627
|
* this person's screen of this app needs between visits, such as a
|
|
575
628
|
* filter, a collapsed column or a half-written draft. It needs no scope
|
|
@@ -616,9 +669,10 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
616
669
|
* is written; where the workspace keeps values off the push, the SDK
|
|
617
670
|
* reads the key first. Every key is read again every five minutes, and
|
|
618
671
|
* whenever the host may have missed a change. Where the host tells
|
|
619
|
-
* nothing (a host from before it, or a channel the server refuses),
|
|
620
|
-
*
|
|
621
|
-
* while nothing changes).
|
|
672
|
+
* nothing (a host from before it, or a channel the server refuses), and
|
|
673
|
+
* while the host is still joining, the SDK polls on `intervalMs`
|
|
674
|
+
* (default 5 seconds, doubling to a minute while nothing changes).
|
|
675
|
+
* Returns the unsubscribe.
|
|
622
676
|
*/
|
|
623
677
|
watch: (listener: (entry: Api.AppSharedStateEntry) => void, options?: {
|
|
624
678
|
intervalMs?: number;
|
|
@@ -640,20 +694,24 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
640
694
|
* cursor, a ping, a reaction. It reaches each open copy's `onBroadcast`
|
|
641
695
|
* listeners for `event` within about a second and is never stored, so a
|
|
642
696
|
* copy that opens later never hears it; keep what it needs in `shared`.
|
|
643
|
-
* Needs `shared_state:write`. A payload over 8 KiB of JSON,
|
|
644
|
-
* 10 messages a second after a burst of 20,
|
|
645
|
-
*
|
|
697
|
+
* Needs `shared_state:write`. A payload over 8 KiB of JSON, more than
|
|
698
|
+
* 10 messages a second from one person after a burst of 20, or more than
|
|
699
|
+
* 30 a second from everyone using the installation together after a
|
|
700
|
+
* burst of 60, rejects with an `AppCallError` whose `code` says which.
|
|
646
701
|
*/
|
|
647
702
|
broadcast: (event: string, payload?: unknown) => Promise<void>;
|
|
648
703
|
/**
|
|
649
704
|
* Calls `listener` with the payload of each quick message sent for
|
|
650
705
|
* `event` while the app is open. Messages this copy sent are left out
|
|
651
|
-
* unless `self` is set.
|
|
652
|
-
*
|
|
653
|
-
*
|
|
706
|
+
* unless `self` is set. `missed` is called when messages may have passed
|
|
707
|
+
* unheard: the host's channel joined late, or was lost and is back. Where
|
|
708
|
+
* the host tells nothing (a host from before it, an app without
|
|
709
|
+
* `shared_state:write`, or a channel the server refuses), neither is
|
|
710
|
+
* ever called. Returns the unsubscribe.
|
|
654
711
|
*/
|
|
655
712
|
onBroadcast: (event: string, listener: (payload: unknown) => void, options?: {
|
|
656
713
|
self?: boolean;
|
|
714
|
+
missed?: () => void;
|
|
657
715
|
}) => (() => void);
|
|
658
716
|
/** What changed in a record since its viewer last looked at it in this
|
|
659
717
|
* app. `mark` notes a record as they see it now (from `getTopicRecord`
|