@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/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, and how to stop hearing them. */
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
- export interface BroadcastTold {
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<Api.AppExecution[]>;
535
+ }) => Promise<AppExecutionOf<T>[]>;
536
536
  /** Polls a run with backoff until it finishes, and resolves with how it
537
- * ended. A run waiting on an approver can wait for a long time; pass a
538
- * `signal` to stop. */
539
- waitForExecution: (executionId: string, options?: PollOptions) => Promise<Api.AppExecution>;
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
- raiseEvent: (event: string, payload?: Record<string, unknown>, options?: ChangeOptions) => Promise<Api.AppEventRaised>;
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), the
613
- * SDK polls on `intervalMs` (default 5 seconds, doubling to a minute
614
- * while nothing changes). Returns the unsubscribe.
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, or more than
637
- * 10 messages a second after a burst of 20, rejects with an
638
- * `AppCallError` whose `code` says which.
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. Where the host tells nothing (a host from before
645
- * it, an app without `shared_state:write`, or a channel the server
646
- * refuses), `listener` is never called. Returns the unsubscribe.
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