@almateam/app-sdk 0.9.0 → 0.11.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.
@@ -185,6 +185,11 @@ export interface AppWorkflowSummary {
185
185
  /** The newest run, on the organization's calendar, and how it went. */
186
186
  last_run?: string;
187
187
  needs_connection?: boolean;
188
+ /**
189
+ * A workflow the app ships (`manifest.workflows` `{ key, definition }`):
190
+ * the key the app starts it by, `runWorkflow({ key })`.
191
+ */
192
+ key?: string;
188
193
  /** Paused only when the newest run waits on one of the viewer's own Tasks. */
189
194
  state: "proposed" | "draft" | "live" | "paused";
190
195
  /**
@@ -291,6 +296,13 @@ export interface FactValue {
291
296
  typed: TypedValue | null;
292
297
  ref: ValueRef | null;
293
298
  }
299
+ export interface IssueRecordLink {
300
+ /**
301
+ * One of the public pages the app's website built (`/report`), which reads
302
+ * the record by the link's `#fragment` (`ownEntry()`).
303
+ */
304
+ path: string;
305
+ }
294
306
  /**
295
307
  * The topic as Knowledge renders it. Cadence, review configuration and
296
308
  * cost stay private.
@@ -333,6 +345,21 @@ export interface RecordFact {
333
345
  /** The viewer can read a discussion about this value. */
334
346
  has_discussion?: true;
335
347
  }
