@almateam/app-sdk 0.3.1 → 0.4.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 +70 -16
- package/generated/apiTypes.d.ts +111 -0
- package/index.d.ts +69 -2
- package/index.js +90 -19
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ An app imports the SDK as `@alma/app-sdk`. Install the published package under
|
|
|
8
8
|
that name, for its types:
|
|
9
9
|
|
|
10
10
|
```sh
|
|
11
|
-
npm install --save-dev @alma/app-sdk@npm:@almateam/app-sdk@^0.
|
|
11
|
+
npm install --save-dev @alma/app-sdk@npm:@almateam/app-sdk@^0.4.0
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
Alma builds an app's source with its own current copy of the SDK, whatever
|
|
@@ -64,23 +64,77 @@ topic the viewer can edit, and is parsed against its field — a date that is no
|
|
|
64
64
|
one, or a choice outside the field's options, is refused. Setting a value the
|
|
65
65
|
field already holds confirms it as the viewer's.
|
|
66
66
|
|
|
67
|
+
A write says what the app read. Every read (`listTopics`, `getTopicRecord`)
|
|
68
|
+
carries each field's `revisions`, the SDK remembers them, and `setTopicField`
|
|
69
|
+
sends the one for the field it writes. If someone changed that field after the
|
|
70
|
+
app read it, nothing is written and the call rejects with a `field.changed`
|
|
71
|
+
error carrying what the field holds now:
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
import { isFieldChanged } from "@alma/app-sdk";
|
|
75
|
+
|
|
76
|
+
try {
|
|
77
|
+
await alma.setTopicField(topicId, "stage", "Signed");
|
|
78
|
+
} catch (error) {
|
|
79
|
+
if (!isFieldChanged(error)) throw error;
|
|
80
|
+
// "This changed since you opened it": show error.current.values, let the
|
|
81
|
+
// viewer decide again, then write against what they were shown.
|
|
82
|
+
await alma.setTopicField(topicId, "stage", "Signed", undefined, {
|
|
83
|
+
ifRevision: error.current.revision,
|
|
84
|
+
});
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Read the record before writing it, so the SDK has something to send: a write
|
|
89
|
+
that says nothing about what it read will be refused. To say it yourself, pass
|
|
90
|
+
`{ ifRevision }` (a revision from a read, a receipt's `revision` or a conflict's
|
|
91
|
+
`current.revision`) or `{ ifValue }` (a value the field held, as its `text` was
|
|
92
|
+
read, or `null` if it held nothing). The receipt names how the write ended in
|
|
93
|
+
`outcome` (`applied`, `confirmed` or `unchanged`). To make a write safe to send
|
|
94
|
+
twice, pass `{ idempotencyKey }`: the same key and request again answers with
|
|
95
|
+
the first receipt and writes nothing, marked `superseded` if the field has
|
|
96
|
+
changed since.
|
|
97
|
+
|
|
98
|
+
## State: what only this person's screen needs
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
await alma.state.set("filter", { stage: "Live" });
|
|
102
|
+
const filter = await alma.state.get<{ stage: string }>("filter"); // or undefined
|
|
103
|
+
await alma.state.delete("filter");
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
If another person, a workflow or Alma needs to see or act on something, it is a
|
|
107
|
+
record. If only this app's screen for this person needs it, it is app state.
|
|
108
|
+
|
|
109
|
+
State is a small key/value store per installed app and per person: a filter, a
|
|
110
|
+
collapsed column, a half-written draft. Only that person's sessions of that app
|
|
111
|
+
read or write it. It needs no scope and no owner's approval, and declaring
|
|
112
|
+
nothing for it does not widen a version. Nothing in it reaches a workflow run,
|
|
113
|
+
search or anything Alma knows; there is no store an app's people share. It
|
|
114
|
+
survives a reload and a new version of the app, and goes when the app is removed
|
|
115
|
+
from the workspace or the person leaves it. Keys are letters, digits, `_` and
|
|
116
|
+
`-` (up to 128 characters). A value is any JSON up to 16 KB, and one person
|
|
117
|
+
holds at most 64 keys and 256 KB in one app; a `set` past a limit rejects with a
|
|
118
|
+
refusal whose `code` is `app_state.value_too_large` or
|
|
119
|
+
`app_state.quota_exceeded`.
|
|
120
|
+
|
|
67
121
|
## Records: the workspace's typed topics
|
|
68
122
|
|
|
69
|
-
An app
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
123
|
+
An app's records are the workspace's topics, of the types its manifest declares
|
|
124
|
+
(`types`): each type's `key` and `name`, its `fields` (a key, a name, a value
|
|
125
|
+
type of `text`, `date`, `number`, `money` or `choice`, and a choice's `options`)
|
|
126
|
+
and its `relationships` (a `label`, the key of the type it points at, such as
|
|
127
|
+
`person` or `contact`, and a `cardinality`). When an owner's share installs the
|
|
128
|
+
app, the workspace's type of that key is reused, gaining what it lacks, or
|
|
129
|
+
created. `listTopics({ type, filter, sort })` reads them as the viewer,
|
|
130
|
+
`setTopicField` changes one as the viewer, and `createTopic(name, typeId)` (the
|
|
131
|
+
id from `listTopicTypes()`) creates one: the host shows Alma's own access sheet,
|
|
132
|
+
starting from the app's audience, and the viewer chooses who can see it. A
|
|
133
|
+
relationship's values sit under `rel_<label>__<type key>` (`rel_csm__person`). A
|
|
134
|
+
version declaring a type, field or relationship the shared version did not is
|
|
135
|
+
wider and asks an owner; while the app is installed, the workspace's schema
|
|
136
|
+
editor lists it under "Used by" and refuses to retype or remove what it
|
|
137
|
+
declares.
|
|
84
138
|
|
|
85
139
|
## Workflows: the app's backend
|
|
86
140
|
|
package/generated/apiTypes.d.ts
CHANGED
|
@@ -61,10 +61,27 @@ export interface AppRunReceipt {
|
|
|
61
61
|
status: string;
|
|
62
62
|
created_at: string;
|
|
63
63
|
}
|
|
64
|
+
/**
|
|
65
|
+
* One key of an app's own state for its viewer: what only that person's
|
|
66
|
+
* screen of that app needs between visits.
|
|
67
|
+
*/
|
|
68
|
+
export interface AppStateEntry {
|
|
69
|
+
key: string;
|
|
70
|
+
/** Whether the key holds a value; one never set, or deleted, does not. */
|
|
71
|
+
exists: boolean;
|
|
72
|
+
/** The stored JSON; null when the key holds nothing. */
|
|
73
|
+
value: unknown;
|
|
74
|
+
}
|
|
64
75
|
export interface AppTopicRecord {
|
|
65
76
|
topic: TopicRef;
|
|
66
77
|
record: KnowledgeRecord;
|
|
67
78
|
facts: TopicFact[];
|
|
79
|
+
/**
|
|
80
|
+
* Each field's revision, by field key, for every field that holds a value.
|
|
81
|
+
* Send it back as `if_revision` when writing that field; a field absent
|
|
82
|
+
* here holds nothing (`if_value: null`).
|
|
83
|
+
*/
|
|
84
|
+
revisions: Record<string, string>;
|
|
68
85
|
}
|
|
69
86
|
/**
|
|
70
87
|
* A row of the member Workflows list: a workflow the viewer reads the card
|
|
@@ -75,6 +92,7 @@ export interface AppWorkflowSummary {
|
|
|
75
92
|
name: string;
|
|
76
93
|
/** The newest run, on the organization's calendar, and how it went. */
|
|
77
94
|
last_run?: string;
|
|
95
|
+
needs_connection?: boolean;
|
|
78
96
|
/** Paused only when the newest run waits on one of the viewer's own Tasks. */
|
|
79
97
|
state: "proposed" | "draft" | "live" | "paused";
|
|
80
98
|
/**
|
|
@@ -190,6 +208,11 @@ export interface RecordSection {
|
|
|
190
208
|
value_type: "text" | "date" | "number" | "money" | "choice";
|
|
191
209
|
currency?: string;
|
|
192
210
|
options?: string[];
|
|
211
|
+
/**
|
|
212
|
+
* How many earlier values of this field the viewer can read with
|
|
213
|
+
* `getTopicFieldHistory`; absent when there are none.
|
|
214
|
+
*/
|
|
215
|
+
earlier_values?: number;
|
|
193
216
|
facts: RecordFact[];
|
|
194
217
|
}
|
|
195
218
|
export interface RecordUpdate {
|
|
@@ -247,7 +270,58 @@ export interface TopicFact {
|
|
|
247
270
|
value: FactValue;
|
|
248
271
|
verified_at: string | null;
|
|
249
272
|
}
|
|
273
|
+
export interface TopicFieldHistory {
|
|
274
|
+
topic_id: string;
|
|
275
|
+
field_key: string;
|
|
276
|
+
entries: TopicFieldHistoryEntry[];
|
|
277
|
+
}
|
|
278
|
+
/** One earlier value of a field, as a reader of the record sees it. */
|
|
279
|
+
export interface TopicFieldHistoryEntry {
|
|
280
|
+
id: string;
|
|
281
|
+
value: string;
|
|
282
|
+
value_json: TypedValue | null;
|
|
283
|
+
/**
|
|
284
|
+
* Who or what a history line names: a person (named where the viewer can
|
|
285
|
+
* still resolve them), Alma, or a workflow's run.
|
|
286
|
+
*/
|
|
287
|
+
written_by: {
|
|
288
|
+
kind: "person";
|
|
289
|
+
name: string | null;
|
|
290
|
+
} | {
|
|
291
|
+
kind: "alma";
|
|
292
|
+
} | {
|
|
293
|
+
kind: "workflow";
|
|
294
|
+
};
|
|
295
|
+
/** Who had confirmed the value while it stood. */
|
|
296
|
+
verified_by: {
|
|
297
|
+
name: string | null;
|
|
298
|
+
at: string;
|
|
299
|
+
} | null;
|
|
300
|
+
/** Why the value stopped standing. */
|
|
301
|
+
reason: "corrected" | "superseded" | "retracted" | "rejected" | "moved" | "unattributed";
|
|
302
|
+
/** The preset a person gave for removing it, when they gave one. */
|
|
303
|
+
rejection_reason: "wrong_entity" | "inaccurate" | "irrelevant" | "duplicate" | null;
|
|
304
|
+
/** Who or what made the change; null when no writer declared itself. */
|
|
305
|
+
changed_by: {
|
|
306
|
+
kind: "person";
|
|
307
|
+
name: string | null;
|
|
308
|
+
} | {
|
|
309
|
+
kind: "alma";
|
|
310
|
+
} | {
|
|
311
|
+
kind: "workflow";
|
|
312
|
+
} | null;
|
|
313
|
+
/** What took its place, when something did. */
|
|
314
|
+
replaced_by_value: string | null;
|
|
315
|
+
stood_from: string | null;
|
|
316
|
+
replaced_at: string;
|
|
317
|
+
}
|
|
250
318
|
export interface TopicFieldReceipt {
|
|
319
|
+
/**
|
|
320
|
+
* `applied` wrote the value; `confirmed` marked a value the field already
|
|
321
|
+
* held as the caller's; `unchanged` found it already confirmed.
|
|
322
|
+
*/
|
|
323
|
+
outcome: "applied" | "confirmed" | "unchanged";
|
|
324
|
+
/** Deprecated: read `outcome` (`saved` is `applied`). */
|
|
251
325
|
status: "saved" | "confirmed" | "unchanged";
|
|
252
326
|
topic_id: string;
|
|
253
327
|
field_key: string;
|
|
@@ -256,6 +330,21 @@ export interface TopicFieldReceipt {
|
|
|
256
330
|
text: string;
|
|
257
331
|
typed: TypedValue | null;
|
|
258
332
|
};
|
|
333
|
+
/**
|
|
334
|
+
* The field's revision once this write stood: the `if_revision` of the
|
|
335
|
+
* next write.
|
|
336
|
+
*/
|
|
337
|
+
revision: string;
|
|
338
|
+
applied_at: string;
|
|
339
|
+
/** The call ledger row that records this write. */
|
|
340
|
+
call_id: string | null;
|
|
341
|
+
/**
|
|
342
|
+
* On a retry under the same Idempotency-Key: the field has changed since
|
|
343
|
+
* this write, and nothing was written again.
|
|
344
|
+
*/
|
|
345
|
+
superseded?: true;
|
|
346
|
+
/** With `superseded`: the field's revision now. */
|
|
347
|
+
current_revision?: string;
|
|
259
348
|
}
|
|
260
349
|
export interface TopicRecord {
|
|
261
350
|
id: string;
|
|
@@ -271,6 +360,12 @@ export interface TopicRecord {
|
|
|
271
360
|
icon: string | null;
|
|
272
361
|
} | null;
|
|
273
362
|
values: Record<string, FactValue[]>;
|
|
363
|
+
/**
|
|
364
|
+
* Each field's revision, by field key, for every field that holds a value.
|
|
365
|
+
* Send it back as `if_revision` when writing that field; a field absent
|
|
366
|
+
* here holds nothing (`if_value: null`).
|
|
367
|
+
*/
|
|
368
|
+
revisions: Record<string, string>;
|
|
274
369
|
unverified_value_count: number;
|
|
275
370
|
can_edit: boolean;
|
|
276
371
|
created_at: string;
|
|
@@ -345,6 +440,14 @@ export interface WorkflowCard {
|
|
|
345
440
|
runs: WorkflowRun[];
|
|
346
441
|
lessons: WorkflowLesson[];
|
|
347
442
|
can_edit_lessons: boolean;
|
|
443
|
+
connection_blocks?: {
|
|
444
|
+
step_id: string;
|
|
445
|
+
step_name: string;
|
|
446
|
+
provider: string;
|
|
447
|
+
owner_user_id: string | null;
|
|
448
|
+
account_name: string;
|
|
449
|
+
reason: "missing" | "expired" | "revoked" | "identity_unverified" | "account_unavailable" | "credential_missing" | "scope_missing" | "requester_required";
|
|
450
|
+
}[];
|
|
348
451
|
/** Only topics the viewer can open. */
|
|
349
452
|
topics: WorkflowTopic[];
|
|
350
453
|
audience?: RecordAudience;
|
|
@@ -388,6 +491,8 @@ export interface AppOperationResults {
|
|
|
388
491
|
listTopicTypes: TopicType[];
|
|
389
492
|
/** Get a topic's record */
|
|
390
493
|
getTopicRecord: AppTopicRecord;
|
|
494
|
+
/** Get a field's earlier values */
|
|
495
|
+
getTopicFieldHistory: TopicFieldHistory;
|
|
391
496
|
/** Get the discussion about a value */
|
|
392
497
|
getTopicFactDiscussion: AppFactDiscussion;
|
|
393
498
|
/** Set a field's value */
|
|
@@ -413,4 +518,10 @@ export interface AppOperationResults {
|
|
|
413
518
|
};
|
|
414
519
|
/** Get the organization's defined aggregates */
|
|
415
520
|
getOrganizationAnalytics: OrganizationAnalytics;
|
|
521
|
+
/** Read a key of the app's state */
|
|
522
|
+
getAppState: AppStateEntry;
|
|
523
|
+
/** Set a key of the app's state */
|
|
524
|
+
setAppState: AppStateEntry;
|
|
525
|
+
/** Delete a key of the app's state */
|
|
526
|
+
deleteAppState: AppStateEntry;
|
|
416
527
|
}
|
package/index.d.ts
CHANGED
|
@@ -43,6 +43,7 @@ declare const APP_OPERATIONS: {
|
|
|
43
43
|
readonly listTopicTypes: "read";
|
|
44
44
|
readonly getTopicRecord: "read";
|
|
45
45
|
readonly getTopicFactDiscussion: "read";
|
|
46
|
+
readonly getTopicFieldHistory: "read";
|
|
46
47
|
readonly downloadTopicFactAttachment: "read";
|
|
47
48
|
readonly setTopicField: "change";
|
|
48
49
|
readonly listWorkflows: "read";
|
|
@@ -54,6 +55,9 @@ declare const APP_OPERATIONS: {
|
|
|
54
55
|
readonly getExecution: "read";
|
|
55
56
|
readonly listOutcomes: "read";
|
|
56
57
|
readonly getOrganizationAnalytics: "read";
|
|
58
|
+
readonly getAppState: "read";
|
|
59
|
+
readonly setAppState: "change";
|
|
60
|
+
readonly deleteAppState: "change";
|
|
57
61
|
};
|
|
58
62
|
export type AppOperationId = keyof typeof APP_OPERATIONS;
|
|
59
63
|
export interface AppRequest {
|
|
@@ -62,6 +66,46 @@ export interface AppRequest {
|
|
|
62
66
|
/** Only the query keys the operation declares reach the API. */
|
|
63
67
|
query?: Record<string, string | number | string[] | undefined>;
|
|
64
68
|
body?: Record<string, unknown>;
|
|
69
|
+
/** Names one request, so making it again (after an answer that never
|
|
70
|
+
* arrived) answers with what the first attempt did and changes nothing. */
|
|
71
|
+
idempotencyKey?: string;
|
|
72
|
+
}
|
|
73
|
+
/** A field as it stands: its revision and the values it holds. */
|
|
74
|
+
export interface FieldState {
|
|
75
|
+
revision: string;
|
|
76
|
+
values: {
|
|
77
|
+
text: string;
|
|
78
|
+
typed: Api.TypedValue | null;
|
|
79
|
+
}[];
|
|
80
|
+
}
|
|
81
|
+
/** A refused call. `message` is the refusal's words, to show as they are.
|
|
82
|
+
* A refusal a program can act on also carries its `code`; `field.changed`
|
|
83
|
+
* carries the field as it stands in `current`. */
|
|
84
|
+
export declare class AppCallError extends Error {
|
|
85
|
+
readonly code: string | undefined;
|
|
86
|
+
readonly current: FieldState | undefined;
|
|
87
|
+
constructor(message: string, detail?: {
|
|
88
|
+
code?: string;
|
|
89
|
+
current?: FieldState;
|
|
90
|
+
});
|
|
91
|
+
}
|
|
92
|
+
/** A field write refused because the field changed after the app read it.
|
|
93
|
+
* Nothing was written; `current` is what the field holds now. */
|
|
94
|
+
export type FieldChangedError = AppCallError & {
|
|
95
|
+
code: "field.changed";
|
|
96
|
+
current: FieldState;
|
|
97
|
+
};
|
|
98
|
+
export declare function isFieldChanged(error: unknown): error is FieldChangedError;
|
|
99
|
+
/** What a field write says the app read before writing. Left out, the SDK
|
|
100
|
+
* sends what its own last read of the record showed. */
|
|
101
|
+
export interface FieldWriteOptions {
|
|
102
|
+
/** The field's revision, from a record's `revisions`, a receipt's
|
|
103
|
+
* `revision` or a conflict's `current.revision`. */
|
|
104
|
+
ifRevision?: string;
|
|
105
|
+
/** A value the field held, as its `text` was read; null if it held
|
|
106
|
+
* nothing. */
|
|
107
|
+
ifValue?: string | null;
|
|
108
|
+
idempotencyKey?: string;
|
|
65
109
|
}
|
|
66
110
|
export interface AppTransport {
|
|
67
111
|
/** Resolves with the response's `data`, or `{ data, meta }` when the
|
|
@@ -80,6 +124,9 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
80
124
|
}>;
|
|
81
125
|
getTopicRecord: (topicId: string) => Promise<Api.AppTopicRecord>;
|
|
82
126
|
getTopicFactDiscussion: (topicId: string, factId: string) => Promise<Api.AppFactDiscussion>;
|
|
127
|
+
/** A field's earlier values, newest first, as the viewer may read
|
|
128
|
+
* them. A record section's `earlier_values` says how many there are. */
|
|
129
|
+
getTopicFieldHistory: (topicId: string, fieldKey: string) => Promise<Api.TopicFieldHistory>;
|
|
83
130
|
/** The host downloads the file itself; the app receives only a receipt. */
|
|
84
131
|
downloadTopicFactAttachment: (topicId: string, factId: string, turn: {
|
|
85
132
|
kind: "message" | "queued";
|
|
@@ -88,8 +135,15 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
88
135
|
/** Sets one field as the viewer, where they may edit the topic;
|
|
89
136
|
* rejects with the refusal's words where they may not. Nobody is asked.
|
|
90
137
|
* Setting a value the field already holds confirms it as theirs. On a
|
|
91
|
-
* relationship, `refTopicId` names the topic the value refers to.
|
|
92
|
-
|
|
138
|
+
* relationship, `refTopicId` names the topic the value refers to.
|
|
139
|
+
*
|
|
140
|
+
* The write says what this app last read of the field (from
|
|
141
|
+
* `listTopics` or `getTopicRecord`). If the field changed since, nothing
|
|
142
|
+
* is written and it rejects with a `field.changed` error
|
|
143
|
+
* (`isFieldChanged`) carrying the field as it stands: show that, and
|
|
144
|
+
* write again against it by passing `ifRevision: error.current.revision`
|
|
145
|
+
* once the viewer has decided. */
|
|
146
|
+
setTopicField: (topicId: string, fieldKey: string, value: string, refTopicId?: string, options?: FieldWriteOptions) => Promise<Api.TopicFieldReceipt>;
|
|
93
147
|
/** Creates a record as the viewer. Who can see it is the viewer's
|
|
94
148
|
* choice in Alma's own access sheet, never the app's. */
|
|
95
149
|
createTopic: (name: string, topicTypeId?: string) => Promise<Api.CreatedTopicRecord>;
|
|
@@ -123,6 +177,19 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
123
177
|
/** Pass the `edit_revision` the card gave; a save made meanwhile is
|
|
124
178
|
* refused rather than overwritten. */
|
|
125
179
|
updateLesson: (lessonId: string, content: string, editRevision: string) => Promise<Api.AppLesson>;
|
|
180
|
+
/** This app's own state for its viewer: a small store for what only
|
|
181
|
+
* this person's screen of this app needs between visits, such as a
|
|
182
|
+
* filter, a collapsed column or a half-written draft. It needs no scope
|
|
183
|
+
* and nobody else reads it. If another person, a workflow or Alma needs
|
|
184
|
+
* to see or act on something, keep it in a record instead. Keys are
|
|
185
|
+
* letters, digits, `_` and `-`; values are any JSON, within a size limit
|
|
186
|
+
* a `set` past it rejects with. */
|
|
187
|
+
state: {
|
|
188
|
+
/** The value a key holds, or `undefined` when it holds nothing. */
|
|
189
|
+
get: <T = unknown>(key: string) => Promise<T | undefined>;
|
|
190
|
+
set: (key: string, value: unknown) => Promise<void>;
|
|
191
|
+
delete: (key: string) => Promise<void>;
|
|
192
|
+
};
|
|
126
193
|
listOutcomes: (page?: {
|
|
127
194
|
limit?: number;
|
|
128
195
|
offset?: number;
|
package/index.js
CHANGED
|
@@ -83,33 +83,81 @@ var FINISHED = [
|
|
|
83
83
|
"failed",
|
|
84
84
|
"cancelled"
|
|
85
85
|
];
|
|
86
|
+
class AppCallError extends Error {
|
|
87
|
+
code;
|
|
88
|
+
current;
|
|
89
|
+
constructor(message, detail = {}) {
|
|
90
|
+
super(message);
|
|
91
|
+
this.name = "AppCallError";
|
|
92
|
+
this.code = detail.code;
|
|
93
|
+
this.current = detail.current;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
function isFieldChanged(error) {
|
|
97
|
+
return error instanceof Error && error.code === "field.changed" && error.current !== undefined;
|
|
98
|
+
}
|
|
86
99
|
function createAppSdk(transport) {
|
|
100
|
+
const read = new Map;
|
|
101
|
+
const precondition = (topicId, fieldKey, options) => {
|
|
102
|
+
if (options.ifRevision !== undefined || options.ifValue !== undefined)
|
|
103
|
+
return {
|
|
104
|
+
...options.ifRevision === undefined ? {} : { if_revision: options.ifRevision },
|
|
105
|
+
...options.ifValue === undefined ? {} : { if_value: options.ifValue }
|
|
106
|
+
};
|
|
107
|
+
const fields = read.get(topicId);
|
|
108
|
+
if (!fields)
|
|
109
|
+
return {};
|
|
110
|
+
const revision = fields[fieldKey];
|
|
111
|
+
return revision === undefined ? { if_value: null } : { if_revision: revision };
|
|
112
|
+
};
|
|
87
113
|
const getExecution = (executionId) => transport.call("getExecution", {
|
|
88
114
|
params: { id: executionId }
|
|
89
115
|
});
|
|
90
116
|
return {
|
|
91
117
|
call: (operationId, request) => transport.call(operationId, request),
|
|
92
|
-
listTopics: (query = {}) =>
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
118
|
+
listTopics: async (query = {}) => {
|
|
119
|
+
const page = await transport.call("listTopics", {
|
|
120
|
+
query: {
|
|
121
|
+
type: query.type,
|
|
122
|
+
filter: query.filter,
|
|
123
|
+
sort: query.sort,
|
|
124
|
+
cursor: query.cursor,
|
|
125
|
+
limit: query.limit
|
|
126
|
+
}
|
|
127
|
+
});
|
|
128
|
+
for (const topic of page.data)
|
|
129
|
+
if (topic.revisions)
|
|
130
|
+
read.set(topic.id, { ...topic.revisions });
|
|
131
|
+
return page;
|
|
132
|
+
},
|
|
133
|
+
getTopicRecord: async (topicId) => {
|
|
134
|
+
const record = await transport.call("getTopicRecord", { params: { id: topicId } });
|
|
135
|
+
if (record.revisions)
|
|
136
|
+
read.set(topicId, { ...record.revisions });
|
|
137
|
+
return record;
|
|
138
|
+
},
|
|
104
139
|
getTopicFactDiscussion: (topicId, factId) => transport.call("getTopicFactDiscussion", { params: { id: topicId, factId } }),
|
|
140
|
+
getTopicFieldHistory: (topicId, fieldKey) => transport.call("getTopicFieldHistory", { params: { id: topicId, key: fieldKey } }),
|
|
105
141
|
downloadTopicFactAttachment: (topicId, factId, turn, attachmentId) => transport.call("downloadTopicFactAttachment", {
|
|
106
142
|
params: { id: topicId, factId, attachmentId },
|
|
107
143
|
query: { turn_kind: turn.kind, turn_id: turn.id }
|
|
108
144
|
}),
|
|
109
|
-
setTopicField: (topicId, fieldKey, value, refTopicId) =>
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
145
|
+
setTopicField: async (topicId, fieldKey, value, refTopicId, options = {}) => {
|
|
146
|
+
const receipt = await transport.call("setTopicField", {
|
|
147
|
+
params: { id: topicId, key: fieldKey },
|
|
148
|
+
body: {
|
|
149
|
+
value,
|
|
150
|
+
...refTopicId ? { ref_topic_id: refTopicId } : {},
|
|
151
|
+
...precondition(topicId, fieldKey, options)
|
|
152
|
+
},
|
|
153
|
+
...options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}
|
|
154
|
+
});
|
|
155
|
+
const revision = receipt.current_revision ?? receipt.revision;
|
|
156
|
+
const fields = read.get(topicId);
|
|
157
|
+
if (fields && revision)
|
|
158
|
+
fields[fieldKey] = revision;
|
|
159
|
+
return receipt;
|
|
160
|
+
},
|
|
113
161
|
createTopic: (name, topicTypeId) => transport.call("createTopic", {
|
|
114
162
|
body: { name, ...topicTypeId ? { topic_type_id: topicTypeId } : {} }
|
|
115
163
|
}),
|
|
@@ -156,6 +204,21 @@ function createAppSdk(transport) {
|
|
|
156
204
|
params: { id: lessonId },
|
|
157
205
|
body: { content, expected_revision: editRevision }
|
|
158
206
|
}),
|
|
207
|
+
state: {
|
|
208
|
+
get: async (key) => {
|
|
209
|
+
const entry = await transport.call("getAppState", { params: { key } });
|
|
210
|
+
return entry.exists ? entry.value : undefined;
|
|
211
|
+
},
|
|
212
|
+
set: async (key, value) => {
|
|
213
|
+
await transport.call("setAppState", {
|
|
214
|
+
params: { key },
|
|
215
|
+
body: { value }
|
|
216
|
+
});
|
|
217
|
+
},
|
|
218
|
+
delete: async (key) => {
|
|
219
|
+
await transport.call("deleteAppState", { params: { key } });
|
|
220
|
+
}
|
|
221
|
+
},
|
|
159
222
|
listOutcomes: (page = {}) => transport.call("listOutcomes", {
|
|
160
223
|
query: { limit: page.limit, offset: page.offset }
|
|
161
224
|
}),
|
|
@@ -177,7 +240,12 @@ function hostTransport() {
|
|
|
177
240
|
clearTimeout(call.timer);
|
|
178
241
|
pending.delete(message["id"]);
|
|
179
242
|
if (typeof message["error"] === "string")
|
|
180
|
-
call.reject(new
|
|
243
|
+
call.reject(new AppCallError(message["error"], {
|
|
244
|
+
...typeof message["code"] === "string" ? { code: message["code"] } : {},
|
|
245
|
+
...typeof message["current"] === "object" && message["current"] !== null ? {
|
|
246
|
+
current: message["current"]
|
|
247
|
+
} : {}
|
|
248
|
+
}));
|
|
181
249
|
else if (message["meta"] !== undefined)
|
|
182
250
|
call.resolve({ data: message["data"], meta: message["meta"] });
|
|
183
251
|
else
|
|
@@ -205,14 +273,17 @@ function hostTransport() {
|
|
|
205
273
|
operation: operationId,
|
|
206
274
|
params: request.params ?? {},
|
|
207
275
|
query,
|
|
208
|
-
...request.body ? { body: request.body } : {}
|
|
276
|
+
...request.body ? { body: request.body } : {},
|
|
277
|
+
...request.idempotencyKey ? { idempotency_key: request.idempotencyKey } : {}
|
|
209
278
|
});
|
|
210
279
|
})
|
|
211
280
|
};
|
|
212
281
|
}
|
|
213
282
|
export {
|
|
283
|
+
AppCallError,
|
|
214
284
|
applicationPath,
|
|
215
285
|
createAppSdk,
|
|
216
286
|
hostNavigation,
|
|
217
|
-
hostTransport
|
|
287
|
+
hostTransport,
|
|
288
|
+
isFieldChanged
|
|
218
289
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@almateam/app-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Types, host bridge and the alma-app dev command for apps that run in Alma. Alma builds every app with its own current copy of the SDK; install this for the types and the command.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"homepage": "https://docs.alma.team/developers/apps",
|