@k2b/cloud 0.28.0 → 0.29.1

package/src/browser/provider-folder.tsx

@@ -0,0 +1,301 @@
+import { timed } from "@k2b/stdlib/solid";
+import { announce, Button, IconButton, Placeholder, TextInput } from "@k2b/ui";
+import { batch, createMemo, createSignal, For, type JSX, Match, onCleanup, Show, Switch } from "solid-js";
+import type { FileProviderEntry } from "../contracts/file-provider";
+import type { fileChooserMessages } from "./file-chooser-messages";
+import { type FileProviderCaller, FileProviderError, type FileProviderSource, listProviderFolder } from "./file-providers";
+
+type Messages = ReturnType<typeof fileChooserMessages.resolve>["t"];
+type Crumb = { id?: string; name: string };
+/** Where the dialog is: a folder of one provider, or the source list when `null`. */
+export type FolderLocation = { provider: FileProviderSource; trail: readonly Crumb[] } | null;
+
+/** Empty pages may still continue; a dialog follows at most this many of them before it shows "Load more". */
+const EMPTY_PAGES_FOLLOWED = 5;
+
+/**
+ * Browsing one provider's folders, shared by choosing and saving: the location, the name filter, the folder's pages,
+ * and its load state. `settled` runs after a folder has loaded or the source list is back, so the dialog can move
+ * focus to its first row.
+ */
+export const createProviderFolder = (props: { caller: () => FileProviderCaller; t: () => Messages; settled: () => void }) => {
+  const [location, setLocation] = createSignal<FolderLocation>(null);
+  const [filter, setFilter] = createSignal("");
+  const [query, setQuery] = createSignal("");
+  const [items, setItems] = createSignal<FileProviderEntry[]>([]);
+  const [next, setNext] = createSignal<string | null>(null);
+  const [writable, setWritable] = createSignal(false);
+  const [status, setStatus] = createSignal<"loading" | "ready" | "more" | "error">("ready");
+  const [error, setError] = createSignal<FileProviderError | null>(null);
+  let request: AbortController | undefined;
+  onCleanup(() => request?.abort());
+
+  const folderName = () => location()?.trail.at(-1)?.name ?? props.t().sources;
+
+  const load = async (more = false) => {
+    const current = location();
+    if (!current) return;
+    request?.abort();
+    const pending = new AbortController();
+    request = pending;
+    if (!more) {
+      batch(() => {
+        setItems([]);
+        setNext(null);
+        setWritable(false);
+      });
+    }
+    setStatus(more ? "more" : "loading");
+    setError(null);
+    try {
+      let cursor = more ? (next() ?? undefined) : undefined;
+      let followed = 0;
+      for (;;) {
+        const page = await listProviderFolder(
+          current.provider,
+          { parent: current.trail.at(-1)?.id, query: query() || undefined, cursor },
+          props.caller(),
+          pending.signal,
+        );
+        if (pending.signal.aborted) return;
+        batch(() => {
+          setItems((previous) => [...previous, ...page.items]);
+          setNext(page.next);
+          if (!more) setWritable(page.writable);
+        });
+        if (items().length > 0 || !page.next || ++followed >= EMPTY_PAGES_FOLLOWED) break;
+        cursor = page.next;
+      }
+      setStatus("ready");
+      if (!more) {
+        announce(props.t().folderAnnounced({ folder: folderName(), count: items().length, more: Boolean(next()) }));
+        props.settled();
+      }
+    } catch (cause) {
+      if (pending.signal.aborted) return;
+      setError(
+        cause instanceof FileProviderError ? cause : new FileProviderError("INTERNAL", cause instanceof Error ? cause.message : "", 500),
+      );
+      setStatus(more ? "ready" : "error");
+    }
+  };
+
+  const applyQuery = (value: string) => {
+    setQuery(value.trim());
+    void load();
+  };
+  const { debouncedFn: applyFilter, cancel: cancelFilter } = timed.debounce(applyQuery, 250);
+  onCleanup(cancelFilter);
+  const clearFilter = () => {
+    cancelFilter();
+    setFilter("");
+    if (location() && query()) applyQuery("");
+  };
+  const changeFilter = (value: string) => {
+    setFilter(value);
+    if (location()) applyFilter(value);
+  };
+
+  const navigate = (target: FolderLocation) => {
+    cancelFilter();
+    request?.abort();
+    batch(() => {
+      setFilter("");
+      setQuery("");
+      setLocation(target);
+      setItems([]);
+      setNext(null);
+      setWritable(false);
+      setError(null);
+      setStatus(target ? "loading" : "ready");
+    });
+    if (target) void load();
+    else props.settled();
+  };
+  const openProvider = (provider: FileProviderSource) => navigate({ provider, trail: [{ name: provider.name }] });
+  const openFolder = (entry: FileProviderEntry) => {
+    const current = location();
+    if (current) navigate({ provider: current.provider, trail: [...current.trail, { id: entry.id, name: entry.name }] });
+  };
+  const up = () => {
+    const current = location();
+    if (!current) return;
+    navigate(current.trail.length > 1 ? { provider: current.provider, trail: current.trail.slice(0, -1) } : null);
+  };
+
+  const errorView = createMemo(() => {
+    const value = error();
+    if (!value) return null;
+    const t = props.t();
+    const app = location()?.provider.name ?? "";
+    if (value.status === 0) return { title: t.offline, description: t.offlineHint, retry: true };
+    if (value.status === 403) return { title: t.noAccess, description: t.backHint, retry: false };
+    if (value.status === 404) return { title: t.notFound, description: t.backHint, retry: false };
+    if (value.status >= 502 || value.code === "APP_UNAVAILABLE")
+      return { title: t.unavailable({ app }), description: t.unavailableHint, retry: true };
+    return { title: t.loadFailed, description: value.message || undefined, retry: true };
+  });
+
+  return {
+    location,
+    filter,
+    query,
+    items,
+    next,
+    writable,
+    status,
+    error,
+    errorView,
+    folderName,
+    load,
+    navigate,
+    openProvider,
+    openFolder,
+    up,
+    changeFilter,
+    clearFilter,
+  };
+};
+
+export type ProviderFolder = ReturnType<typeof createProviderFolder>;
+
+/**
+ * The path row with Up and the name filter. With `sources`, the path starts at the source list; without it, the
+ * provider is the top, so Up stops there.
+ */
+export function FolderToolbar(props: { folder: ProviderFolder; t: () => Messages; disabled: boolean; sources: boolean }): JSX.Element {
+  const top = () => {
+    const current = props.folder.location();
+    return !current || (!props.sources && current.trail.length === 1);
+  };
+  return (
+    <div class="cloud-file-chooser__toolbar">
+      <nav class="cloud-file-chooser__crumbs" aria-label={props.t().breadcrumbs}>
+        <IconButton size="sm" variant="ghost" label={props.t().up} disabled={top() || props.disabled} onClick={props.folder.up}>
+          <i class="ti ti-arrow-up" aria-hidden="true" />
+        </IconButton>
+        <ol>
+          <Show when={props.sources}>
+            <li>
+              <Button
+                size="sm"
+                variant={props.folder.location() ? "text" : "subtle"}
+                aria-current={props.folder.location() ? undefined : "location"}
+                disabled={props.disabled}
+                onClick={() => props.folder.navigate(null)}
+              >
+                {props.t().sources}
+              </Button>
+            </li>
+          </Show>
+          <For each={props.folder.location()?.trail ?? []}>
+            {(crumb, index) => {
+              const last = () => index() === (props.folder.location()?.trail.length ?? 0) - 1;
+              return (
+                <li>
+                  <Show when={props.sources || index() > 0}>
+                    <span aria-hidden="true">/</span>
+                  </Show>
+                  <Button
+                    size="sm"
+                    variant={last() ? "subtle" : "text"}
+                    aria-current={last() ? "location" : undefined}
+                    disabled={props.disabled}
+                    onClick={() => {
+                      const current = props.folder.location();
+                      if (current && !last())
+                        props.folder.navigate({ provider: current.provider, trail: current.trail.slice(0, index() + 1) });
+                    }}
+                  >
+                    {crumb.name}
+                  </Button>
+                </li>
+              );
+            }}
+          </For>
+        </ol>
+      </nav>
+      <TextInput
+        class="cloud-file-chooser__filter"
+        type="search"
+        icon="ti ti-filter"
+        aria-label={props.t().filter}
+        placeholder={props.t().filter}
+        maxLength={200}
+        disabled={props.disabled}
+        value={props.folder.filter}
+        onValueChange={props.folder.changeFilter}
+        clearable
+        onClear={props.folder.clearFilter}
+      />
+    </div>
+  );
+}
+
+/**
+ * One folder in the dialog body: loading, the error with Try again or Up, the empty folder, no matches, or `children`
+ * with Load more below while the folder continues.
+ */
+export function FolderContents(props: { folder: ProviderFolder; t: () => Messages; children: JSX.Element }): JSX.Element {
+  const folder = props.folder;
+  return (
+    <Switch>
+      <Match when={folder.status() === "loading"}>
+        <Placeholder state="loading" variant="panel" class="cloud-file-chooser__state" description={props.t().loading} />
+      </Match>
+      <Match when={folder.status() === "error" && folder.errorView()}>
+        {(view) => (
+          <Placeholder
+            state="error"
+            variant="panel"
+            class="cloud-file-chooser__state"
+            title={view().title}
+            description={view().description}
+            action={
+              view().retry ? (
+                <Button size="sm" variant="secondary" onClick={() => void folder.load()}>
+                  {props.t().retry}
+                </Button>
+              ) : (
+                <Button size="sm" variant="secondary" onClick={folder.up}>
+                  <i class="ti ti-arrow-up" aria-hidden="true" /> {props.t().up}
+                </Button>
+              )
+            }
+          />
+        )}
+      </Match>
+      <Match when={folder.items().length === 0 && !folder.next()}>
+        <Show
+          when={folder.query()}
+          fallback={<Placeholder variant="panel" class="cloud-file-chooser__state" icon="ti ti-folder" title={props.t().emptyFolder} />}
+        >
+          <Placeholder
+            variant="panel"
+            class="cloud-file-chooser__state"
+            icon="ti ti-filter-off"
+            title={props.t().noMatches({ query: folder.query() })}
+            action={
+              <Button size="sm" variant="secondary" onClick={folder.clearFilter}>
+                {props.t().clearFilter}
+              </Button>
+            }
+          />
+        </Show>
+      </Match>
+      <Match when={true}>
+        {props.children}
+        <div class="cloud-file-chooser__more">
+          <Show when={folder.error() && folder.status() === "ready"}>
+            <Placeholder state="error" variant="inline" align="left" description={folder.errorView()?.title} />
+          </Show>
+          <Show when={folder.next()}>
+            <Button variant="secondary" size="sm" loading={folder.status() === "more"} onClick={() => void folder.load(true)}>
+              {folder.error() ? props.t().retry : props.t().loadMore}
+            </Button>
+          </Show>
+        </div>
+      </Match>
+    </Switch>
+  );
+}

