@almateam/app-sdk 0.9.0 → 0.10.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/cli.js CHANGED
@@ -2,9 +2,245 @@
2
2
 
3
3
  // src/cli/main.ts
4
4
  import { existsSync as existsSync2 } from "fs";
5
- import { join as join5, resolve } from "path";
5
+ import { mkdir as mkdir2, rm, writeFile as writeFile3 } from "fs/promises";
6
+ import { dirname as dirname2, join as join6, resolve } from "path";
6
7
  import { parseArgs } from "util";
7
8
 
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
+
8
244
  // src/cli/dev.ts
9
245
  import { existsSync, watch } from "node:fs";
10
246
  import { join as join3 } from "node:path";
@@ -12,7 +248,7 @@ import { join as join3 } from "node:path";
12
248
  // src/cli/project.ts
13
249
  import { readdir, readFile } from "node:fs/promises";
14
250
  import { join, relative, sep } from "node:path";
15
- var SOURCE_FILE = /\.(?:tsx|ts|jsx|js|mjs|css|html|svg|json)$/;
251
+ var SOURCE_FILE = /\.(?:tsx|ts|jsx|js|mjs|css|html|svg|json|md|txt)$/;
16
252
  var LOCKFILES = new Set([
17
253
  "package-lock.json",
18
254
  "npm-shrinkwrap.json",
@@ -28,7 +264,7 @@ function isProjectPath(path) {
28
264
  }
29
265
  async function readProject(directory) {
30
266
  const manifestText = await readFile(join(directory, "manifest.json"), "utf8").catch(() => {
31
- throw new Error(`No manifest.json in ${directory}. An app's folder holds its manifest beside index.html.`);
267
+ throw new Error(`No manifest.json in ${directory}. An app's folder holds its manifest beside its source.`);
32
268
  });
33
269
  const manifest = JSON.parse(manifestText);
34
270
  if (typeof manifest !== "object" || manifest === null)
@@ -470,6 +706,45 @@ async function runDev(options) {
470
706
  }
471
707
  }
472
708
 
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
+
473
748
  // src/cli/siteFiles.ts
474
749
  var DEFAULT_SITE_FILES_FOLDER2 = "_site-files";
475
750
  var SITE_FILE_LIMITS2 = {
@@ -510,23 +785,23 @@ var LOOPBACK_HOSTS2 = new Set(["127.0.0.1", "localhost", "[::1]"]);
510
785
 
511
786
  // src/cli/signIn.ts
512
787
  import { spawn } from "node:child_process";
513
- import { chmod, mkdir, readFile as readFile3, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
788
+ import { chmod, mkdir, readFile as readFile4, rename as rename2, writeFile as writeFile2 } from "node:fs/promises";
514
789
  import { createServer } from "node:http";
515
790
  import { homedir } from "node:os";
516
- import { dirname, join as join4 } from "node:path";
791
+ import { dirname, join as join5 } from "node:path";
517
792
  import {
518
793
  auth
519
794
  } from "@modelcontextprotocol/sdk/client/auth.js";
520
- var STORE = join4(homedir(), ".config", "alma", "app-cli.json");
795
+ var STORE = join5(homedir(), ".config", "alma", "app-cli.json");
521
796
  var CALLBACK_PORT = 53682;
522
797
  var CALLBACK_TIMEOUT_MS = 5 * 60000;
523
798
  var SCOPE = "openid email profile offline_access";
524
799
  async function load(server) {
525
- const all = await readFile3(STORE, "utf8").then((text) => JSON.parse(text)).catch(() => ({}));
800
+ const all = await readFile4(STORE, "utf8").then((text) => JSON.parse(text)).catch(() => ({}));
526
801
  return all[server] ?? {};
527
802
  }
528
803
  async function save(server, stored) {
529
- const all = await readFile3(STORE, "utf8").then((text) => JSON.parse(text)).catch(() => ({}));
804
+ const all = await readFile4(STORE, "utf8").then((text) => JSON.parse(text)).catch(() => ({}));
530
805
  all[server] = stored;
531
806
  const folder = dirname(STORE);
532
807
  await mkdir(folder, { recursive: true, mode: 448 });
@@ -647,11 +922,14 @@ function signedInAuthor(server) {
647
922
  // src/cli/main.ts
648
923
  var USAGE = `Usage: alma-app dev|push [folder] [--app <app id>] [--org <organization id>]
649
924
  [--files <folder>] [--server <MCP url>]
925
+ alma-app convert [folder]
650
926
 
651
927
  Pushes the app in [folder] (default: here) to Alma as a new draft version,
652
928
  signed in to Alma in your browser: dev now and on every save, push once.
653
929
  A web site's pictures, fonts, PDFs and audio are uploaded from --files
654
- (default: ${DEFAULT_SITE_FILES_FOLDER2} in the folder) and listed in site-files.json first.`;
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.`;
655
933
  var { values, positionals } = parseArgs({
656
934
  args: process.argv.slice(2),
657
935
  allowPositionals: true,
@@ -668,12 +946,31 @@ if (values.help || positionals[0] === "help") {
668
946
  process.exit(0);
669
947
  }
670
948
  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
+ }
671
968
  if (command !== "dev" && command !== "push") {
672
969
  console.error(USAGE);
673
970
  process.exit(1);
674
971
  }
675
972
  var directory = resolve(positionals[1] ?? ".");
676
- var filesDirectory = values.files ? resolve(values.files) : join5(directory, DEFAULT_SITE_FILES_FOLDER2);
973
+ var filesDirectory = values.files ? resolve(values.files) : join6(directory, DEFAULT_SITE_FILES_FOLDER2);
677
974
  if (values.app && !isAppId2(values.app)) {
678
975
  console.error(`--app ${values.app} is not an app id. The first push without --app prints it.`);
679
976
  process.exit(1);
package/files.d.ts ADDED
@@ -0,0 +1,25 @@
1
+ /** The bridge question an app in Alma's frame asks for one of its own
2
+ * files, as an `alma:operation` (`{ type, id, operation, params, query,
3
+ * body: { name } }`). The host answers `alma:result` with the same `id`
4
+ * and `data: { name, media_type, bytes }`, `bytes` an `ArrayBuffer` of
5
+ * the whole file; or with `error` and a `code` (`AppFileRefusalCode`).
6
+ * Only a file of the app version the frame is running is ever answered. */
7
+ export declare const APP_FILE_QUESTION = "getAppFile";
8
+ /** What a host refuses an app file with: `file.not_found` (the version has
9
+ * no file by that name), `file.invalid_name` (not a file name), or
10
+ * `file.unavailable` (the host could not read it now; asking again may
11
+ * succeed). */
12
+ export type AppFileRefusalCode = "file.not_found" | "file.invalid_name" | "file.unavailable";
13
+ /** The host's answer to `APP_FILE_QUESTION`. */
14
+ export interface AppFileAnswer {
15
+ name: string;
16
+ media_type: string;
17
+ bytes: ArrayBuffer;
18
+ }
19
+ /** Whether `name` is one an uploaded file may have: letters, digits, dots,
20
+ * dashes and underscores, at most 128, starting with a letter or digit,
21
+ * with no `..`. The same rule the upload and the build hold names to. */
22
+ export declare function isAppFileName(name: unknown): name is string;
23
+ /** The file name an address on the published address names
24
+ * (`/_files/cover.png` is `cover.png`), or null. */
25
+ export declare function appFileNameOf(address: string): string | null;
package/index.d.ts CHANGED
@@ -1,9 +1,11 @@
1
1
  import { AppCallError, type FieldState } from "./callError";
2
2
  import type * as Api from "./generated/apiTypes";
3
- import type { EventResult, EventResultTicket, WaitForResultOptions } from "./siteRuntime";
3
+ import type { AppPlace } from "./app";
4
+ import { type EventResult, type EventResultTicket, type OwnEntry, type WaitForResultOptions } from "./siteRuntime";
4
5
  export { AppCallError, type FieldState } from "./callError";
6
+ export * from "./app";
7
+ export * from "./files";
5
8
  export * from "./navigation";
6
- export * from "./site";
7
9
  export * from "./siteRuntime";
8
10
  export type * from "./generated/apiTypes";
9
11
  /** Which records `listTopics` reads. `schema` is the `schema.id` of a `type`
@@ -282,6 +284,10 @@ export interface BroadcastWatch {
282
284
  stop(): void;
283
285
  }
284
286
  export interface AppTransport {
287
+ /** Where the transport runs: `public` at the app's published address,
288
+ * where a type is named by its key. A transport without it is Alma's
289
+ * frame. */
290
+ place?: AppPlace;
285
291
  /** Resolves with the response's `data`, or `{ data, meta }` when the
286
292
  * response pages. A change is the viewer's own act: it resolves with the
287
293
  * result where they may make it, and rejects with the refusal's words
@@ -314,6 +320,11 @@ export interface AppTransport {
314
320
  * published site's raise returned. A transport without it has no
315
321
  * results to read. */
316
322
  result?(token: string): Promise<EventResult>;
323
+ /** An address the app's own uploaded file `name` shows from: at once
324
+ * where the address is known (`/_files/<name>` at a published
325
+ * address), or once the host has handed over its bytes (a blob: URL in
326
+ * Alma's frame). A transport without it has no files. */
327
+ fileUrl?(name: string): string | Promise<string>;
317
328
  }
318
329
  export declare function createAppSdk(transport: AppTransport): {
319
330
  call: <T>(operationId: AppOperationId, request?: AppRequest) => Promise<T>;
@@ -386,7 +397,13 @@ export declare function createAppSdk(transport: AppTransport): {
386
397
  groups?: Api.TypeViewGroup[];
387
398
  };
388
399
  }>;
389
- getTopicRecord: (topicId: string) => Promise<Api.AppTopicRecord>;
400
+ /** A record as the viewer reads it. At a published address it is an
401
+ * entry of a type the version lets visitors read in full, named with
402
+ * `type` (its key), in the same shape (see `PUBLIC_RECORD_SHAPE`); in
403
+ * Alma's frame `type` is not needed. */
404
+ getTopicRecord: (topicId: string, options?: {
405
+ type?: string;
406
+ }) => Promise<Api.AppTopicRecord>;
390
407
  getTopicFactDiscussion: (topicId: string, factId: string) => Promise<Api.AppFactDiscussion>;
391
408
  /** A field's earlier values, newest first, as the viewer may read
392
409
  * them. A record section's `earlier_values` says how many there are. */
@@ -494,8 +511,15 @@ export declare function createAppSdk(transport: AppTransport): {
494
511
  * see it follows the app's audience in Alma, never the app. The record and
495
512
  * its values are saved together: if one value is refused nothing is
496
513
  * created, and it rejects with the refusal's words, which start with the
497
- * field's key. Each call is one request: calling again creates again. */
498
- createTopic: (name: string, topicTypeId?: string, options?: CreateTopicOptions) => Promise<Api.CreatedTopicRecord>;
514
+ * field's key. Each call is one request: calling again creates again.
515
+ * The type is its id, or its key as the manifest names it; at a
516
+ * published address it is a type the version lets visitors add to, by
517
+ * key, `name` is its `name` field (empty lets Alma name it after the
518
+ * type), and the answer carries `result`, the visitor's private link to
519
+ * the entry, when the version lets them read their own. */
520
+ createTopic: (name: string, topicTypeId?: string, options?: CreateTopicOptions) => Promise<OperationResult<"createTopic"> & {
521
+ result?: EventResultTicket;
522
+ }>;
499
523
  /** Deletes a record of one of this app's own types as the viewer. Alma
500
524
  * keeps it for 30 days, when the person who deleted it can bring it back
501
525
  * with `restoreTopic`, or from the app's Data if they edit the app. A
@@ -574,6 +598,26 @@ export declare function createAppSdk(transport: AppTransport): {
574
598
  * result page reads from its address with `readResultToken`). Rejects
575
599
  * with `result.unavailable` where the transport has no results. */
576
600
  result: (token: string) => Promise<EventResult>;
601
+ /** The address to show the app's own uploaded file `name` from (an
602
+ * `<img src>`, a font, an audio source): `/_files/<name>` at the
603
+ * published address, a blob: URL of its bytes in Alma's frame.
604
+ * Rejects with `file.not_found`, `file.invalid_name` or
605
+ * `file.unavailable`. */
606
+ fileUrl: (name: string) => Promise<string>;
607
+ /** At a published address, the visitor's own entry, named by the
608
+ * private link this page was opened with: `#<token>` in its address
609
+ * (`navigate(path, { hash: result.token })` after `createTopic` or
610
+ * `raiseEvent` leads there; the token stays in the fragment, which no
611
+ * server and no log sees). Null when the address names none; `pending`
612
+ * until the entry is there, also for a token the site does not know;
613
+ * else the entry, in the shape `listTopics` gives. Rejects with
614
+ * `result.unavailable` in Alma's frame, where a member has no private
615
+ * link. */
616
+ ownEntry: (hash?: string) => Promise<{
617
+ status: "pending";
618
+ } | ({
619
+ status: "ready";
620
+ } & OwnEntry) | null>;
577
621
  /** Reads a result until it is ready, after 1, 2, 4 and then every 8
578
622
  * seconds, and resolves with what the workflow answered. Rejects with
579
623
  * `result.timeout` once `timeoutMs` (default two minutes) passes with