@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/index.d.ts
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
|
+
import { AppCallError, type FieldState } from "./callError";
|
|
1
2
|
import type * as Api from "./generated/apiTypes";
|
|
3
|
+
import type { EventResult, EventResultTicket, WaitForResultOptions } from "./siteRuntime";
|
|
4
|
+
export { AppCallError, type FieldState } from "./callError";
|
|
2
5
|
export * from "./navigation";
|
|
6
|
+
export * from "./site";
|
|
7
|
+
export * from "./siteRuntime";
|
|
3
8
|
export type * from "./generated/apiTypes";
|
|
4
9
|
/** Which records `listTopics` reads. `schema` is the `schema.id` of a `type`
|
|
5
10
|
* another app keeps. A field filter is `<field>:<op>:<value>` (op: eq, ne,
|
|
@@ -48,6 +53,12 @@ export interface PollOptions {
|
|
|
48
53
|
* "Waiting for Lena". */
|
|
49
54
|
onUpdate?: (execution: Api.AppExecution) => void;
|
|
50
55
|
}
|
|
56
|
+
/** A run whose program returns a `result` of a shape the app knows, as
|
|
57
|
+
* `waitForExecution<T>` gives it. Unchecked: the app's own program is what
|
|
58
|
+
* vouches for `T`. */
|
|
59
|
+
export type AppExecutionOf<T> = Omit<Api.AppExecution, "result"> & {
|
|
60
|
+
result: T | null;
|
|
61
|
+
};
|
|
51
62
|
/** Every Alma `/v1` operation an app may call, by OpenAPI operationId, and
|
|
52
63
|
* whether it only reads or makes a change as its viewer. The host refuses
|
|
53
64
|
* any other name and any operation outside the manifest's scopes. */
|
|
@@ -76,7 +87,6 @@ declare const APP_OPERATIONS: {
|
|
|
76
87
|
readonly runWorkflow: "change";
|
|
77
88
|
readonly listWorkflowExecutions: "read";
|
|
78
89
|
readonly getExecution: "read";
|
|
79
|
-
readonly listOutcomes: "read";
|
|
80
90
|
readonly publishCard: "change";
|
|
81
91
|
readonly raiseAppEvent: "change";
|
|
82
92
|
readonly getAppState: "read";
|
|
@@ -99,26 +109,6 @@ export interface AppRequest {
|
|
|
99
109
|
* arrived) answers with what the first attempt did and changes nothing. */
|
|
100
110
|
idempotencyKey?: string;
|
|
101
111
|
}
|
|
102
|
-
/** A field as it stands: its revision and the values it holds. */
|
|
103
|
-
export interface FieldState {
|
|
104
|
-
revision: string;
|
|
105
|
-
values: {
|
|
106
|
-
text: string;
|
|
107
|
-
typed: Api.TypedValue | null;
|
|
108
|
-
}[];
|
|
109
|
-
}
|
|
110
|
-
/** A refused call. `message` is the refusal's words, to show as they are.
|
|
111
|
-
* A refusal a program can act on also carries its `code`; `field.changed`
|
|
112
|
-
* carries the field as it stands in `current`, and
|
|
113
|
-
* `app_shared_state.revision_conflict` the shared key. */
|
|
114
|
-
export declare class AppCallError extends Error {
|
|
115
|
-
readonly code: string | undefined;
|
|
116
|
-
readonly current: FieldState | Api.AppSharedStateEntry | undefined;
|
|
117
|
-
constructor(message: string, detail?: {
|
|
118
|
-
code?: string;
|
|
119
|
-
current?: FieldState | Api.AppSharedStateEntry;
|
|
120
|
-
});
|
|
121
|
-
}
|
|
122
112
|
/** A field write refused because the field changed after the app read it.
|
|
123
113
|
* Nothing was written; `current` is what the field holds now. */
|
|
124
114
|
export type FieldChangedError = AppCallError & {
|
|
@@ -268,18 +258,23 @@ export type SharedStateTold = {
|
|
|
268
258
|
missed: true;
|
|
269
259
|
};
|
|
270
260
|
/** What a host answers a shared-state watch with: whether it will tell
|
|
271
|
-
* changes,
|
|
261
|
+
* changes, whether it is still joining (it tells `missed` once it is in,
|
|
262
|
+
* and changes from then on), and how to stop hearing them. */
|
|
272
263
|
export interface SharedStateWatch {
|
|
273
264
|
watching: boolean;
|
|
265
|
+
joining?: boolean;
|
|
274
266
|
stop(): void;
|
|
275
267
|
}
|
|
276
268
|
/** A quick message as a host tells it: its event, its payload, and whether
|
|
277
|
-
* this open copy of the app sent it
|
|
278
|
-
|
|
269
|
+
* this open copy of the app sent it; or that messages may have passed
|
|
270
|
+
* unheard. */
|
|
271
|
+
export type BroadcastTold = {
|
|
279
272
|
event: string;
|
|
280
273
|
payload: unknown;
|
|
281
274
|
self: boolean;
|
|
282
|
-
}
|
|
275
|
+
} | {
|
|
276
|
+
missed: true;
|
|
277
|
+
};
|
|
283
278
|
/** What a host answers a broadcast watch with: whether it will tell
|
|
284
279
|
* messages, and how to stop hearing them. */
|
|
285
280
|
export interface BroadcastWatch {
|
|
@@ -315,6 +310,10 @@ export interface AppTransport {
|
|
|
315
310
|
/** Be told each quick message sent to everyone with the app open. A
|
|
316
311
|
* transport without it tells nothing. */
|
|
317
312
|
watchBroadcasts?(told: (message: BroadcastTold) => void): Promise<BroadcastWatch>;
|
|
313
|
+
/** What a raised event's workflow has answered so far, by the `token` a
|
|
314
|
+
* published site's raise returned. A transport without it has no
|
|
315
|
+
* results to read. */
|
|
316
|
+
result?(token: string): Promise<EventResult>;
|
|
318
317
|
}
|
|
319
318
|
export declare function createAppSdk(transport: AppTransport): {
|
|
320
319
|
call: <T>(operationId: AppOperationId, request?: AppRequest) => Promise<T>;
|
|
@@ -519,7 +518,8 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
519
518
|
/** Starts a workflow the app's manifest names. Nobody is asked: it starts
|
|
520
519
|
* where the workflow's owner granted the app, or the viewer may run it
|
|
521
520
|
* themselves, on a record they can see, and rejects with the refusal's
|
|
522
|
-
* words otherwise. The run acts as the workflow, not as the viewer
|
|
521
|
+
* words otherwise. The run acts as the workflow, not as the viewer: only
|
|
522
|
+
* a step account set to whoever starts the run is the viewer's own. */
|
|
523
523
|
runWorkflow: (workflowId: string, run?: {
|
|
524
524
|
topicId?: string;
|
|
525
525
|
input?: Record<string, unknown>;
|
|
@@ -529,14 +529,15 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
529
529
|
getExecution: (executionId: string) => Promise<Api.AppExecution>;
|
|
530
530
|
/** The newest runs of a workflow the app names that the viewer may read,
|
|
531
531
|
* on one record when `topicId` names it: how an app opened again finds
|
|
532
|
-
* the run it started
|
|
533
|
-
listRuns: (workflowId: string, run?: {
|
|
532
|
+
* the run it started, with `result` typed as `T`. */
|
|
533
|
+
listRuns: <T = unknown>(workflowId: string, run?: {
|
|
534
534
|
topicId?: string;
|
|
535
|
-
}) => Promise<
|
|
535
|
+
}) => Promise<AppExecutionOf<T>[]>;
|
|
536
536
|
/** Polls a run with backoff until it finishes, and resolves with how it
|
|
537
|
-
* ended
|
|
538
|
-
* `signal` to
|
|
539
|
-
|
|
537
|
+
* ended, with `result` typed as `T` where its code step returns one. A
|
|
538
|
+
* run waiting on an approver can wait for a long time; pass a `signal` to
|
|
539
|
+
* stop. */
|
|
540
|
+
waitForExecution: <T = unknown>(executionId: string, options?: PollOptions) => Promise<AppExecutionOf<T>>;
|
|
540
541
|
getWorkflowCard: (workflowId: string) => Promise<Api.WorkflowCard>;
|
|
541
542
|
/** Adds a lesson for the workflow's later runs. It is live at once
|
|
542
543
|
* (`active: true`) when the viewer can edit the workflow; otherwise it
|
|
@@ -561,8 +562,23 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
561
562
|
* with `payload` as data it does not trust. The answer is the same
|
|
562
563
|
* whether or not a workflow listens. An event the shared version does
|
|
563
564
|
* not declare rejects with `event.undeclared`; past the app's events for
|
|
564
|
-
* the hour, with `event.rate_limited` and when to try again.
|
|
565
|
-
|
|
565
|
+
* the hour, with `event.rate_limited` and when to try again. On a
|
|
566
|
+
* published site the answer also carries `result` when the event's
|
|
567
|
+
* workflow answers the visitor, and a refusal for now is a
|
|
568
|
+
* `SiteRefusalError` (`visitor.rate_limited`, `site.paused`). */
|
|
569
|
+
raiseEvent: (event: string, payload?: Record<string, unknown>, options?: ChangeOptions) => Promise<Api.AppEventRaised & {
|
|
570
|
+
result?: EventResultTicket;
|
|
571
|
+
}>;
|
|
572
|
+
/** On a published site, what the workflow a raise started has answered
|
|
573
|
+
* so far, by the `result.token` the raise returned (or the token a
|
|
574
|
+
* result page reads from its address with `readResultToken`). Rejects
|
|
575
|
+
* with `result.unavailable` where the transport has no results. */
|
|
576
|
+
result: (token: string) => Promise<EventResult>;
|
|
577
|
+
/** Reads a result until it is ready, after 1, 2, 4 and then every 8
|
|
578
|
+
* seconds, and resolves with what the workflow answered. Rejects with
|
|
579
|
+
* `result.timeout` once `timeoutMs` (default two minutes) passes with
|
|
580
|
+
* the result still pending. */
|
|
581
|
+
waitForResult: (token: string, options?: WaitForResultOptions) => Promise<unknown>;
|
|
566
582
|
/** This app's own state for its viewer: a small store for what only
|
|
567
583
|
* this person's screen of this app needs between visits, such as a
|
|
568
584
|
* filter, a collapsed column or a half-written draft. It needs no scope
|
|
@@ -609,9 +625,10 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
609
625
|
* is written; where the workspace keeps values off the push, the SDK
|
|
610
626
|
* reads the key first. Every key is read again every five minutes, and
|
|
611
627
|
* whenever the host may have missed a change. Where the host tells
|
|
612
|
-
* nothing (a host from before it, or a channel the server refuses),
|
|
613
|
-
*
|
|
614
|
-
* while nothing changes).
|
|
628
|
+
* nothing (a host from before it, or a channel the server refuses), and
|
|
629
|
+
* while the host is still joining, the SDK polls on `intervalMs`
|
|
630
|
+
* (default 5 seconds, doubling to a minute while nothing changes).
|
|
631
|
+
* Returns the unsubscribe.
|
|
615
632
|
*/
|
|
616
633
|
watch: (listener: (entry: Api.AppSharedStateEntry) => void, options?: {
|
|
617
634
|
intervalMs?: number;
|
|
@@ -633,28 +650,25 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
633
650
|
* cursor, a ping, a reaction. It reaches each open copy's `onBroadcast`
|
|
634
651
|
* listeners for `event` within about a second and is never stored, so a
|
|
635
652
|
* copy that opens later never hears it; keep what it needs in `shared`.
|
|
636
|
-
* Needs `shared_state:write`. A payload over 8 KiB of JSON,
|
|
637
|
-
* 10 messages a second after a burst of 20,
|
|
638
|
-
*
|
|
653
|
+
* Needs `shared_state:write`. A payload over 8 KiB of JSON, more than
|
|
654
|
+
* 10 messages a second from one person after a burst of 20, or more than
|
|
655
|
+
* 30 a second from everyone using the installation together after a
|
|
656
|
+
* burst of 60, rejects with an `AppCallError` whose `code` says which.
|
|
639
657
|
*/
|
|
640
658
|
broadcast: (event: string, payload?: unknown) => Promise<void>;
|
|
641
659
|
/**
|
|
642
660
|
* Calls `listener` with the payload of each quick message sent for
|
|
643
661
|
* `event` while the app is open. Messages this copy sent are left out
|
|
644
|
-
* unless `self` is set.
|
|
645
|
-
*
|
|
646
|
-
*
|
|
662
|
+
* unless `self` is set. `missed` is called when messages may have passed
|
|
663
|
+
* unheard: the host's channel joined late, or was lost and is back. Where
|
|
664
|
+
* the host tells nothing (a host from before it, an app without
|
|
665
|
+
* `shared_state:write`, or a channel the server refuses), neither is
|
|
666
|
+
* ever called. Returns the unsubscribe.
|
|
647
667
|
*/
|
|
648
668
|
onBroadcast: (event: string, listener: (payload: unknown) => void, options?: {
|
|
649
669
|
self?: boolean;
|
|
670
|
+
missed?: () => void;
|
|
650
671
|
}) => (() => void);
|
|
651
|
-
listOutcomes: (page?: {
|
|
652
|
-
limit?: number;
|
|
653
|
-
offset?: number;
|
|
654
|
-
}) => Promise<{
|
|
655
|
-
data: Api.AppOutcome[];
|
|
656
|
-
meta: Api.PageMeta;
|
|
657
|
-
}>;
|
|
658
672
|
/** What changed in a record since its viewer last looked at it in this
|
|
659
673
|
* app. `mark` notes a record as they see it now (from `getTopicRecord`
|
|
660
674
|
* or `listTopics`); `changes` answers with the fields whose value moved
|