package/src/browser/provider-list.ts

@@ -0,0 +1,39 @@
+import { createSignal } from "solid-js";
+import { FileProviderError, type FileProviderSource } from "./file-providers";
+
+/** The catalog refuses the caller, such as a visitor of a public page or a session that has just expired. */
+const refused = (error: unknown) => error instanceof FileProviderError && (error.status === 401 || error.status === 403);
+
+/**
+ * One page's file providers, shared by choosing and saving: the list is loaded once and kept; a failed load is tried
+ * again on the next request. A caller the catalog refuses has no providers for now, and the next request asks again,
+ * because a renewed session may see them. `known` is the list once it arrived, and reactive.
+ */
+export const createProviderList = (loadProviders: () => Promise<FileProviderSource[]>) => {
+  let request: Promise<readonly FileProviderSource[]> | undefined;
+  const [known, setKnown] = createSignal<readonly FileProviderSource[] | undefined>(undefined);
+  const providers = (): Promise<readonly FileProviderSource[]> => {
+    request ??= loadProviders().then(
+      (list) => {
+        setKnown(list);
+        return list;
+      },
+      (error: unknown) => {
+        request = undefined;
+        if (!refused(error)) throw error;
+        setKnown([]);
+        return [];
+      },
+    );
+    return request;
+  };
+  return {
+    providers,
+    known,
+    /** Whether a load is running or kept; only a refusal or a failure leaves none behind. */
+    requested: () => request !== undefined,
+    prefetch: () => void providers().catch(() => undefined),
+  };
+};
+
+export type ProviderList = ReturnType<typeof createProviderList>;

