@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.
- package/README.md +174 -45
- package/app.d.ts +297 -0
- package/cli.js +2 -2
- package/files.d.ts +25 -0
- package/generated/apiTypes.d.ts +31 -0
- package/index.d.ts +85 -11
- package/index.js +591 -238
- package/navigation.d.ts +44 -2
- package/package.json +1 -1
- package/siteRuntime.d.ts +42 -14
- package/site.d.ts +0 -267
package/generated/apiTypes.d.ts
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
519
|
-
*
|
|
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: (
|
|
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
|
-
|
|
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
|