nexus-shared 3.2.0 → 4.1.0

package/dist/Helpers/MessageUnread.js

@@ -0,0 +1,245 @@
+import { chatBadgeText } from "./ChatHelpers.js";
+/*
+ * How much mail waits, for the bell on every page: one poller per mailbox, outside React, shared by every bell that
+ * draws it. It reads `source.unread()` once when the first bell appears, then every minute while the page is in front,
+ * at once when the window takes the focus again or the tab is shown again, and never while the tab is hidden. However
+ * many bells a page draws, it asks once. When the count goes up after the page has read it once, it words it for a
+ * screen reader, so the bell says "3 unread messages" once - not on every read, and not as the page loads.
+ */
+/** How often the bell reads, in milliseconds, while the page is in front: a minute (the domain messages spec). */
+export const MESSAGE_UNREAD_INTERVAL = 60_000;
+/** A wake within this long of the last read reads nothing more: a tab shown again also takes the focus. */
+export const MESSAGE_UNREAD_WAKE_GAP = 2_000;
+/** The browser's: `Date.now`, `setTimeout`, `document.visibilityState`, `focus` and `visibilitychange`. */
+export function browserUnreadEnvironment() {
+    return {
+        now: () => Date.now(),
+        later: (run, ms) => {
+            const timer = setTimeout(run, ms);
+            return () => clearTimeout(timer);
+        },
+        visible: () => typeof document === "undefined" || document.visibilityState !== "hidden",
+        watch: run => {
+            if (typeof window === "undefined")
+                return () => { };
+            window.addEventListener("focus", run);
+            document.addEventListener("visibilitychange", run);
+            return () => {
+                window.removeEventListener("focus", run);
+                document.removeEventListener("visibilitychange", run);
+            };
+        },
+    };
+}
+/** "No unread messages", "1 unread message", "3 unread messages", "More than 99 unread messages". */
+export function mailUnreadWords(count, max = 99) {
+    if (count <= 0)
+        return "No unread messages";
+    if (count > max)
+        return `More than ${max} unread messages`;
+    return count === 1 ? "1 unread message" : `${count} unread messages`;
+}
+/** The badge: "3", "99+" from 100 on (a backend counts to 100 and stops). Empty for none. */
+export function mailUnreadBadge(count, max = 99) {
+    return count > 0 ? chatBadgeText(count, max) : "";
+}
+/** A thread's address in the inbox: `href` with `thread=<id>` added to its query, before any `#`. */
+export function mailThreadHref(href, id) {
+    const hash = href.indexOf("#");
+    const path = hash < 0 ? href : href.slice(0, hash);
+    const rest = hash < 0 ? "" : href.slice(hash);
+    return `${path}${path.includes("?") ? "&" : "?"}thread=${encodeURIComponent(String(id))}${rest}`;
+}
+const IDLE = { status: "idle", count: 0, newest: [], failed: false };
+/** One mailbox's unread count for the whole page. Every bell of the page on the same source shares it. */
+export class MessageUnreadPoller {
+    source;
+    env;
+    snapshot = IDLE;
+    listeners = new Set();
+    members = new Map();
+    controller = null;
+    cancelTimer = null;
+    stopWatching = null;
+    startedAt = Number.NEGATIVE_INFINITY;
+    endedAt = Number.NEGATIVE_INFINITY;
+    known = false;
+    seq = 0;
+    /** A refresh was asked while a read was on its way: one more read follows it. */
+    again = false;
+    /** Reads started, for a page that shows how many calls it made, and for tests. */
+    reads = 0;
+    constructor(source, env = browserUnreadEnvironment()) {
+        this.source = source;
+        this.env = env;
+    }
+    getSnapshot = () => this.snapshot;
+    /** Hears every change. Joining is separate: a bell that only shows a count need not make the page read. */
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    set(next) {
+        this.snapshot = { ...this.snapshot, ...next };
+        for (const listener of this.listeners)
+            listener();
+    }
+    /** How often the members want a read: the shortest any of them asked for. */
+    get interval() {
+        return this.members.size ? Math.min(...this.members.values()) : MESSAGE_UNREAD_INTERVAL;
+    }
+    /** A bell drawn: the first starts the reads. Reads at once unless an answer younger than the interval is held. */
+    join(interval = MESSAGE_UNREAD_INTERVAL) {
+        const key = Symbol("bell");
+        const first = this.members.size === 0;
+        this.members.set(key, Math.max(1000, interval));
+        if (first)
+            this.stopWatching = this.env.watch(() => this.wake());
+        if (this.env.now() - this.endedAt >= this.interval)
+            this.read();
+        else
+            this.schedule();
+        return {
+            leave: () => {
+                if (!this.members.delete(key))
+                    return;
+                if (this.members.size === 0)
+                    this.stop();
+                else
+                    this.schedule();
+            },
+            speaks: () => this.members.keys().next().value === key,
+        };
+    }
+    /**
+     * Reads now: a page that just read a thread, archived some, or a bell opened. With a read on its way - which may have
+     * counted before the change - one more read follows it, however many refreshes are asked meanwhile; never two at once.
+     * While the page is hidden nothing is read: the read asked for waits for the page to be shown.
+     */
+    refresh() {
+        if (this.members.size === 0)
+            return;
+        if (this.controller || !this.env.visible()) {
+            this.again = true;
+            return;
+        }
+        this.read();
+    }
+    /** A read ended: the one asked for meanwhile, now, while the page is in front; else the next one, a minute on. */
+    settle() {
+        if (this.again && this.members.size > 0 && this.env.visible()) {
+            this.again = false;
+            this.read();
+            return;
+        }
+        this.schedule();
+    }
+    /** The window took the focus, or the tab was shown or hidden. */
+    wake() {
+        if (!this.env.visible()) {
+            this.cancelTimer?.();
+            this.cancelTimer = null;
+            return;
+        }
+        if (this.controller)
+            return;
+        // Shown again with a read asked for while hidden: at once, however recent the last read.
+        if (this.again) {
+            this.again = false;
+            this.read();
+            return;
+        }
+        if (this.env.now() - this.startedAt < MESSAGE_UNREAD_WAKE_GAP) {
+            this.schedule();
+            return;
+        }
+        this.read();
+    }
+    read() {
+        if (this.controller || !this.env.visible())
+            return;
+        this.cancelTimer?.();
+        this.cancelTimer = null;
+        const controller = new AbortController();
+        this.controller = controller;
+        this.startedAt = this.env.now();
+        this.reads++;
+        if (!this.known)
+            this.set({ status: "loading" });
+        let answer;
+        try {
+            answer = Promise.resolve(this.source.unread(controller.signal));
+        }
+        catch (error) {
+            answer = Promise.reject(error);
+        }
+        answer.then(unread => {
+            if (this.controller !== controller)
+                return;
+            this.controller = null;
+            this.endedAt = this.env.now();
+            const count = Math.max(0, Math.floor(Number(unread.count) || 0));
+            const before = this.snapshot.count;
+            const rose = this.known && count > before;
+            this.known = true;
+            this.set({
+                status: "ready",
+                count,
+                newest: unread.newest ?? [],
+                failed: false,
+                error: undefined,
+                checkedAt: this.endedAt,
+                ...(rose && { spoken: { text: mailUnreadWords(count), seq: ++this.seq } }),
+            });
+            this.settle();
+        }, (error) => {
+            if (this.controller !== controller)
+                return;
+            this.controller = null;
+            this.endedAt = this.env.now();
+            // The count read before stays on the bell; the next minute tries again.
+            this.set({ status: this.known ? "ready" : "failed", failed: true, error });
+            this.settle();
+        });
+    }
+    /** The next read, an interval after the last one ended: only while a bell is drawn and the page is in front. */
+    schedule() {
+        this.cancelTimer?.();
+        this.cancelTimer = null;
+        if (this.members.size === 0 || this.controller || !this.env.visible())
+            return;
+        const wait = Math.max(0, this.interval - (this.env.now() - this.endedAt));
+        this.cancelTimer = this.env.later(() => {
+            this.cancelTimer = null;
+            this.read();
+        }, wait);
+    }
+    /** The last bell went: no timer, no watching, the read on its way called off. What was read stays for the next bell. */
+    stop() {
+        this.again = false;
+        this.cancelTimer?.();
+        this.cancelTimer = null;
+        this.stopWatching?.();
+        this.stopWatching = null;
+        if (this.controller) {
+            this.controller.abort();
+            this.controller = null;
+            if (!this.known)
+                this.set({ status: "idle" });
+        }
+    }
+}
+const pollers = new WeakMap();
+/** The page's poller for a mailbox: one per source object, however many bells draw it. */
+export function messageUnreadPoller(source) {
+    let poller = pollers.get(source);
+    if (!poller) {
+        poller = new MessageUnreadPoller(source);
+        pollers.set(source, poller);
+    }
+    return poller;
+}
+/** Reads the count again now, for every bell on `source`: after the page read a thread or archived some. */
+export function refreshMessageUnread(source) {
+    pollers.get(source)?.refresh();
+}