package/src/browser/save-files.browser-harness.tsx

@@ -0,0 +1,35 @@
+import { render } from "solid-js/web";
+import { SaveFilesButton, saveFiles } from "./files";
+
+/**
+ * Buttons that call the real `saveFiles` for a browser test, which answers the catalog, the provider's Queries and
+ * Action, and its write streams. `#save` saves one attachment by URL, `#save-all` two, `#save-big` one above the
+ * provider's limit. Each call gets a fresh signal that `window.abortSaving()` aborts. Each result lands in
+ * `window.saved`. `SaveFilesButton` renders the shared icon button for the same attachment.
+ */
+type Saved = Awaited<ReturnType<typeof saveFiles>>;
+const results: Saved[] = [];
+let saving = new AbortController();
+Object.assign(window, { saved: results, abortSaving: () => saving.abort() });
+
+const attachment = (name: string) => ({ name, content: `/source/${encodeURIComponent(name)}` });
+const sets: Record<string, Parameters<typeof saveFiles>[0]> = {
+  save: [attachment("report.pdf")],
+  "save-all": [attachment("report.pdf"), attachment("notes.txt")],
+  "save-big": [{ ...attachment("huge.zip"), size: 5_000 }],
+};
+for (const [id, files] of Object.entries(sets)) {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.id = id;
+  button.textContent = id;
+  document.body.append(button);
+  button.addEventListener("click", () => {
+    saving = new AbortController();
+    void saveFiles(files, { signal: saving.signal }).then((saved) => void results.push(saved));
+  });
+}
+const icon = document.createElement("div");
+icon.id = "icon";
+document.body.append(icon);
+render(() => <SaveFilesButton files={() => sets.save!} />, icon);

