@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/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, and how to stop hearing them. */
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
- export interface BroadcastTold {
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
- getTopicRecord: (topicId: string) => Promise<Api.AppTopicRecord>;
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
- createTopic: (name: string, topicTypeId?: string, options?: CreateTopicOptions) => Promise<Api.CreatedTopicRecord>;
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
- raiseEvent: (event: string, payload?: Record<string, unknown>, options?: ChangeOptions) => Promise<Api.AppEventRaised>;
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), the
620
- * SDK polls on `intervalMs` (default 5 seconds, doubling to a minute
621
- * while nothing changes). Returns the unsubscribe.
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, or more than
644
- * 10 messages a second after a burst of 20, rejects with an
645
- * `AppCallError` whose `code` says which.
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. Where the host tells nothing (a host from before
652
- * it, an app without `shared_state:write`, or a channel the server
653
- * refuses), `listener` is never called. Returns the unsubscribe.
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`