348
+ export interface RecordLinkIssued {
349
+ topic_id: string;
350
+ /**
351
+ * The page with the link's token in its fragment. Handed to this caller
352
+ * only and never stored; issuing again replaces it.
353
+ */
354
+ url: string;
355
+ issued_at: string;
356
+ }
357
+ export interface RecordLinkRevoked {
358
+ topic_id: string;
359
+ /** False when the record had no link to switch off. */
360
+ revoked: boolean;
361
+ revoked_at: string;
362
+ }
336
363
  export interface RecordSection {
337
364
  id: string;
338
365
  key: string;
@@ -916,6 +943,10 @@ export interface AppOperationResults {
916
943
  deleteAppSharedState: AppSharedStateEntry;
917
944
  /** Send a quick message to everyone with the app open */
918
945
  sendAppBroadcast: AppBroadcastSent;
946
+ /** Share a record by private link */
947
+ issueRecordLink: RecordLinkIssued;
948
+ /** Switch off a record's private link */
949
+ revokeRecordLink: RecordLinkRevoked;
919
950
  /** Raise one of the app's events */
920
951
  raiseAppEvent: AppEventRaised;
921
952
  }
package/index.d.ts CHANGED
@@ -1,9 +1,11 @@
1
1
  import { AppCallError, type FieldState } from "./callError";
2
2
  import type * as Api from "./generated/apiTypes";
3
- import type { EventResult, EventResultTicket, WaitForResultOptions } from "./siteRuntime";
3
+ import type { AppPlace } from "./app";
4
+ import { type EventResult, type EventResultTicket, type OwnEntry, type WaitForResultOptions } from "./siteRuntime";
4
5
  export { AppCallError, type FieldState } from "./callError";
6
+ export * from "./app";
7
+ export * from "./files";
5
8
  export * from "./navigation";
6
- export * from "./site";
7
9
  export * from "./siteRuntime";
8
10
  export type * from "./generated/apiTypes";
9
11
  /** Which records `listTopics` reads. `schema` is the `schema.id` of a `type`
@@ -67,6 +69,8 @@ declare const APP_OPERATIONS: {
67
69
  readonly createTopic: "change";
68
70
  readonly deleteTopic: "change";
69
71
  readonly restoreTopic: "change";
72
+ readonly issueRecordLink: "change";
73
+ readonly revokeRecordLink: "change";
70
74
  readonly listTopicTypes: "read";
71
75
  readonly getTopicRecord: "read";
72
76
  readonly listViews: "read";
@@ -100,7 +104,8 @@ declare const APP_OPERATIONS: {
100
104
  };
101
105
  export type AppOperationId = keyof typeof APP_OPERATIONS;
102
106
  export interface AppRequest {
103
- /** Path template parameters; the host refuses any that is not a UUID. */
107
+ /** Path template parameters; the host refuses any that is not a UUID
108
+ * (or, for a workflow the app ships, its key). */
104
109
  params?: Record<string, string>;
105
110
  /** Only the query keys the operation declares reach the API. */
106
111
  query?: Record<string, string | number | string[] | undefined>;
@@ -282,6 +287,10 @@ export interface BroadcastWatch {
282
287
  stop(): void;
283
288
  }
284
289
  export interface AppTransport {
290
+ /** Where the transport runs: `public` at the app's published address,
291
+ * where a type is named by its key. A transport without it is Alma's
292
+ * frame. */
293
+ place?: AppPlace;
285
294
  /** Resolves with the response's `data`, or `{ data, meta }` when the
286
295
  * response pages. A change is the viewer's own act: it resolves with the
287
296
  * result where they may make it, and rejects with the refusal's words
@@ -314,7 +323,18 @@ export interface AppTransport {
314
323
  * published site's raise returned. A transport without it has no
315
324
  * results to read. */
316
325
  result?(token: string): Promise<EventResult>;
326
+ /** An address the app's own uploaded file `name` shows from: at once
327
+ * where the address is known (`/_files/<name>` at a published
328
+ * address), or once the host has handed over its bytes (a blob: URL in
329
+ * Alma's frame). A transport without it has no files. */
330
+ fileUrl?(name: string): string | Promise<string>;
317
331
  }
332
+ /** A workflow the app names: its id, or `{ key }` for one the app ships
333
+ * (`manifest.workflows` `{ key, definition }`), which a copy of the app
334
+ * starts by the same key. */
335
+ export type AppWorkflowRef = string | {
336
+ key: string;
337
+ };
318
338
  export declare function createAppSdk(transport: AppTransport): {
319
339
  call: <T>(operationId: AppOperationId, request?: AppRequest) => Promise<T>;
320
340
  /** The viewer's own person record (`person_id`, a record of type
@@ -386,7 +406,13 @@ export declare function createAppSdk(transport: AppTransport): {
386
406
  groups?: Api.TypeViewGroup[];
387
407
  };
388
408
  }>;
389
- getTopicRecord: (topicId: string) => Promise<Api.AppTopicRecord>;
409
+ /** A record as the viewer reads it. At a published address it is an
410
+ * entry of a type the version lets visitors read in full, named with
411
+ * `type` (its key), in the same shape (see `PUBLIC_RECORD_SHAPE`); in
412
+ * Alma's frame `type` is not needed. */
413
+ getTopicRecord: (topicId: string, options?: {
414
+ type?: string;
415
+ }) => Promise<Api.AppTopicRecord>;
390
416
  getTopicFactDiscussion: (topicId: string, factId: string) => Promise<Api.AppFactDiscussion>;
391
417
  /** A field's earlier values, newest first, as the viewer may read
392
418
  * them. A record section's `earlier_values` says how many there are. */
@@ -494,8 +520,15 @@ export declare function createAppSdk(transport: AppTransport): {
494
520
  * see it follows the app's audience in Alma, never the app. The record and
495
521
  * its values are saved together: if one value is refused nothing is
496
522
  * created, and it rejects with the refusal's words, which start with the
497
- * field's key. Each call is one request: calling again creates again. */
498
- createTopic: (name: string, topicTypeId?: string, options?: CreateTopicOptions) => Promise<Api.CreatedTopicRecord>;
523
+ * field's key. Each call is one request: calling again creates again.
524
+ * The type is its id, or its key as the manifest names it; at a
525
+ * published address it is a type the version lets visitors add to, by
526
+ * key, `name` is its `name` field (empty lets Alma name it after the
527
+ * type), and the answer carries `result`, the visitor's private link to
528
+ * the entry, when the version lets them read their own. */
529
+ createTopic: (name: string, topicTypeId?: string, options?: CreateTopicOptions) => Promise<OperationResult<"createTopic"> & {
530
+ result?: EventResultTicket;
531
+ }>;
499
532
  /** Deletes a record of one of this app's own types as the viewer. Alma
500
533
  * keeps it for 30 days, when the person who deleted it can bring it back
501
534
  * with `restoreTopic`, or from the app's Data if they edit the app. A
@@ -512,15 +545,35 @@ export declare function createAppSdk(transport: AppTransport): {
512
545
  * refusal's words. So does one past its 30 days, until Alma removes it
513
546
  * for good; then it rejects as not found. */
514
547
  restoreTopic: (topicId: string, options?: ChangeOptions) => Promise<Api.RestoredTopicRecord>;
548
+ /** A private link to one of this app's own records, for someone outside
549
+ * Alma, as a viewer who can edit it (the `records:share` scope): the
550
+ * app's website page `path` with the link in its `#fragment`, where
551
+ * `ownEntry()` reads the record's public fields. Its type must be one
552
+ * the published app lets the public read by its private link
553
+ * (`read: "own"`), and `path` one of its public pages; from a draft the
554
+ * link opens the draft's private preview. The answer's `url` is for this
555
+ * viewer alone: hand it on, never store it. Issuing again replaces the
556
+ * link, and the old one stops working. Rejects with `link.no_address`,
557
+ * `link.not_public`, `link.not_a_page`, `link.visitor_entry` or
558
+ * `link.cannot_edit` or `link.rate_limited`, and with `site.no_viewer` at a published address,
559
+ * where nobody is signed in. */
560
+ issueRecordLink: (recordId: string, link: {
561
+ path: string;
562
+ }, options?: ChangeOptions) => Promise<Api.RecordLinkIssued>;
563
+ /** Switches off the record's private link: it stops working at once.
564
+ * `revoked` is false when the record had none. */
565
+ revokeRecordLink: (recordId: string, options?: ChangeOptions) => Promise<Api.RecordLinkRevoked>;
515
566
  /** Every type, its fields and its relationships. */
516
567
  listTopicTypes: <T = Api.TopicType[]>() => Promise<T>;
517
568
  listWorkflows: () => Promise<Api.AppWorkflowSummary[]>;
518
- /** Starts a workflow the app's manifest names. Nobody is asked: it starts
519
- * where the workflow's owner granted the app, or the viewer may run it
569
+ /** Starts a workflow the app's manifest names: by its id, or one the app
570
+ * ships by its key (`{ key: "invite" }`), which the version in use must
571
+ * ship. Nobody is asked: it starts where the workflow's owner granted the
572
+ * app (the app's own workflows always), or the viewer may run it
520
573
  * themselves, on a record they can see, and rejects with the refusal's
521
574
  * words otherwise. The run acts as the workflow, not as the viewer: only
522
575
  * a step account set to whoever starts the run is the viewer's own. */
523
- runWorkflow: (workflowId: string, run?: {
576
+ runWorkflow: (workflow: AppWorkflowRef, run?: {
524
577
  topicId?: string;
525
578
  input?: Record<string, unknown>;
526
579
  }, options?: ChangeOptions) => Promise<Api.AppRunReceipt>;
@@ -529,8 +582,9 @@ export declare function createAppSdk(transport: AppTransport): {
529
582
  getExecution: (executionId: string) => Promise<Api.AppExecution>;
530
583
  /** The newest runs of a workflow the app names that the viewer may read,
531
584
  * on one record when `topicId` names it: how an app opened again finds
532
- * the run it started, with `result` typed as `T`. */
533
- listRuns: <T = unknown>(workflowId: string, run?: {
585
+ * the run it started, with `result` typed as `T`. Takes the workflow's
586
+ * id or, for one the app ships, `{ key }`. */
587
+ listRuns: <T = unknown>(workflow: AppWorkflowRef, run?: {
534
588
  topicId?: string;
535
589
  }) => Promise<AppExecutionOf<T>[]>;
536
590
  /** Polls a run with backoff until it finishes, and resolves with how it
@@ -574,6 +628,26 @@ export declare function createAppSdk(transport: AppTransport): {
574
628
  * result page reads from its address with `readResultToken`). Rejects
575
629
  * with `result.unavailable` where the transport has no results. */
576
630
  result: (token: string) => Promise<EventResult>;
631
+ /** The address to show the app's own uploaded file `name` from (an
632
+ * `<img src>`, a font, an audio source): `/_files/<name>` at the
633
+ * published address, a blob: URL of its bytes in Alma's frame.
634
+ * Rejects with `file.not_found`, `file.invalid_name` or
635
+ * `file.unavailable`. */
636
+ fileUrl: (name: string) => Promise<string>;
637
+ /** At a published address, the visitor's own entry, named by the
638
+ * private link this page was opened with: `#<token>` in its address
639
+ * (`navigate(path, { hash: result.token })` after `createTopic` or
640
+ * `raiseEvent` leads there; the token stays in the fragment, which no
641
+ * server and no log sees). Null when the address names none; `pending`
642
+ * until the entry is there, also for a token the site does not know;
643
+ * else the entry, in the shape `listTopics` gives. Rejects with
644
+ * `result.unavailable` in Alma's frame, where a member has no private
645
+ * link. */
646
+ ownEntry: (hash?: string) => Promise<{
647
+ status: "pending";
648
+ } | ({
649
+ status: "ready";
650
+ } & OwnEntry) | null>;
577
651
  /** Reads a result until it is ready, after 1, 2, 4 and then every 8
578
652
  * seconds, and resolves with what the workflow answered. Rejects with
579
653
  * `result.timeout` once `timeoutMs` (default two minutes) passes with