package/src/browser/save-files.tsx

@@ -0,0 +1,107 @@
+import { dialogCore, IconButton, type IconButtonProps, panelDialogWorkspaceOptions, toast, useLocale } from "@k2b/ui";
+import { createSignal, type JSX, splitProps } from "solid-js";
+import type { FileProviderList } from "./FileChooser";
+import { FileSaver, type SavedFile } from "./FileSaver";
+import { fileChooserMessages } from "./file-chooser-messages";
+import type { FileProviderCaller, SaveFileSource } from "./file-providers";
+import type { ProviderList } from "./provider-list";
+
+export type { SavedFile } from "./FileSaver";
+export type { SaveFileSource } from "./file-providers";
+
+export type SaveFilesOptions = {
+  /** Closes the dialog and stops what is still running; files saved before stay saved. */
+  signal?: AbortSignal;
+};
+
+/** The icon of the save action, for menus that show it beside other actions. */
+export const SAVE_FILES_ICON = "ti ti-folder-down";
+
+/**
+ * One page's saving into file providers, over the same provider list as choosing. `caller` carries the locale and,
+ * in tests, the transport.
+ */
+export const createFileSaving = (
+  list: ProviderList,
+  caller: () => FileProviderCaller = () => ({ locale: document.documentElement.lang || "en" }),
+) => {
+  const saveFiles = async (files: readonly SaveFileSource[], options: SaveFilesOptions = {}): Promise<SavedFile[]> => {
+    if (files.length === 0 || options.signal?.aborted) return [];
+    // Only a refusal leaves an empty list without a request; asking again lets a renewed session find its apps.
+    const known = list.known()?.length === 0 && !list.requested() ? undefined : list.known();
+    const [providers, setProviders] = createSignal<FileProviderList>(known ? { state: "ready", providers: known } : { state: "loading" });
+    const load = () => {
+      setProviders({ state: "loading" });
+      list.providers().then(
+        (value) => setProviders({ state: "ready", providers: value }),
+        () => setProviders({ state: "error" }),
+      );
+    };
+    if (!known) load();
+    const saved: SavedFile[] = [];
+    const running = new Set<Promise<void>>();
+    await dialogCore.open<void>(
+      (close) => (
+        <FileSaver
+          files={files}
+          providers={providers}
+          retryProviders={load}
+          caller={caller}
+          saved={saved}
+          running={running}
+          close={() => close()}
+        />
+      ),
+      {
+        ...panelDialogWorkspaceOptions,
+        panelClassName: `${panelDialogWorkspaceOptions.panelClassName} cloud-file-chooser-dialog`,
+        // While the folder still loads, the dialog itself holds focus; its first row takes it once it arrives.
+        initialFocus: (dialog) => dialog.querySelector<HTMLElement>('[role="gridcell"][tabindex="0"]') ?? dialog,
+        signal: options.signal,
+        history: true,
+      },
+    );
+    // Closing stops the transfers; a receipt that was already on its way still counts.
+    await Promise.all(running);
+    const first = saved[0];
+    if (first) {
+      const t = fileChooserMessages.resolve([caller().locale]).t;
+      toast.success(
+        saved.length === 1 && files.length === 1
+          ? t.savedOne({ name: first.name, app: first.app })
+          : t.savedMany({ count: saved.length, total: files.length, app: first.app }),
+        first.href ? { action: { label: t.showIn({ app: first.app }), href: first.href } } : undefined,
+      );
+    }
+    return saved;
+  };
+
+  /**
+   * The save action's label: "Save to Files" once one provider that stores files is known, otherwise "Save to…".
+   * With `name` it names one file; with `all` it saves every file of a list.
+   */
+  const label = (locale: string, options: { name?: string; all?: boolean } = {}): string => {
+    const t = fileChooserMessages.resolve([locale]).t;
+    const savers = list.known()?.filter((provider) => provider.save) ?? [];
+    const app = savers.length === 1 ? savers[0]!.name : undefined;
+    if (options.all) return app ? t.saveAllTo({ app }) : t.saveAllToAny;
+    if (options.name) return app ? t.saveNamedTo({ name: options.name, app }) : t.saveNamedToAny({ name: options.name });
+    return app ? t.saveTo({ app }) : t.saveToAny;
+  };
+
+  /** An icon button that saves `files()` when activated; its label and tooltip name the file or say "all". */
+  function SaveFilesButton(
+    props: Omit<IconButtonProps, "children" | "label" | "onClick"> & { files: () => readonly SaveFileSource[]; all?: boolean },
+  ): JSX.Element {
+    const locale = useLocale();
+    const [local, rest] = splitProps(props, ["files", "all"]);
+    const name = () => (local.all ? undefined : local.files()[0]?.name);
+    return (
+      <IconButton {...rest} label={label(locale(), { name: name(), all: local.all })} onClick={() => void saveFiles(local.files())}>
+        <i class={SAVE_FILES_ICON} aria-hidden="true" />
+      </IconButton>
+    );
+  }
+
+  return { saveFiles, label, SaveFilesButton };
+};

