@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 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.10.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 { mkdir as mkdir2, rm, writeFile as writeFile3 } from "fs/promises";
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 readFile4, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
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 join5 } from "node:path";
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 = join5(homedir(), ".config", "alma", "app-cli.json");
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 readFile4(STORE, "utf8").then((text) => JSON.parse(text)).catch(() => ({}));
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 readFile4(STORE, "utf8").then((text) => JSON.parse(text)).catch(() => ({}));
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) : join6(directory, DEFAULT_SITE_FILES_FOLDER2);
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);
@@ -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. Nobody is asked: it starts
543
- * 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
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: (workflowId: string, run?: {
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
- 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?: {
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
- const response = await send(`${base}/_alma/results/${encodeURIComponent(token)}`, { cache: "no-store" });
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: (workflowId, run = {}, options = {}) => transport.call("runWorkflow", {
1399
- params: { id: workflowId },
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 (workflowId, run = {}) => await transport.call("listWorkflowExecutions", {
1408
- params: { id: workflowId },
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.10.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 `GET /_alma/results/:token`. What
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