package/dist/Helpers/NexusDriveAdapter.d.ts

@@ -0,0 +1,71 @@
+import type { ApiClient } from "./ApiClient.ts";
+import { FileAdapter } from "./FileAdapter.ts";
+import { type ApiModuleValue, type ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { FileCallOptions, FileChange, FileCopy, FileOwner, FileUpload, OwnerFiles, StoredFile } from "../Interfaces/FileInterfaces.ts";
+/**
+ * The owner module's refusal, passed on by Drive, of a change to files that may now only be added to (`API_X084`, the
+ * core's `NexusFileTickets.WritableAsync`): a posted goods receipt's documents renamed, marked or removed.
+ */
+export declare const FILES_ADD_ONLY = "API_X084";
+/**
+ * Why an owner's files are read only when its module refuses a write ticket with a 404 but a read ticket finds it: the
+ * owner is not in use now (pending, ended, in the trash or deleted). Its files stay where they are.
+ */
+export declare const OWNER_NOT_IN_USE_REASON = "This record is not in use now, so its files can be seen but not changed.";
+/** What the adapter sends its calls with: the app's `api` (nexus-shared/client), so its token and headers go with them. */
+export type FileApiClient = Pick<ApiClient<{
+    toast?: false;
+}>, "send">;
+export interface NexusDriveAdapterOptions {
+    /** The client the calls go through: `api` from nexus-shared/client. */
+    client: FileApiClient;
+    /** Reads the editor's pointer file. Default the browser's `fetch`. */
+    fetch?: typeof fetch;
+    /** The app's Drive module. Default `NexusModule.Drive`. */
+    drive?: ApiModuleValue;
+    /** The pointer file that names the current editor. Default `nexus-image-editor.txt` (Drive's `copy-image-editor.mjs`). */
+    editorPointer?: string;
+}
+/**
+ * The Nexus Drive (`Nexus.Drives`, `App/Api/File/...`) behind the owner modules' tickets (`App/Api/Files/...`).
+ * Register another with `defineFileAdapter` to keep files elsewhere.
+ */
+export declare class NexusDriveAdapter extends FileAdapter {
+    readonly drive: ApiModuleValue;
+    readonly editorPointer: string;
+    private readonly tickets;
+    private readonly client;
+    private readonly fetcher;
+    constructor(options: NexusDriveAdapterOptions);
+    private driveEndpoint;
+    /** A write ticket for the owner, kept while it is good. */
+    private writeTicket;
+    /** Calls Drive with the owner's write ticket, asking for a fresh one once when Drive says it ran out. */
+    private withTicket;
+    /** A read ticket for several owners of one category. */
+    private readTicket;
+    list(owner: FileOwner<ApiModuleValue>, options?: FileCallOptions): Promise<ApiResult<OwnerFiles>>;
+    primaries(module: ApiModuleValue, category: string, ownerIds: readonly string[], options?: FileCallOptions): Promise<ApiResult<(StoredFile | null)[]>>;
+    upload(owner: FileOwner<ApiModuleValue>, upload: FileUpload, options?: FileCallOptions): Promise<ApiResult<StoredFile>>;
+    setPrimary(owner: FileOwner<ApiModuleValue>, fileId: string | null, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    rename(owner: FileOwner<ApiModuleValue>, fileId: string, name: string, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    /**
+     * Drive's Delete answers the file record: `pendingRemoval: true` when it stays for the review (a picture live on a
+     * reviewed gallery; a second Delete changes nothing), else it is gone (`false`, or nothing from an older Drive).
+     */
+    remove(owner: FileOwner<ApiModuleValue>, fileId: string, options?: FileCallOptions): Promise<ApiResult<unknown>>;
+    /**
+     * `PUT File/Keep/{id}` with `{ ticket, id }` (the same id: Drive refuses a body id unlike the route's): the held removal
+     * cancelled, the file answered as it is now (`pendingRemoval: false`); a file not waiting is answered unchanged.
+     */
+    keep(owner: FileOwner<ApiModuleValue>, fileId: string, options?: FileCallOptions): Promise<ApiResult<StoredFile | null>>;
+    /** `API_X084`: the files may now only be added to. */
+    changesLeft(answer: Pick<ApiResult, "messageCode" | "errorCode" | "status">): readonly FileChange[] | null;
+    fileUrl(file: StoredFile, copy: FileCopy): string;
+    /** Reads Drive's pointer file (`Assets/File/nexus-image-editor.txt`), which names the versioned module beside it. */
+    editorModuleUrl(signal?: AbortSignal): Promise<string>;
+}
+/** Reads one of Drive's `FileResponseContract`s; null when it is not one. */
+export declare function readStoredFile(value: unknown): StoredFile | null;
+/** Reads Drive's `FileListResponseContract`. */
+export declare function readOwnerFiles(value: unknown): OwnerFiles;

package/dist/Helpers/NexusDriveAdapter.js

@@ -0,0 +1,236 @@
+import { readFetchResponse } from "./ApiResponses.js";
+import { getApiModules } from "./ApiModules.js";
+import { FileAdapter, fileOwnerKey, pictureLimits, removalHeld } from "./FileAdapter.js";
+import { NexusModule } from "../Interfaces/ApiInterfaces.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const text = (value) => (typeof value === "string" && value.trim() ? value : null);
+const count = (value, fallback = 0) => (typeof value === "number" && Number.isFinite(value) ? value : fallback);
+/** Drive's `EFileKinds` flags, and the MIME type of each. */
+const NEXUS_FILE_KINDS = [
+    [1, "image/png"],
+    [2, "image/jpeg"],
+    [4, "image/webp"],
+    [8, "application/pdf"],
+];
+/** The Drive refusal that says a ticket ran out (DRV_X011): asked again once, with a fresh ticket. */
+const TICKET_RAN_OUT = "DRV_X011";
+/**
+ * The owner module's refusal, passed on by Drive, of a change to files that may now only be added to (`API_X084`, the
+ * core's `NexusFileTickets.WritableAsync`): a posted goods receipt's documents renamed, marked or removed.
+ */
+export const FILES_ADD_ONLY = "API_X084";
+/**
+ * Why an owner's files are read only when its module refuses a write ticket with a 404 but a read ticket finds it: the
+ * owner is not in use now (pending, ended, in the trash or deleted). Its files stay where they are.
+ */
+export const OWNER_NOT_IN_USE_REASON = "This record is not in use now, so its files can be seen but not changed.";
+/** A ticket is used until this long before it runs out, so a slow upload never carries one that expires on the way. */
+const TICKET_MARGIN_MS = 60_000;
+/**
+ * The Nexus Drive (`Nexus.Drives`, `App/Api/File/...`) behind the owner modules' tickets (`App/Api/Files/...`).
+ * Register another with `defineFileAdapter` to keep files elsewhere.
+ */
+export class NexusDriveAdapter extends FileAdapter {
+    drive;
+    editorPointer;
+    tickets = new Map();
+    client;
+    fetcher;
+    constructor(options) {
+        super();
+        this.client = options.client;
+        this.fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.drive = options.drive ?? NexusModule.Drive;
+        this.editorPointer = options.editorPointer ?? "nexus-image-editor.txt";
+    }
+    driveEndpoint(method, path, extras = {}) {
+        return { module: this.drive, path, method, ...extras };
+    }
+    /** A write ticket for the owner, kept while it is good. */
+    async writeTicket(owner, signal, fresh = false) {
+        const key = fileOwnerKey(owner);
+        const kept = this.tickets.get(key);
+        if (!fresh && kept && kept.until > Date.now())
+            return { ok: true, result: kept.ticket };
+        const answer = await this.client.send({ module: owner.module, path: "Files/Ticket/{category}/{ownerId}", method: "POST" }, {
+            params: { category: owner.category, ownerId: owner.ownerId },
+            signal,
+            toast: false,
+        });
+        const ticket = isRecord(answer.result) ? text(answer.result.ticket) : null;
+        if (!answer.ok || !ticket) {
+            this.tickets.delete(key);
+            return { ...answer, ok: false, result: undefined };
+        }
+        const expires = isRecord(answer.result) ? Date.parse(String(answer.result.expiresAt ?? "")) : NaN;
+        // Kept only when the backend's end is ahead of this clock by more than the margin; a clock that is ahead asks each time.
+        if (Number.isFinite(expires) && expires - TICKET_MARGIN_MS > Date.now())
+            this.tickets.set(key, { ticket, until: expires - TICKET_MARGIN_MS });
+        return { ...answer, result: ticket };
+    }
+    /** Calls Drive with the owner's write ticket, asking for a fresh one once when Drive says it ran out. */
+    async withTicket(owner, options, call) {
+        for (const fresh of [false, true]) {
+            const ticket = await this.writeTicket(owner, options.signal, fresh);
+            if (!ticket.ok)
+                return ticket;
+            const answer = await call(ticket.result);
+            if (answer.ok || answer.messageCode !== TICKET_RAN_OUT || fresh)
+                return answer;
+        }
+        return { ok: false };
+    }
+    /** A read ticket for several owners of one category. */
+    async readTicket(module, category, ownerIds, signal) {
+        const answer = await this.client.send({ module, path: "Files/Owners/{category}", method: "POST" }, {
+            params: { category },
+            body: { ownerIds },
+            signal,
+            toast: false,
+        });
+        const ticket = isRecord(answer.result) ? text(answer.result.ticket) : null;
+        return answer.ok && ticket ? { ...answer, result: ticket } : { ...answer, ok: false, result: undefined };
+    }
+    async list(owner, options = {}) {
+        const read = (ticket) => this.client.send(this.driveEndpoint("POST", "File/List"), { body: { ticket }, signal: options.signal, toast: false });
+        let answer = await this.withTicket(owner, options, read);
+        // No write ticket for this person (a key they do not hold, an owner they may only see): their files, read only, and
+        // the refusal's words as the reason. A 404 is an owner not in use - pending, ended, in the trash or deleted - that a
+        // read ticket still finds: "The record was not found." under its files would be untrue, so it says what it is.
+        let refused;
+        if (!answer.ok && (answer.status === 403 || answer.status === 404) && owner.ownerId !== "me" && !answer.aborted) {
+            refused = answer.status === 404 ? OWNER_NOT_IN_USE_REASON : answer.message;
+            const ticket = await this.readTicket(owner.module, owner.category, [owner.ownerId], options.signal);
+            if (ticket.ok)
+                answer = await read(ticket.result);
+        }
+        if (!answer.ok)
+            return answer;
+        const files = readOwnerFiles(answer.result);
+        if (refused && !files.category.canWrite)
+            files.readOnlyReason = refused;
+        return { ...answer, result: files };
+    }
+    async primaries(module, category, ownerIds, options = {}) {
+        if (ownerIds.length === 0)
+            return { ok: true, result: [] };
+        const ticket = await this.readTicket(module, category, ownerIds, options.signal);
+        if (!ticket.ok)
+            return { ...ticket, result: undefined };
+        const answer = await this.client.send(this.driveEndpoint("POST", "File/Primaries"), { body: { ticket: ticket.result }, signal: options.signal, toast: false });
+        if (!answer.ok)
+            return answer;
+        const files = ownerIds.map(() => null);
+        for (const item of Array.isArray(answer.result) ? answer.result : []) {
+            if (!isRecord(item))
+                continue;
+            const index = count(item.ownerIndex, -1);
+            if (index >= 0 && index < files.length)
+                files[index] = readStoredFile(item.file);
+        }
+        return { ...answer, result: files };
+    }
+    upload(owner, upload, options = {}) {
+        return this.withTicket(owner, options, async (ticket) => {
+            const form = new FormData();
+            form.append("ticket", ticket);
+            form.append("file", upload.file, upload.name);
+            if (upload.thumbnail)
+                form.append("thumbnail", upload.thumbnail, `thumbnail-${upload.name}`);
+            const answer = await this.client.send(this.driveEndpoint("POST", "File/Upload", { bodyType: "form-data" }), { body: form, signal: options.signal, toast: false, timeout: 120_000 });
+            const file = answer.ok ? readStoredFile(answer.result) : null;
+            return answer.ok && file ? { ...answer, result: file } : { ...answer, ok: answer.ok && file !== null, result: undefined };
+        });
+    }
+    setPrimary(owner, fileId, options = {}) {
+        return this.withTicket(owner, options, ticket => this.client.send(this.driveEndpoint("PUT", "File/SetPrimary"), { body: { ticket, id: fileId }, signal: options.signal, toast: false }));
+    }
+    rename(owner, fileId, name, options = {}) {
+        return this.withTicket(owner, options, ticket => this.client.send(this.driveEndpoint("PUT", "File/Rename"), { body: { ticket, id: fileId, fileDisplayName: name }, signal: options.signal, toast: false }));
+    }
+    /**
+     * Drive's Delete answers the file record: `pendingRemoval: true` when it stays for the review (a picture live on a
+     * reviewed gallery; a second Delete changes nothing), else it is gone (`false`, or nothing from an older Drive).
+     */
+    async remove(owner, fileId, options = {}) {
+        const answer = await this.withTicket(owner, options, ticket => this.client.send(this.driveEndpoint("DELETE", "File/Delete"), { body: { ticket, id: fileId }, signal: options.signal, toast: false }));
+        if (!answer.ok || !removalHeld(answer.result))
+            return answer;
+        return { ...answer, result: readStoredFile(answer.result) ?? { pendingRemoval: true } };
+    }
+    /**
+     * `PUT File/Keep/{id}` with `{ ticket, id }` (the same id: Drive refuses a body id unlike the route's): the held removal
+     * cancelled, the file answered as it is now (`pendingRemoval: false`); a file not waiting is answered unchanged.
+     */
+    keep(owner, fileId, options = {}) {
+        return this.withTicket(owner, options, async (ticket) => {
+            const answer = await this.client.send(this.driveEndpoint("PUT", "File/Keep/{id}"), { params: { id: fileId }, body: { ticket, id: fileId }, signal: options.signal, toast: false });
+            return { ...answer, result: answer.ok ? readStoredFile(answer.result) : undefined };
+        });
+    }
+    /** `API_X084`: the files may now only be added to. */
+    changesLeft(answer) {
+        return answer.messageCode === FILES_ADD_ONLY ? ["add"] : null;
+    }
+    fileUrl(file, copy) {
+        return getApiModules().browserApiUrl(this.driveEndpoint("GET", "File/View/{id}/{size}"), { params: { id: file.id, size: copy === "thumbnail" ? "Thumbnail" : "Original" } });
+    }
+    /** Reads Drive's pointer file (`Assets/File/nexus-image-editor.txt`), which names the versioned module beside it. */
+    async editorModuleUrl(signal) {
+        const asset = (file) => getApiModules().browserApiUrl(this.driveEndpoint("GET", "Assets/File/{file}"), { params: { file } });
+        const response = await this.fetcher(asset(this.editorPointer), { signal, credentials: "same-origin", cache: "no-cache" });
+        if (!response.ok) {
+            const answer = await readFetchResponse(response);
+            throw new Error(answer.message ?? "The image editor could not be loaded.");
+        }
+        const name = (await response.text()).trim();
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\.m?js$/.test(name))
+            throw new Error("The image editor's address on the server is not valid.");
+        return new URL(asset(name), globalThis.location?.href ?? "http://localhost/").href;
+    }
+}
+/** Reads one of Drive's `FileResponseContract`s; null when it is not one. */
+export function readStoredFile(value) {
+    if (!isRecord(value))
+        return null;
+    const id = text(value.id);
+    if (!id)
+        return null;
+    return {
+        id,
+        name: text(value.fileDisplayName) ?? "File",
+        contentType: text(value.contentType) ?? "application/octet-stream",
+        size: count(value.fileSize),
+        width: typeof value.width === "number" ? value.width : null,
+        height: typeof value.height === "number" ? value.height : null,
+        hasThumbnail: value.hasThumbnail === true,
+        isPrimary: value.isPrimary === true,
+        createdAt: text(value.creationTime),
+        // Only on a file whose Delete waits for a review (Drive's `removalTime` with it): every other file's record is as before.
+        ...(value.pendingRemoval === true ? { pendingRemoval: true, ...(text(value.removalTime) ? { removalAt: text(value.removalTime) } : {}) } : {}),
+    };
+}
+/** Reads Drive's `FileListResponseContract`. */
+export function readOwnerFiles(value) {
+    const answer = isRecord(value) ? value : {};
+    const kinds = count(answer.fileKinds);
+    const maxBytes = count(answer.maxFileBytes);
+    // A picture's limits, Drive's settings (`Nexus:Drive:Pictures`); an older Drive says none, and the defaults apply, so
+    // every picture is still made small before it is sent.
+    const pictures = pictureLimits({ maxBytes, pictureMaxSide: count(answer.pictureMaxSide), pictureQuality: count(answer.pictureQuality), pictureMaxBytes: count(answer.pictureMaxBytes) });
+    const category = {
+        code: text(answer.categoryCode) ?? "",
+        name: text(answer.displayName) ?? "Files",
+        types: NEXUS_FILE_KINDS.filter(([flag]) => (kinds & flag) !== 0).map(([, type]) => type),
+        maxBytes,
+        maxCount: count(answer.maxFileCount),
+        thumbnailSize: count(answer.thumbnailSize),
+        canWrite: answer.canWrite === true,
+        pictureMaxSide: pictures.maxSide,
+        pictureQuality: pictures.quality,
+        pictureMaxBytes: pictures.maxBytes,
+        ...(answer.holdsRemovals === true ? { holdsRemovals: true } : {}),
+    };
+    const files = (Array.isArray(answer.files) ? answer.files : []).map(readStoredFile).filter((file) => file !== null);
+    return { category, files };
+}