package/src/cli/admin/outgoing-mail.ts

@@ -2,6 +2,8 @@ import {
   type AdminMailApp,
   type AdminMailProfile,
   type AdminMailRecord,
+  MailLogAccessSchema,
+  MailLogAppIdSchema,
   type MailPage,
   MailProfileInputSchema,
   type MailRetention,
@@ -181,8 +183,16 @@ export const outgoingMailCommands = [
       printJsonOrTable(
         ctx,
         result,
-        result.items.map((app) => ({ ...app, profiles: app.profiles.join(",") })),
-        [{ key: "appId" }, { key: "name" }, { key: "declared" }, { key: "mode" }, { key: "profiles" }],
+        result.items.map((app) => ({ ...app, reads: app.readDeclared, profiles: app.profiles.join(","), logApps: app.logApps.join(",") })),
+        [
+          { key: "appId" },
+          { key: "name" },
+          { key: "declared" },
+          { key: "reads" },
+          { key: "mode" },
+          { key: "profiles" },
+          { key: "logApps" },
+        ],
       );
     },
   }),
@@ -212,4 +222,22 @@ export const outgoingMailCommands = [
       );
     },
   }),
+  command("outgoing-mail apps set-log-access", {
+    summary: "Choose which other applications' mail logs an app may read",
+    args: { app: arg.required({ valueLabel: "app" }) },
+    flags: {
+      apps: flag.string({ description: "Comma-separated source application IDs" }),
+      ownOnly: flag.boolean({ description: "Remove all other application log grants" }),
+      yes: confirmFlag("Confirm application mail log access change"),
+    },
+    async run({ ctx, args, flags }) {
+      confirmed(flags.yes);
+      if ((flags.apps !== undefined) === !!flags.ownOnly) throw new Error("Choose exactly one of --apps or --own-only.");
+      const reader = MailLogAppIdSchema.safeParse(args.app);
+      const value = MailLogAccessSchema.safeParse({ apps: flags.apps?.split(",").map((app) => app.trim()) ?? [] });
+      if (!reader.success || args.app === "core" || !value.success || value.data.apps.includes(args.app))
+        throw new Error("Choose a valid reader and distinct source apps other than Core or the reader itself.");
+      print(ctx, await apiJson(ctx, "PUT", `${root}/apps/${encodeURIComponent(args.app)}/log-access`, value.data));
+    },
+  }),
 ];

