@almateam/app-sdk 0.10.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 +92 -8
- package/cli.js +8 -305
- package/generated/apiTypes.d.ts +31 -0
- package/index.d.ts +36 -6
- package/index.js +22 -5
- package/package.json +1 -1
- package/siteRuntime.d.ts +2 -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.11.0
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
Alma builds an app's source with its own current copy of the SDK, whatever
|
|
@@ -356,6 +356,64 @@ const done = await alma.waitForExecution(run.id, {
|
|
|
356
356
|
});
|
|
357
357
|
```
|
|
358
358
|
|
|
359
|
+
### A workflow the app ships, started by its key
|
|
360
|
+
|
|
361
|
+
A workflow the app ships with (`workflows: [{ key, definition }]`, its
|
|
362
|
+
definition at `workflows/<key>.json` in the source) has no id until a version
|
|
363
|
+
creates it, and a copy of the app gets its own. To start it from the app's
|
|
364
|
+
pages, mark its entry `"startable": true` and declare the `workflows:run`
|
|
365
|
+
scope: the owners' share card then says "It starts when a member using the
|
|
366
|
+
app starts it from the app", and a version adding `startable` is a wider one.
|
|
367
|
+
Start it, and find its runs, by its key; `listWorkflows()` gives each one's
|
|
368
|
+
`key`. Only a key the version in use ships as startable starts anything: the
|
|
369
|
+
shared app the keys its shared version ships, a draft the keys the draft
|
|
370
|
+
ships, and any other key rejects as not found.
|
|
371
|
+
|
|
372
|
+
```json
|
|
373
|
+
{
|
|
374
|
+
"scopes": ["topics:read", "workflows:run", "workflows:read"],
|
|
375
|
+
"workflows": [
|
|
376
|
+
{ "key": "invite", "definition": "workflows/invite.json", "startable": true }
|
|
377
|
+
]
|
|
378
|
+
}
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
```ts
|
|
382
|
+
const run = await alma.runWorkflow(
|
|
383
|
+
{ key: "invite" },
|
|
384
|
+
{ input: { email, name } }
|
|
385
|
+
);
|
|
386
|
+
const runs = await alma.listRuns({ key: "invite" });
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
A step of a shipped workflow can act from the account of whoever starts the
|
|
390
|
+
run, such as the viewer's own Gmail, by naming its grant's key in `accounts`
|
|
391
|
+
with the value `"requester"` (the only value: any other account is set on the
|
|
392
|
+
workflow by hand). The key must be a named tool's, never a whole
|
|
393
|
+
integration's (`gmail:write` is refused):
|
|
394
|
+
|
|
395
|
+
```json
|
|
396
|
+
{
|
|
397
|
+
"id": "s1",
|
|
398
|
+
"name": "Send the invitation",
|
|
399
|
+
"tool_config": {
|
|
400
|
+
"alma_gmail_send_email": { "recipients": { "kind": "anyone" } }
|
|
401
|
+
},
|
|
402
|
+
"accounts": { "alma_gmail_send_email": "requester" }
|
|
403
|
+
}
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
Such a grant asks the person who started the run before each call: leave its
|
|
407
|
+
`approval` out or write `"actor"` (the account's owner); any other approval is
|
|
408
|
+
refused. Their card shows the call's input (an email's recipients, subject
|
|
409
|
+
and body) and offers the standing choices the gate would honour for them. The
|
|
410
|
+
viewer must have connected that integration themselves, or the run
|
|
411
|
+
fails before it starts work, saying it needs the connection. A run nobody
|
|
412
|
+
started (an event, a schedule, a visitor) has nobody to act as, so its call is
|
|
413
|
+
refused. Adding or changing `accounts` is a wider version an owner approves:
|
|
414
|
+
the card reads "Its steps may send email to anyone from the Gmail of whoever
|
|
415
|
+
starts it, each time after they approve."
|
|
416
|
+
|
|
359
417
|
An attachment download returns only a receipt (`attachment_id`, `filename`,
|
|
360
418
|
`status`): the host fetches the file itself, and neither its URL nor the session
|
|
361
419
|
token reaches the app.
|
|
@@ -539,6 +597,39 @@ npx alma-app push ./app --files ./_site-files --org <organization id>
|
|
|
539
597
|
Publishing a version follows the workspace's approval level for sharing apps;
|
|
540
598
|
going public counts as widening who sees it.
|
|
541
599
|
|
|
600
|
+
### Sharing one record by private link
|
|
601
|
+
|
|
602
|
+
A member can hand one of the app's own records to someone outside Alma, who
|
|
603
|
+
reads it on the app's website without signing in. The app declares the
|
|
604
|
+
`records:share` scope (the share card says "People using this app can share
|
|
605
|
+
one of its records by private link"), and the record's type is one `public`
|
|
606
|
+
reads by its private link (`"read": "own"`), whose `fields` are all the link
|
|
607
|
+
shows. Inside Alma:
|
|
608
|
+
|
|
609
|
+
```ts
|
|
610
|
+
const { url } = await alma.issueRecordLink(snapshot.id, { path: "/report" });
|
|
611
|
+
showCopyableLink(url); // https://<address>/report#<token>
|
|
612
|
+
await alma.revokeRecordLink(snapshot.id); // the link stops working at once
|
|
613
|
+
```
|
|
614
|
+
|
|
615
|
+
`path` is one of the app's public pages; that page reads the record with
|
|
616
|
+
`alma.ownEntry()`, as a visitor's page reads their own entry. The member must
|
|
617
|
+
be able to edit the record, and it must have been made in the app they are
|
|
618
|
+
using: a link made in their draft opens only the draft's private preview.
|
|
619
|
+
Issuing again replaces the link. The `url` is for the member alone: show it so
|
|
620
|
+
they can copy or send it, and never keep it in a record, app state or anything
|
|
621
|
+
a workflow reads. It rejects with `link.no_address` (the app is not on the
|
|
622
|
+
web), `link.not_public`, `link.not_a_page`, `link.visitor_entry` (a visitor's
|
|
623
|
+
own entry already has their link), `link.cannot_edit` or `link.rate_limited` (past 30 links an hour), and with
|
|
624
|
+
`site.no_viewer` at a published address.
|
|
625
|
+
|
|
626
|
+
A link shows only values a person wrote. A value a workflow worked out from
|
|
627
|
+
other records (a report over many entries) is never shown on the web. To share
|
|
628
|
+
such a result, publish a snapshot: on the member's own action, the app writes
|
|
629
|
+
the content into a record of the linked type as the member (`createTopic`,
|
|
630
|
+
`setTopicField`), then issues the link to that record. When the result
|
|
631
|
+
changes, write the snapshot again and issue a new link.
|
|
632
|
+
|
|
542
633
|
## Developing an app
|
|
543
634
|
|
|
544
635
|
The package carries the `alma-app` command, which runs under Node.
|
|
@@ -552,13 +643,6 @@ draft moves to it. `npx alma-app push` pushes once. Without `--app` the first
|
|
|
552
643
|
push starts a new app; a member of several workspaces names one with
|
|
553
644
|
`--org <organization id>`.
|
|
554
645
|
|
|
555
|
-
An app written as one page (`index.html` loading its own script) becomes an
|
|
556
|
-
app with screens with `npx alma-app convert [folder]`: the page's body and
|
|
557
|
-
scripts become the one members' route, on Alma's look as before, and the
|
|
558
|
-
manifest names `screens.entry`. An inline or outside script, or a head element
|
|
559
|
-
other than the title and the page's own stylesheets, is not carried over:
|
|
560
|
-
the command names each and changes nothing.
|
|
561
|
-
|
|
562
646
|
While you have your own app open, what it logs (`console`) and every error it
|
|
563
647
|
does not catch show in its Manage sheet, under Logs, beside how the workflows it
|
|
564
648
|
starts last ran. Only your own sessions are heard: what an app logs can carry
|
package/cli.js
CHANGED
|
@@ -2,245 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
// src/cli/main.ts
|
|
4
4
|
import { existsSync as existsSync2 } from "fs";
|
|
5
|
-
import {
|
|
6
|
-
import { dirname as dirname2, join as join6, resolve } from "path";
|
|
5
|
+
import { join as join5, resolve } from "path";
|
|
7
6
|
import { parseArgs } from "util";
|
|
8
7
|
|
|
9
|
-
// src/cli/convert.ts
|
|
10
|
-
class ConversionRefusal extends Error {
|
|
11
|
-
constructor(message) {
|
|
12
|
-
super(message);
|
|
13
|
-
this.name = "ConversionRefusal";
|
|
14
|
-
}
|
|
15
|
-
}
|
|
16
|
-
var SCRIPT_EXTENSIONS = ["ts", "tsx", "js", "jsx", "mjs"];
|
|
17
|
-
function freeModule(source, stems) {
|
|
18
|
-
const stem = stems.find((candidate) => SCRIPT_EXTENSIONS.every((extension) => !(`${candidate}.${extension}` in source)));
|
|
19
|
-
if (stem === undefined)
|
|
20
|
-
throw new ConversionRefusal(`The app already has ${stems.join(", ")}; rename one before converting.`);
|
|
21
|
-
return `${stem}.tsx`;
|
|
22
|
-
}
|
|
23
|
-
function siteEntryOf(manifest) {
|
|
24
|
-
const site = manifest["site"];
|
|
25
|
-
if (typeof site !== "object" || site === null)
|
|
26
|
-
return null;
|
|
27
|
-
const entry = site["entry"];
|
|
28
|
-
return typeof entry === "string" ? entry : null;
|
|
29
|
-
}
|
|
30
|
-
var ATTRIBUTE = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
|
|
31
|
-
function attributesOf(text) {
|
|
32
|
-
const attributes = {};
|
|
33
|
-
for (const [, name, double, single, bare] of text.matchAll(ATTRIBUTE))
|
|
34
|
-
if (name)
|
|
35
|
-
attributes[name.toLowerCase()] = double ?? single ?? bare ?? "";
|
|
36
|
-
return attributes;
|
|
37
|
-
}
|
|
38
|
-
function tagAttributes(html, tag) {
|
|
39
|
-
const found = new RegExp(`<${tag}\\b([^>]*)>`, "i").exec(html);
|
|
40
|
-
return found ? attributesOf(found[1] ?? "") : {};
|
|
41
|
-
}
|
|
42
|
-
function between(html, tag) {
|
|
43
|
-
const found = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)</${tag}\\s*>`, "i").exec(html);
|
|
44
|
-
return found ? found[1] ?? "" : null;
|
|
45
|
-
}
|
|
46
|
-
var SCRIPT = /<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi;
|
|
47
|
-
function sourcePath(reference) {
|
|
48
|
-
if (/^[a-z][a-z0-9+.-]*:|^\/\//i.test(reference))
|
|
49
|
-
return null;
|
|
50
|
-
const path = reference.replace(/^\.?\//, "");
|
|
51
|
-
if (path === "" || path.split("/").some((part) => part === ".."))
|
|
52
|
-
return null;
|
|
53
|
-
return path;
|
|
54
|
-
}
|
|
55
|
-
function scriptSource(path, source) {
|
|
56
|
-
if (path === null)
|
|
57
|
-
return null;
|
|
58
|
-
if (path in source)
|
|
59
|
-
return path;
|
|
60
|
-
const stem = path.replace(/\.(?:js|mjs)$/, "");
|
|
61
|
-
if (stem === path)
|
|
62
|
-
return null;
|
|
63
|
-
return [`${stem}.ts`, `${stem}.tsx`].find((each) => (each in source)) ?? null;
|
|
64
|
-
}
|
|
65
|
-
function importFromSrc(path) {
|
|
66
|
-
const parts = path.split("/");
|
|
67
|
-
const relative = parts[0] === "src" ? `./${parts.slice(1).join("/")}` : `../${path}`;
|
|
68
|
-
return relative.replace(/\.(tsx|ts|jsx|js|mjs)$/, "");
|
|
69
|
-
}
|
|
70
|
-
function readDocument(html, source) {
|
|
71
|
-
const problems = [];
|
|
72
|
-
const scripts = [];
|
|
73
|
-
const sheets = [];
|
|
74
|
-
const head = between(html, "head") ?? "";
|
|
75
|
-
const bodyText = between(html, "body");
|
|
76
|
-
for (const [, attributeText = "", inline = ""] of html.matchAll(SCRIPT)) {
|
|
77
|
-
const attributes = attributesOf(attributeText);
|
|
78
|
-
const src = attributes["src"];
|
|
79
|
-
if (src === undefined) {
|
|
80
|
-
if (inline.trim() !== "")
|
|
81
|
-
problems.push("index.html runs an inline script. Move it into a module the page loads.");
|
|
82
|
-
continue;
|
|
83
|
-
}
|
|
84
|
-
const path = scriptSource(sourcePath(src), source);
|
|
85
|
-
if (path === null)
|
|
86
|
-
problems.push(`index.html loads ${src}, which is not a file of the app's source.`);
|
|
87
|
-
else if (attributes["type"] !== "module")
|
|
88
|
-
problems.push(`index.html loads ${src} as a classic script; only a module script carries over.`);
|
|
89
|
-
else
|
|
90
|
-
scripts.push(path);
|
|
91
|
-
}
|
|
92
|
-
const headRest = head.replace(/<title\b[^>]*>[\s\S]*?<\/title\s*>/gi, "").replace(SCRIPT, "").replace(/<meta\b[^>]*>/gi, "").replace(/<!--[\s\S]*?-->/g, "");
|
|
93
|
-
for (const [element, attributeText = ""] of headRest.matchAll(/<link\b([^>]*)>/gi)) {
|
|
94
|
-
const attributes = attributesOf(attributeText);
|
|
95
|
-
const path = attributes["href"] === undefined ? null : sourcePath(attributes["href"]);
|
|
96
|
-
if (/\bstylesheet\b/i.test(attributes["rel"] ?? "") && path !== null && path in source)
|
|
97
|
-
sheets.push(path);
|
|
98
|
-
else
|
|
99
|
-
problems.push(`index.html's head has ${element.trim()}, which has no place in an app's screens.`);
|
|
100
|
-
}
|
|
101
|
-
const leftover = headRest.replace(/<link\b[^>]*>/gi, "").trim();
|
|
102
|
-
if (leftover !== "")
|
|
103
|
-
problems.push(`index.html's head has ${leftover.slice(0, 60)}, which has no place in an app's screens. Move styles into a stylesheet the page imports.`);
|
|
104
|
-
if (scripts.length === 0)
|
|
105
|
-
problems.push('index.html loads no module script (<script type="module" src="/src/main.tsx">).');
|
|
106
|
-
const markup = (bodyText ?? html.replace(/<!doctype[^>]*>/i, "")).replace(SCRIPT, "").replace(/<!--[\s\S]*?-->/g, "").trim();
|
|
107
|
-
return {
|
|
108
|
-
problems,
|
|
109
|
-
scripts,
|
|
110
|
-
sheets,
|
|
111
|
-
markup,
|
|
112
|
-
htmlAttributes: tagAttributes(html, "html"),
|
|
113
|
-
bodyAttributes: tagAttributes(html, "body")
|
|
114
|
-
};
|
|
115
|
-
}
|
|
116
|
-
function pageModule(read) {
|
|
117
|
-
const htmlAttributes = { ...read.htmlAttributes };
|
|
118
|
-
delete htmlAttributes["lang"];
|
|
119
|
-
return `/* The app's one page, as its index.html drew it: the page's body, then
|
|
120
|
-
its scripts, run once, after the body is in the document. */
|
|
121
|
-
import { useLayoutEffect, useRef } from "react";
|
|
122
|
-
|
|
123
|
-
const BODY = ${JSON.stringify(read.markup)};
|
|
124
|
-
const HTML_ATTRIBUTES: Record<string, string> = ${JSON.stringify(htmlAttributes)};
|
|
125
|
-
const BODY_ATTRIBUTES: Record<string, string> = ${JSON.stringify(read.bodyAttributes)};
|
|
126
|
-
|
|
127
|
-
// One body for the frame's life, so the page's own scripts, which run once,
|
|
128
|
-
// keep the elements they drew whichever screen shows it.
|
|
129
|
-
let page: HTMLDivElement | null = null;
|
|
130
|
-
|
|
131
|
-
export default function SinglePage() {
|
|
132
|
-
const holder = useRef<HTMLDivElement>(null);
|
|
133
|
-
useLayoutEffect(() => {
|
|
134
|
-
if (page) {
|
|
135
|
-
holder.current?.append(page);
|
|
136
|
-
return;
|
|
137
|
-
}
|
|
138
|
-
page = document.createElement("div");
|
|
139
|
-
page.style.display = "contents";
|
|
140
|
-
page.innerHTML = BODY;
|
|
141
|
-
holder.current?.append(page);
|
|
142
|
-
for (const [name, value] of Object.entries(HTML_ATTRIBUTES))
|
|
143
|
-
document.documentElement.setAttribute(name, value);
|
|
144
|
-
for (const [name, value] of Object.entries(BODY_ATTRIBUTES))
|
|
145
|
-
document.body.setAttribute(name, value);
|
|
146
|
-
${read.scripts.map((path) => ` void import(${JSON.stringify(importFromSrc(path))});`).join(`
|
|
147
|
-
`)}
|
|
148
|
-
}, []);
|
|
149
|
-
return <div ref={holder} style={{ display: "contents" }} />;
|
|
150
|
-
}
|
|
151
|
-
`;
|
|
152
|
-
}
|
|
153
|
-
function appModule(read, siteEntry, pagePath) {
|
|
154
|
-
const sheets = read.sheets.map((path) => `import ${JSON.stringify(importFromSrc(path))};`);
|
|
155
|
-
const pageImport = `() => import(${JSON.stringify(importFromSrc(pagePath))})`;
|
|
156
|
-
const page = `{ path: "/", audience: "members", component: ${pageImport} }`;
|
|
157
|
-
const lines = [
|
|
158
|
-
"// Alma's look, which every app stood on before it chose for itself.",
|
|
159
|
-
'import "@alma/app-ui/base.css";',
|
|
160
|
-
...sheets,
|
|
161
|
-
'import { defineApp } from "@alma/app-sdk";'
|
|
162
|
-
];
|
|
163
|
-
if (siteEntry === null)
|
|
164
|
-
return [
|
|
165
|
-
...lines,
|
|
166
|
-
"",
|
|
167
|
-
"export default defineApp({",
|
|
168
|
-
` routes: [${page}],`,
|
|
169
|
-
` notFound: { component: ${pageImport} },`,
|
|
170
|
-
"});",
|
|
171
|
-
""
|
|
172
|
-
].join(`
|
|
173
|
-
`);
|
|
174
|
-
return [
|
|
175
|
-
...lines,
|
|
176
|
-
`import site from ${JSON.stringify(importFromSrc(siteEntry))};`,
|
|
177
|
-
"",
|
|
178
|
-
"export default defineApp({",
|
|
179
|
-
" ...site,",
|
|
180
|
-
" routes: [",
|
|
181
|
-
` ${page},`,
|
|
182
|
-
' ...site.routes.map((route) => ({ ...route, audience: route.audience ?? ("public" as const) })),',
|
|
183
|
-
" ],",
|
|
184
|
-
"});",
|
|
185
|
-
""
|
|
186
|
-
].join(`
|
|
187
|
-
`);
|
|
188
|
-
}
|
|
189
|
-
var RENAMES = [
|
|
190
|
-
[/(["'])@alma\/app-ui\/site\/render\1/g, "$1@alma/app-ui/render$1"],
|
|
191
|
-
[/(["'])@alma\/app-ui\/site\1/g, "$1@alma/app-ui$1"],
|
|
192
|
-
[/\bdefineSite\b/g, "defineApp"],
|
|
193
|
-
[/\bdefinePage\b/g, "defineRoute"],
|
|
194
|
-
[/\bstartSite\b/g, "startApp"],
|
|
195
|
-
[/\buseSite\b/g, "useApp"],
|
|
196
|
-
[/\bprerenderSite\b/g, "prerenderApp"],
|
|
197
|
-
[/\bsiteDefinitionProblems\b/g, "appDefinitionProblems"],
|
|
198
|
-
[/\bSiteDefinition\b/g, "AppDefinition"],
|
|
199
|
-
[/\bSitePage\b/g, "AppRoute"],
|
|
200
|
-
[/\bSiteLayout\b/g, "AppLayout"],
|
|
201
|
-
[/\bSiteMeta\b/g, "AppMeta"],
|
|
202
|
-
[/\bSiteParams\b/g, "RouteParams"],
|
|
203
|
-
[/\bPageMetaContext\b/g, "RouteMetaContext"],
|
|
204
|
-
[/\bPageMeta\b/g, "RouteMeta"],
|
|
205
|
-
[/\bPageProps\b/g, "RouteProps"],
|
|
206
|
-
[/\bPageComponent\b/g, "RouteComponent"],
|
|
207
|
-
[/\bSiteInfo\b/g, "AppInfo"],
|
|
208
|
-
[/\bNOT_FOUND_PAGE_ID\b/g, "NOT_FOUND_ROUTE_ID"]
|
|
209
|
-
];
|
|
210
|
-
var SCRIPT_FILE = /\.(?:tsx|ts|jsx|js|mjs)$/;
|
|
211
|
-
function convertSinglePageApp(app) {
|
|
212
|
-
const html = app.source["index.html"];
|
|
213
|
-
if (html === undefined)
|
|
214
|
-
throw new ConversionRefusal("The app has no index.html, so it is not in the single-page shape.");
|
|
215
|
-
const entry = freeModule(app.source, ["src/app", "src/screens"]);
|
|
216
|
-
const pagePath = freeModule(app.source, ["src/singlePage", "src/onePage"]);
|
|
217
|
-
const read = readDocument(html, app.source);
|
|
218
|
-
if (read.problems.length > 0)
|
|
219
|
-
throw new ConversionRefusal(read.problems.join(`
|
|
220
|
-
`));
|
|
221
|
-
const siteEntry = siteEntryOf(app.manifest);
|
|
222
|
-
if (siteEntry !== null && !(siteEntry in app.source))
|
|
223
|
-
throw new ConversionRefusal(`The manifest's site.entry is ${siteEntry}, which is not in the source.`);
|
|
224
|
-
const source = {};
|
|
225
|
-
for (const [path, text] of Object.entries(app.source)) {
|
|
226
|
-
if (path === "index.html")
|
|
227
|
-
continue;
|
|
228
|
-
let renamed = text;
|
|
229
|
-
if (SCRIPT_FILE.test(path))
|
|
230
|
-
for (const [pattern, name] of RENAMES)
|
|
231
|
-
renamed = renamed.replace(pattern, name);
|
|
232
|
-
if (path === siteEntry)
|
|
233
|
-
renamed = renamed.replace(/\bpages(\s*:)/, "routes$1");
|
|
234
|
-
source[path] = renamed;
|
|
235
|
-
}
|
|
236
|
-
source[entry] = appModule(read, siteEntry, pagePath);
|
|
237
|
-
source[pagePath] = pageModule(read);
|
|
238
|
-
const manifest = { ...app.manifest };
|
|
239
|
-
delete manifest["entry"];
|
|
240
|
-
delete manifest["site"];
|
|
241
|
-
return { manifest: { ...manifest, screens: { entry } }, source };
|
|
242
|
-
}
|
|
243
|
-
|
|
244
8
|
// src/cli/dev.ts
|
|
245
9
|
import { existsSync, watch } from "node:fs";
|
|
246
10
|
import { join as join3 } from "node:path";
|
|
@@ -706,45 +470,6 @@ async function runDev(options) {
|
|
|
706
470
|
}
|
|
707
471
|
}
|
|
708
472
|
|
|
709
|
-
// src/cli/project.ts
|
|
710
|
-
import { readdir as readdir3, readFile as readFile3 } from "node:fs/promises";
|
|
711
|
-
import { join as join4, relative as relative2, sep as sep2 } from "node:path";
|
|
712
|
-
var SOURCE_FILE2 = /\.(?:tsx|ts|jsx|js|mjs|css|html|svg|json|md|txt)$/;
|
|
713
|
-
var LOCKFILES2 = new Set([
|
|
714
|
-
"package-lock.json",
|
|
715
|
-
"npm-shrinkwrap.json",
|
|
716
|
-
"bun.lock",
|
|
717
|
-
"bun.lockb",
|
|
718
|
-
"yarn.lock",
|
|
719
|
-
"pnpm-lock.yaml"
|
|
720
|
-
]);
|
|
721
|
-
var SKIPPED_DIRECTORIES2 = new Set(["node_modules", "dist", "build"]);
|
|
722
|
-
function isProjectPath2(path) {
|
|
723
|
-
const parts = path.split(/[\\/]/);
|
|
724
|
-
return SOURCE_FILE2.test(path) && !LOCKFILES2.has(parts.at(-1) ?? "") && parts.every((part) => !part.startsWith(".") && !SKIPPED_DIRECTORIES2.has(part));
|
|
725
|
-
}
|
|
726
|
-
async function readProject2(directory) {
|
|
727
|
-
const manifestText = await readFile3(join4(directory, "manifest.json"), "utf8").catch(() => {
|
|
728
|
-
throw new Error(`No manifest.json in ${directory}. An app's folder holds its manifest beside its source.`);
|
|
729
|
-
});
|
|
730
|
-
const manifest = JSON.parse(manifestText);
|
|
731
|
-
if (typeof manifest !== "object" || manifest === null)
|
|
732
|
-
throw new Error("manifest.json is not an object");
|
|
733
|
-
const source = {};
|
|
734
|
-
for (const entry of await readdir3(directory, {
|
|
735
|
-
recursive: true,
|
|
736
|
-
withFileTypes: true
|
|
737
|
-
})) {
|
|
738
|
-
if (!entry.isFile())
|
|
739
|
-
continue;
|
|
740
|
-
const path = relative2(directory, join4(entry.parentPath, entry.name)).split(sep2).join("/");
|
|
741
|
-
if (path === "manifest.json" || !isProjectPath2(path))
|
|
742
|
-
continue;
|
|
743
|
-
source[path] = await readFile3(join4(directory, path), "utf8");
|
|
744
|
-
}
|
|
745
|
-
return { manifest, source };
|
|
746
|
-
}
|
|
747
|
-
|
|
748
473
|
// src/cli/siteFiles.ts
|
|
749
474
|
var DEFAULT_SITE_FILES_FOLDER2 = "_site-files";
|
|
750
475
|
var SITE_FILE_LIMITS2 = {
|
|
@@ -785,23 +510,23 @@ var LOOPBACK_HOSTS2 = new Set(["127.0.0.1", "localhost", "[::1]"]);
|
|
|
785
510
|
|
|
786
511
|
// src/cli/signIn.ts
|
|
787
512
|
import { spawn } from "node:child_process";
|
|
788
|
-
import { chmod, mkdir, readFile as
|
|
513
|
+
import { chmod, mkdir, readFile as readFile3, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
|
|
789
514
|
import { createServer } from "node:http";
|
|
790
515
|
import { homedir } from "node:os";
|
|
791
|
-
import { dirname, join as
|
|
516
|
+
import { dirname, join as join4 } from "node:path";
|
|
792
517
|
import {
|
|
793
518
|
auth
|
|
794
519
|
} from "@modelcontextprotocol/sdk/client/auth.js";
|
|
795
|
-
var STORE =
|
|
520
|
+
var STORE = join4(homedir(), ".config", "alma", "app-cli.json");
|
|
796
521
|
var CALLBACK_PORT = 53682;
|
|
797
522
|
var CALLBACK_TIMEOUT_MS = 5 * 60000;
|
|
798
523
|
var SCOPE = "openid email profile offline_access";
|
|
799
524
|
async function load(server) {
|
|
800
|
-
const all = await
|
|
525
|
+
const all = await readFile3(STORE, "utf8").then((text) => JSON.parse(text)).catch(() => ({}));
|
|
801
526
|
return all[server] ?? {};
|
|
802
527
|
}
|
|
803
528
|
async function save(server, stored) {
|
|
804
|
-
const all = await
|
|
529
|
+
const all = await readFile3(STORE, "utf8").then((text) => JSON.parse(text)).catch(() => ({}));
|
|
805
530
|
all[server] = stored;
|
|
806
531
|
const folder = dirname(STORE);
|
|
807
532
|
await mkdir(folder, { recursive: true, mode: 448 });
|
|
@@ -922,14 +647,11 @@ function signedInAuthor(server) {
|
|
|
922
647
|
// src/cli/main.ts
|
|
923
648
|
var USAGE = `Usage: alma-app dev|push [folder] [--app <app id>] [--org <organization id>]
|
|
924
649
|
[--files <folder>] [--server <MCP url>]
|
|
925
|
-
alma-app convert [folder]
|
|
926
650
|
|
|
927
651
|
Pushes the app in [folder] (default: here) to Alma as a new draft version,
|
|
928
652
|
signed in to Alma in your browser: dev now and on every save, push once.
|
|
929
653
|
A web site's pictures, fonts, PDFs and audio are uploaded from --files
|
|
930
|
-
(default: ${DEFAULT_SITE_FILES_FOLDER2} in the folder) and listed in site-files.json first
|
|
931
|
-
convert rewrites an app whose page is index.html as an app with screens
|
|
932
|
-
(src/app.tsx), showing members what it showed before.`;
|
|
654
|
+
(default: ${DEFAULT_SITE_FILES_FOLDER2} in the folder) and listed in site-files.json first.`;
|
|
933
655
|
var { values, positionals } = parseArgs({
|
|
934
656
|
args: process.argv.slice(2),
|
|
935
657
|
allowPositionals: true,
|
|
@@ -946,31 +668,12 @@ if (values.help || positionals[0] === "help") {
|
|
|
946
668
|
process.exit(0);
|
|
947
669
|
}
|
|
948
670
|
var command = positionals[0];
|
|
949
|
-
if (command === "convert") {
|
|
950
|
-
const folder = resolve(positionals[1] ?? ".");
|
|
951
|
-
try {
|
|
952
|
-
const converted = convertSinglePageApp(await readProject2(folder));
|
|
953
|
-
for (const [path, text] of Object.entries(converted.source)) {
|
|
954
|
-
await mkdir2(dirname2(join6(folder, path)), { recursive: true });
|
|
955
|
-
await writeFile3(join6(folder, path), text);
|
|
956
|
-
}
|
|
957
|
-
await rm(join6(folder, "index.html"));
|
|
958
|
-
await writeFile3(join6(folder, "manifest.json"), `${JSON.stringify(converted.manifest, null, 2)}
|
|
959
|
-
`);
|
|
960
|
-
console.info(`Converted ${folder}.`);
|
|
961
|
-
process.exit(0);
|
|
962
|
-
} catch (error) {
|
|
963
|
-
console.error(error instanceof ConversionRefusal ? `Not converted:
|
|
964
|
-
${error.message}` : error instanceof Error ? error.message : String(error));
|
|
965
|
-
process.exit(1);
|
|
966
|
-
}
|
|
967
|
-
}
|
|
968
671
|
if (command !== "dev" && command !== "push") {
|
|
969
672
|
console.error(USAGE);
|
|
970
673
|
process.exit(1);
|
|
971
674
|
}
|
|
972
675
|
var directory = resolve(positionals[1] ?? ".");
|
|
973
|
-
var filesDirectory = values.files ? resolve(values.files) :
|
|
676
|
+
var filesDirectory = values.files ? resolve(values.files) : join5(directory, DEFAULT_SITE_FILES_FOLDER2);
|
|
974
677
|
if (values.app && !isAppId2(values.app)) {
|
|
975
678
|
console.error(`--app ${values.app} is not an app id. The first push without --app prints it.`);
|
|
976
679
|
process.exit(1);
|
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
|
@@ -69,6 +69,8 @@ declare const APP_OPERATIONS: {
|
|
|
69
69
|
readonly createTopic: "change";
|
|
70
70
|
readonly deleteTopic: "change";
|
|
71
71
|
readonly restoreTopic: "change";
|
|
72
|
+
readonly issueRecordLink: "change";
|
|
73
|
+
readonly revokeRecordLink: "change";
|
|
72
74
|
readonly listTopicTypes: "read";
|
|
73
75
|
readonly getTopicRecord: "read";
|
|
74
76
|
readonly listViews: "read";
|
|
@@ -102,7 +104,8 @@ declare const APP_OPERATIONS: {
|
|
|
102
104
|
};
|
|
103
105
|
export type AppOperationId = keyof typeof APP_OPERATIONS;
|
|
104
106
|
export interface AppRequest {
|
|
105
|
-
/** 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). */
|
|
106
109
|
params?: Record<string, string>;
|
|
107
110
|
/** Only the query keys the operation declares reach the API. */
|
|
108
111
|
query?: Record<string, string | number | string[] | undefined>;
|
|
@@ -326,6 +329,12 @@ export interface AppTransport {
|
|
|
326
329
|
* Alma's frame). A transport without it has no files. */
|
|
327
330
|
fileUrl?(name: string): string | Promise<string>;
|
|
328
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
|
+
};
|
|
329
338
|
export declare function createAppSdk(transport: AppTransport): {
|
|
330
339
|
call: <T>(operationId: AppOperationId, request?: AppRequest) => Promise<T>;
|
|
331
340
|
/** The viewer's own person record (`person_id`, a record of type
|
|
@@ -536,15 +545,35 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
536
545
|
* refusal's words. So does one past its 30 days, until Alma removes it
|
|
537
546
|
* for good; then it rejects as not found. */
|
|
538
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>;
|
|
539
566
|
/** Every type, its fields and its relationships. */
|
|
540
567
|
listTopicTypes: <T = Api.TopicType[]>() => Promise<T>;
|
|
541
568
|
listWorkflows: () => Promise<Api.AppWorkflowSummary[]>;
|
|
542
|
-
/** Starts a workflow the app's manifest names
|
|
543
|
-
*
|
|
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
|
|
544
573
|
* themselves, on a record they can see, and rejects with the refusal's
|
|
545
574
|
* words otherwise. The run acts as the workflow, not as the viewer: only
|
|
546
575
|
* a step account set to whoever starts the run is the viewer's own. */
|
|
547
|
-
runWorkflow: (
|
|
576
|
+
runWorkflow: (workflow: AppWorkflowRef, run?: {
|
|
548
577
|
topicId?: string;
|
|
549
578
|
input?: Record<string, unknown>;
|
|
550
579
|
}, options?: ChangeOptions) => Promise<Api.AppRunReceipt>;
|
|
@@ -553,8 +582,9 @@ export declare function createAppSdk(transport: AppTransport): {
|
|
|
553
582
|
getExecution: (executionId: string) => Promise<Api.AppExecution>;
|
|
554
583
|
/** The newest runs of a workflow the app names that the viewer may read,
|
|
555
584
|
* on one record when `topicId` names it: how an app opened again finds
|
|
556
|
-
* the run it started, with `result` typed as `T`.
|
|
557
|
-
|
|
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?: {
|
|
558
588
|
topicId?: string;
|
|
559
589
|
}) => Promise<AppExecutionOf<T>[]>;
|
|
560
590
|
/** Polls a run with backoff until it finishes, and resolves with how it
|
package/index.js
CHANGED
|
@@ -483,7 +483,14 @@ function siteTransport(options = {}) {
|
|
|
483
483
|
return `${base}/_files/${name}`;
|
|
484
484
|
},
|
|
485
485
|
result: async (token) => {
|
|
486
|
-
|
|
486
|
+
let response = await send(`${base}/_alma/results`, {
|
|
487
|
+
method: "POST",
|
|
488
|
+
headers: { "content-type": "application/json" },
|
|
489
|
+
body: JSON.stringify({ token }),
|
|
490
|
+
cache: "no-store"
|
|
491
|
+
});
|
|
492
|
+
if ([403, 404, 405].includes(response.status))
|
|
493
|
+
response = await send(`${base}/_alma/results/${encodeURIComponent(token)}`, { cache: "no-store" });
|
|
487
494
|
if (!response.ok)
|
|
488
495
|
throw await refusal(response);
|
|
489
496
|
const answer = await response.json();
|
|
@@ -950,6 +957,7 @@ var WATCH_BROADCASTS_QUESTION = "watchBroadcasts";
|
|
|
950
957
|
var BROADCAST_MESSAGE = "alma:broadcast";
|
|
951
958
|
var BROADCAST_EVENT = /^[A-Za-z0-9_.:-]{1,128}$/;
|
|
952
959
|
var oneRequest = () => crypto.randomUUID();
|
|
960
|
+
var workflowParam = (workflow) => typeof workflow === "string" ? workflow : workflow.key;
|
|
953
961
|
var UUID2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
954
962
|
function createAppSdk(transport) {
|
|
955
963
|
const read = new Map;
|
|
@@ -1393,10 +1401,19 @@ function createAppSdk(transport) {
|
|
|
1393
1401
|
params: { id: topicId },
|
|
1394
1402
|
idempotencyKey: options.idempotencyKey ?? oneRequest()
|
|
1395
1403
|
}),
|
|
1404
|
+
issueRecordLink: (recordId, link, options = {}) => transport.call("issueRecordLink", {
|
|
1405
|
+
params: { id: recordId },
|
|
1406
|
+
body: { path: link.path },
|
|
1407
|
+
idempotencyKey: options.idempotencyKey ?? oneRequest()
|
|
1408
|
+
}),
|
|
1409
|
+
revokeRecordLink: (recordId, options = {}) => transport.call("revokeRecordLink", {
|
|
1410
|
+
params: { id: recordId },
|
|
1411
|
+
idempotencyKey: options.idempotencyKey ?? oneRequest()
|
|
1412
|
+
}),
|
|
1396
1413
|
listTopicTypes: () => transport.call("listTopicTypes"),
|
|
1397
1414
|
listWorkflows: () => transport.call("listWorkflows"),
|
|
1398
|
-
runWorkflow: (
|
|
1399
|
-
params: { id:
|
|
1415
|
+
runWorkflow: (workflow, run = {}, options = {}) => transport.call("runWorkflow", {
|
|
1416
|
+
params: { id: workflowParam(workflow) },
|
|
1400
1417
|
body: {
|
|
1401
1418
|
...run.topicId ? { topic_id: run.topicId } : {},
|
|
1402
1419
|
...run.input ? { input: run.input } : {}
|
|
@@ -1404,8 +1421,8 @@ function createAppSdk(transport) {
|
|
|
1404
1421
|
idempotencyKey: options.idempotencyKey ?? oneRequest()
|
|
1405
1422
|
}),
|
|
1406
1423
|
getExecution,
|
|
1407
|
-
listRuns: async (
|
|
1408
|
-
params: { id:
|
|
1424
|
+
listRuns: async (workflow, run = {}) => await transport.call("listWorkflowExecutions", {
|
|
1425
|
+
params: { id: workflowParam(workflow) },
|
|
1409
1426
|
query: { topic_id: run.topicId }
|
|
1410
1427
|
}),
|
|
1411
1428
|
waitForExecution: async (executionId, options = {}) => {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@almateam/app-sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.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",
|
package/siteRuntime.d.ts
CHANGED
|
@@ -87,7 +87,8 @@ export interface SiteTransportOptions {
|
|
|
87
87
|
* door: `raiseAppEvent` is `POST /_alma/events`; `createTopic` is `POST
|
|
88
88
|
* /_alma/records`, its type named by key; `listTopics` is `GET
|
|
89
89
|
* /_alma/records?type=`; `getTopicRecord` is `GET /_alma/records/:id?type=`;
|
|
90
|
-
* a result or the visitor's own entry is `
|
|
90
|
+
* a result or the visitor's own entry is `POST /_alma/results` with the
|
|
91
|
+
* token in the body. What
|
|
91
92
|
* the door shows is handed on in the shape a member's call answers with
|
|
92
93
|
* (`PUBLIC_RECORD_SHAPE`). There is no viewer or shell, and every other
|
|
93
94
|
* operation rejects with `site.no_viewer`, as does a read the door cannot
|