package/src/contracts/app.ts

@@ -119,6 +119,8 @@ export type AppMeta = {
     section: "primary" | "more" | "hidden";
     requiresAuth?: boolean;
     requiresRoles?: Role[];
+    /** Same-origin path of a `GET` route this app serves that returns an `AppNavBadge`; see `defineApp()`. */
+    badge?: string;
   };
   /**
    * Legal/info pages this app owns. Aggregated app-wide and rendered in
@@ -146,6 +148,14 @@ export type AppMeta = {
   cli?: AppCliModules;
 };
 
+/**
+ * Response of an app's `nav.badge` route: how many items wait for the signed-in
+ * person. A positive safe integer shows a count on the app's icon in the rail
+ * and the app grid (above 99 as "99+"); `0`, a non-200 response, or anything
+ * else shows none.
+ */
+export type AppNavBadge = { count: number };
+
 export type WidgetEndpoint = {
   /** Unique-within-the-app id, e.g. "open-requests". */
   id: string;

package/src/contracts/commands.ts

@@ -8,7 +8,9 @@ export const CommandPathSchema = z
   .refine((value) => {
     if (!value.startsWith("/") || /[\\\u0000-\u0020]/u.test(value)) return false;
     try {
-      return new URL(value, "https://cloud.invalid").origin === "https://cloud.invalid";
+      const url = new URL(value, "https://cloud.invalid");
+      // Dot segments can resolve to `//host`, which a browser reads as another host.
+      return url.origin === "https://cloud.invalid" && !url.pathname.startsWith("//");
     } catch {
       return false;
     }

package/src/contracts/notification-group.ts

@@ -0,0 +1,6 @@
+/** App-chosen keys stay separate from the namespaced tags sent to browsers. */
+export const isNotificationGroup = (value: unknown): value is string =>
+  typeof value === "string" && value.length >= 1 && value.length <= 128 && /^[A-Za-z0-9._:-]+$/.test(value);
+
+export const notificationGroupTag = (appId: string, group: string): string | null =>
+  typeof appId === "string" && /^[a-z][a-z0-9-]*$/.test(appId) && isNotificationGroup(group) ? `${appId}:${group}` : null;

package/src/contracts/notification-types.ts

@@ -31,6 +31,12 @@ export const validateNotificationTargetHref = (value: string): `/${string}` => {
 export type NotificationPresentation = {
   title: string;
   body?: string;
+  /** Short text shown in the browser/OS notification, including the lock screen. Cloud passes it only to the browser channel; email, deployment channels, and notification history never receive it. */
+  preview?: string;
+  /** Stable app-chosen browser group key, namespaced by Cloud per application. */
+  group?: string;
+  /** Non-negative safe integer for the app badge; zero clears it. Browser-only. */
+  badge?: number;
   /** Same-origin absolute path. Validated again before persistence and navigation. */
   targetHref?: `/${string}`;
 };