@brftech/filex-app-ui 0.54.0 → 0.56.0

package/dist/index.d.ts

@@ -6,6 +6,152 @@ export declare interface BridgeError {
     message?: string;
 }
 
+/** `coedit.append` params: the host seals it and the relay places it. */
+export declare interface CoEditAppendParams {
+    kind: CoEditKind;
+    body: unknown;
+}
+
+export declare interface CoEditAppendResult {
+    /** Where it landed; it comes back as a `coedit.entry` too. */
+    seq: number;
+}
+
+export declare interface CoEditBlobGetParams {
+    name: string;
+}
+
+export declare interface CoEditBlobGetResult {
+    name: string;
+    bytes: ArrayBuffer;
+}
+
+/** `coedit.blob.put` / `coedit.blob.get`: the session's sealed blobs (the
+ *  base document, images added while editing). A name, not a path. */
+export declare interface CoEditBlobPutParams {
+    name: string;
+    data: ArrayBuffer;
+}
+
+/** `coedit.cursor` event data. */
+export declare interface CoEditCursor {
+    client: string;
+    cursor: unknown;
+}
+
+/** `coedit.cursor` params: passed to the other members, not kept. The host
+ *  sends a few a second at most (the last one wins). */
+export declare interface CoEditCursorParams {
+    cursor: unknown;
+}
+
+/** `coedit.dropped` event data (filex 0.56). */
+export declare interface CoEditDropped {
+    /** The last entry the host handed over. */
+    from: number;
+    /** `gone`: the membership ended (the session closed, or the page was away
+     *  too long) - join again. `broken`: an entry did not check out (missing,
+     *  moved, altered, replayed) - stop editing together. */
+    reason: 'gone' | 'broken';
+}
+
+/** One entry of the session's log, opened and checked by filex. */
+export declare type CoEditEntry = (CoEditEntryBase & {
+    kind: CoEditKind;
+    body: unknown;
+}) | (CoEditEntryBase & {
+    kind: 'join';
+    member: CoEditMember;
+}) | (CoEditEntryBase & {
+    kind: 'leave';
+}) | (CoEditEntryBase & {
+    kind: 'saved';
+    through: number;
+});
+
+declare interface CoEditEntryBase {
+    seq: number;
+    /** The relay's time, Unix ms - the same for every member. */
+    at: number;
+    client: string;
+}
+
+/**
+ * What `coedit.join` answers: who the app is in the session and how far
+ * the log has gone. The entries come as `coedit.entry` events once the app
+ * subscribes (`coedit.subscribe` from 0 for the whole log). `unavailable`
+ * when filex offers no editing together here (filex 0.55, editing together
+ * turned off, an encrypted file, a vault): the app edits alone - the message
+ * says why (`not_ready` after waiting for a session's creator, `encrypted`,
+ * `nothing_to_watch` for a person who may only read the file while nobody
+ * edits it, or the server's code: `coedit_off`, `coedit_build`,
+ * `coedit_file_changed`).
+ */
+export declare interface CoEditHello {
+    session: string;
+    me: CoEditMember;
+    /**
+     * The last entry's seq when filex handed the session over (0: an empty
+     * log). filex 0.56: the changes this browser kept from an earlier opening
+     * of the file (a lost connection, a closed tab), which filex sends before
+     * it answers, are in the log up to here - an editor that starts once it
+     * has read this far opens with them.
+     */
+    head: number;
+    /** The last `changes` entry's seq, as far as `head`. */
+    changesHead: number;
+    /** The last entry the file on the storage holds. */
+    savedThrough: number;
+    /**
+     * filex 0.56: this member started the session. Before anybody else can
+     * join it puts the base document - EXACTLY the bytes it opened - with
+     * `coedit.blob.put('base', bytes)`. A member that did not start it opens
+     * `coedit.blob.get('base')`, never the file: the file may hold a save of
+     * the session already, and the log applies to the base.
+     */
+    created: boolean;
+}
+
+/** `coedit.join` params: join (or start) the session of an opened file. */
+export declare interface CoEditJoinParams {
+    index?: number;
+}
+
+/** What a member appends: the editor's changes, a lock request, a release. */
+export declare type CoEditKind = 'changes' | 'lock' | 'release';
+
+/** `coedit.lease`: the changes lease (one writer at a time, one that has
+ *  seen every change). */
+export declare interface CoEditLeaseParams {
+    op: 'acquire' | 'release';
+    /** The seq of the last `changes` entry the app applied. */
+    changesSeen: number;
+}
+
+export declare interface CoEditLeaseResult {
+    granted: boolean;
+}
+
+/** A member of the session. */
+export declare interface CoEditMember {
+    /** The relay's id for the connection. */
+    client: string;
+    /** An opaque id of the person, the same for each of their connections in
+     *  this session; never an account id. */
+    user: string;
+    /** The person's display name. */
+    name: string;
+    /** The editor's per-session user index: given once, never twice. */
+    indexUser: number;
+    /** May append changes (an editor role and the right to change the file). */
+    canEdit: boolean;
+}
+
+/** `coedit.subscribe` params: entries after `from` arrive as `coedit.entry`. */
+export declare interface CoEditSubscribeParams {
+    from: number;
+}
+
 export declare interface ConfirmParams {
     title?: string;
     text: string;
@@ -92,16 +238,64 @@ export declare interface FileInfo {
     /** It cannot be saved over: read-only storage, view-only opening, or the
      *  app holds no `files:write`. */
     readOnly: boolean;
+    /**
+     * 0.55.0: the file is end-to-end encrypted - `folder` in an encrypted
+     * folder, `vault` in a vault (where only one person edits at a time),
+     * `file` for a single encrypted file (`.fxe`). As the server says it;
+     * ABSENT for a file that is not encrypted.
+     *
+     * ⚠ The server holds such a file only as ciphertext and has no key. Unless
+     * `plaintext` is true, filex hands the app nothing of it: `file.read` is
+     * refused (`failed` with `encrypted`), a save is refused, and `readOnly`
+     * is true.
+     */
+    encrypted?: 'folder' | 'vault' | 'file';
+    /**
+     * 0.56.0: filex hands this encrypted file to the app in the clear. The
+     * person's browser, which holds the folder key while the folder is
+     * unlocked, decrypts it for `file.read` and encrypts what `file.save`
+     * hands over before it leaves the browser; the server sees only
+     * ciphertext. Only with `encrypted: 'folder'` or `'vault'`, for an app
+     * whose manifest says `encrypted_folders: {"open": true}` (the grant
+     * `files:e2e-plaintext`) - never for a `.fxe`. ABSENT otherwise.
+     *
+     * In a vault (`encrypted: 'vault'`) the browser reads the file from the
+     * vault's packs and writes a save as the vault's next generation, under
+     * the vault's write lock (one writer at a time). A save is refused -
+     * `failed` with `vault_locked` - while somebody else writes the vault, and
+     * with `vault_lock_lost` when this session's write lock ended before the
+     * save was committed: nothing was written, save again. The vault locked
+     * meanwhile (its keys left the browser): `unavailable`, and filex closes
+     * the app.
+     *
+     * What changes for the app: a read and a save are held whole in the page
+     * (at most LIMITS.maxEncryptedBytes); a save is written only over the file
+     * as it was opened (`failed` with `changed` when it changed meanwhile);
+     * `file.saveAs` answers `unavailable` (a copy elsewhere would leave the
+     * folder decrypted); the app's module (`engine.call`, `job.submit`) is
+     * never handed the file; `state.get` / `state.set` use a store of their
+     * own for this folder, sealed in the person's browser (the server keeps it
+     * and cannot read it; apart from the app's ordinary store, a little smaller
+     * as it is measured sealed). Everything the app holds is plaintext: keep it
+     * in the frame. In a folder whose names are encrypted too, `name` and
+     * `ext` are the decrypted name's - the server never sees them.
+     */
+    plaintext?: true;
 }
 
 export declare interface FilexApp {
     readonly session: Session;
     /** The file at `index` (default the first) the interface was opened with. */
     open(index?: number): Promise<OpenedFile>;
-    /** Save new content over an opened file. */
+    /**
+     * Save new content over an opened file. `through` (filex 0.56, editing
+     * together): the last log entry the saved document holds, so the session
+     * knows what is saved.
+     */
     save(data: SaveData, opts?: {
         index?: number;
         mime?: string;
+        through?: number;
     }): Promise<SaveResult>;
     /** Save a NEW file; filex asks the person where (its own folder picker). */
     saveAs(name: string, data: SaveData, mime?: string): Promise<SaveAsResult>;
@@ -120,13 +314,46 @@ export declare interface FilexApp {
      * filex asks the person first. `cancelled` when they say no.
      */
     download(name: string, data: SaveData, mime?: string): Promise<DownloadResult>;
+    /**
+     * Print a PDF (filex 0.55; the app needs `ui.print` in its manifest): a
+     * sandboxed frame may not open the print dialog, so filex prints it from
+     * its own page. filex asks the person every time, and the dialog opens on
+     * their click on filex's Allow; at most LIMITS.maxPrintBytes. filex 0.54
+     * and older answer `unknown_method`, and a host whose print page may not
+     * be shown `unavailable`: hand the PDF over with `download` then.
+     */
+    print(name: string, pdf: Blob | ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array>): Promise<PrintResult>;
+    /**
+     * Editing together (filex 0.56; the app's manifest says `"co_edit":
+     * {"open": true}`, granted as `files:co-edit`). filex seals what the app appends, orders it
+     * through its relay and hands every member the same entries in the same
+     * order (`coedit.entry` events after `subscribe`); the app never holds a
+     * key. `join` answering `unavailable` (filex 0.55, editing together off
+     * here, an encrypted file) means: edit alone. The member that started the
+     * session (`created`) puts the base document before anybody else may join.
+     */
+    coedit: {
+        join(index?: number): Promise<CoEditHello>;
+        subscribe(from: number): Promise<void>;
+        append(kind: CoEditKind, body: unknown): Promise<CoEditAppendResult>;
+        lease(op: 'acquire' | 'release', changesSeen: number): Promise<boolean>;
+        cursor(cursor: unknown): void;
+        putBlob(name: string, data: Blob | ArrayBuffer | ArrayBufferView): Promise<void>;
+        getBlob(name: string): Promise<ArrayBuffer>;
+        leave(): Promise<void>;
+    };
     /** Call the app's own module (`ui_call` export) with the opened files. */
     call<T = unknown>(method: string, params?: unknown): Promise<T>;
     /** Queue one of the app's actions on the opened files; answers the op. */
     submit(action: string, params?: Record<string, unknown>): Promise<{
         op: unknown;
     }>;
-    /** This person's small store for this app (JSON values, 8 KiB each). */
+    /**
+     * This person's small store for this app (JSON values, 8 KiB each). While
+     * the app holds a file of an encrypted folder in the clear
+     * (`FileInfo.plaintext`, filex 0.56) it is another store, sealed in the
+     * browser - apart from this one, and empty while the folder is locked.
+     */
     state: {
         get<T = unknown>(key: string): Promise<T | undefined>;
         set(key: string, value: unknown): Promise<void>;
@@ -176,7 +403,18 @@ export declare type HostEvent =
 /** The person closed the frame's surroundings; last chance to say so. */
 | 'close.request'
 /** An administrator installed a new version of this app: reload to use it. */
-| 'app.updated';
+| 'app.updated'
+/** Editing together: the next entry of the session's log, opened. `data: CoEditEntry`. */
+| 'coedit.entry'
+/** Editing together: another member's cursor (not kept). `data: CoEditCursor`. */
+| 'coedit.cursor'
+/**
+* Editing together: the host stopped handing entries over. `data:
+* CoEditDropped` - `gone`: the membership ended (join again); `broken`: an
+* entry did not check out (stop editing together). A connection that drops
+* for a moment is the host's own: it reconnects and says nothing.
+*/
+| 'coedit.dropped';
 
 /** What the host may ask the app (and wait for). */
 export declare type HostRequest = 
@@ -244,12 +482,35 @@ export declare const LIMITS: {
     readonly connectTimeoutMs: 10000;
     /** The largest file `ui.download` hands the person (streamed or not). */
     readonly maxDownloadBytes: number;
+    /**
+     * The largest PDF `ui.print` prints (filex 0.55). Lower than a download:
+     * a download can stream to disk, a print is held whole in the page (one
+     * Blob) until the print dialog has read it, and a document worth printing
+     * is far smaller.
+     */
+    readonly maxPrintBytes: number;
+    /**
+     * The largest file of an encrypted folder filex hands an app in the clear
+     * or takes back from it (filex 0.56, `FileInfo.plaintext`): it is
+     * decrypted and encrypted whole in the page, as filex's own explorer does
+     * for a file of this size.
+     */
+    readonly maxEncryptedBytes: number;
 };
 
 /** What the app may ask the host. Anything else is `unknown_method`. */
 export declare type Method = 'session.get' | 'file.read' | 'file.save' | 'file.saveAs' | 'ui.dirty' | 'ui.title' | 'ui.toast' | 'ui.confirm' | 'ui.close' | 'clipboard.write' | 'ui.download' | 'engine.call' | 'job.submit' | 'state.get' | 'state.set'
 /** 0.52.0: what the app's license says (a paid app from a store), `LicenseInfo`. */
-| 'license.get';
+| 'license.get'
+/** 0.55.0: filex prints a PDF the app hands it (`PrintParams`, grant `ui:print`). */
+| 'ui.print'
+/**
+* Editing together (`coedit.*`, task #189): the session's log the host
+* seals, orders through filex's relay and opens again. Defined in filex
+* 0.55, which answers each `unavailable`; offered from 0.56 to an app
+* granted `files:co-edit` (see `CoEditHello`). `unavailable` = edit alone.
+*/
+| 'coedit.join' | 'coedit.subscribe' | 'coedit.append' | 'coedit.lease' | 'coedit.cursor' | 'coedit.blob.put' | 'coedit.blob.get' | 'coedit.leave';
 
 export declare const METHODS: readonly Method[];
 
@@ -270,6 +531,31 @@ export declare interface PortMessage {
     v: number;
 }
 
+/**
+ * `ui.print` (filex 0.55.0): a PDF for the browser's print dialog. A
+ * sandboxed frame may not open that dialog (measured: Chromium ignores
+ * `print()` there and says so, Firefox ignores it), so filex prints the PDF
+ * from a page of its own, with the app's `ui:print` grant, never over
+ * LIMITS.maxPrintBytes. filex asks every time, above the frame, and the
+ * dialog opens only on the person's click on filex's Allow. The print dialog
+ * can save the PDF too, so `ui:print` is the same kind of grant as
+ * `ui:download`. filex 0.54 and older answer `unknown_method`.
+ */
+export declare interface PrintParams {
+    /** The document's name, for the question filex may ask - a name, not a path. */
+    name: string;
+    /** The PDF: a transferred ArrayBuffer or ReadableStream<Uint8Array>. */
+    data: ReadableStream<Uint8Array> | ArrayBuffer;
+    /** `application/pdf` when given; nothing else is printed. */
+    mime?: string;
+}
+
+export declare interface PrintResult {
+    /** The browser's print dialog was opened with the PDF. */
+    printed: true;
+    size: number;
+}
+
 /** `file.read` params. */
 export declare interface ReadParams {
     index?: number;
@@ -326,6 +612,12 @@ export declare interface SaveParams {
     /** A transferred ReadableStream<Uint8Array>, an ArrayBuffer or a string. */
     data: ReadableStream<Uint8Array> | ArrayBuffer | string;
     mime?: string;
+    /**
+     * 0.55.0, editing together: the last log entry (`CoEditEntry.seq`) the
+     * saved document holds, so the session knows what is saved. Ignored
+     * outside a session.
+     */
+    through?: number;
 }
 
 export declare interface SaveResult {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brftech/filex-app-ui",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "description": "filex app interface SDK: the bridge between an app's own sandboxed interface and filex (open, save, dirty, call the app's module)",
   "type": "module",
   "main": "./dist/filex-app-ui.js",

package/src/index.ts

@@ -36,6 +36,12 @@ import {
   type ToastParams,
   type DownloadResult,
   type LicenseInfo,
+  type PrintResult,
+  type CoEditHello,
+  type CoEditKind,
+  type CoEditAppendResult,
+  type CoEditLeaseResult,
+  type CoEditBlobGetResult,
 } from './protocol';
 
 export * from './protocol';
@@ -78,8 +84,12 @@ export interface FilexApp {
   readonly session: Session;
   /** The file at `index` (default the first) the interface was opened with. */
   open(index?: number): Promise<OpenedFile>;
-  /** Save new content over an opened file. */
-  save(data: SaveData, opts?: { index?: number; mime?: string }): Promise<SaveResult>;
+  /**
+   * Save new content over an opened file. `through` (filex 0.56, editing
+   * together): the last log entry the saved document holds, so the session
+   * knows what is saved.
+   */
+  save(data: SaveData, opts?: { index?: number; mime?: string; through?: number }): Promise<SaveResult>;
   /** Save a NEW file; filex asks the person where (its own folder picker). */
   saveAs(name: string, data: SaveData, mime?: string): Promise<SaveAsResult>;
   /** Unsaved changes, or not: filex asks before the person leaves them. */
@@ -97,11 +107,44 @@ export interface FilexApp {
    * filex asks the person first. `cancelled` when they say no.
    */
   download(name: string, data: SaveData, mime?: string): Promise<DownloadResult>;
+  /**
+   * Print a PDF (filex 0.55; the app needs `ui.print` in its manifest): a
+   * sandboxed frame may not open the print dialog, so filex prints it from
+   * its own page. filex asks the person every time, and the dialog opens on
+   * their click on filex's Allow; at most LIMITS.maxPrintBytes. filex 0.54
+   * and older answer `unknown_method`, and a host whose print page may not
+   * be shown `unavailable`: hand the PDF over with `download` then.
+   */
+  print(name: string, pdf: Blob | ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array>): Promise<PrintResult>;
+  /**
+   * Editing together (filex 0.56; the app's manifest says `"co_edit":
+   * {"open": true}`, granted as `files:co-edit`). filex seals what the app appends, orders it
+   * through its relay and hands every member the same entries in the same
+   * order (`coedit.entry` events after `subscribe`); the app never holds a
+   * key. `join` answering `unavailable` (filex 0.55, editing together off
+   * here, an encrypted file) means: edit alone. The member that started the
+   * session (`created`) puts the base document before anybody else may join.
+   */
+  coedit: {
+    join(index?: number): Promise<CoEditHello>;
+    subscribe(from: number): Promise<void>;
+    append(kind: CoEditKind, body: unknown): Promise<CoEditAppendResult>;
+    lease(op: 'acquire' | 'release', changesSeen: number): Promise<boolean>;
+    cursor(cursor: unknown): void;
+    putBlob(name: string, data: Blob | ArrayBuffer | ArrayBufferView): Promise<void>;
+    getBlob(name: string): Promise<ArrayBuffer>;
+    leave(): Promise<void>;
+  };
   /** Call the app's own module (`ui_call` export) with the opened files. */
   call<T = unknown>(method: string, params?: unknown): Promise<T>;
   /** Queue one of the app's actions on the opened files; answers the op. */
   submit(action: string, params?: Record<string, unknown>): Promise<{ op: unknown }>;
-  /** This person's small store for this app (JSON values, 8 KiB each). */
+  /**
+   * This person's small store for this app (JSON values, 8 KiB each). While
+   * the app holds a file of an encrypted folder in the clear
+   * (`FileInfo.plaintext`, filex 0.56) it is another store, sealed in the
+   * browser - apart from this one, and empty while the folder is locked.
+   */
   state: {
     get<T = unknown>(key: string): Promise<T | undefined>;
     set(key: string, value: unknown): Promise<void>;
@@ -301,7 +344,9 @@ function bridge(port: MessagePort, opts: ConnectOptions): FilexApp {
     },
     async save(data, o = {}) {
       const p = await payload(data);
-      return request<SaveResult>('file.save', { index: o.index ?? 0, data: p.data, mime: o.mime }, p.transfer);
+      const params: Record<string, unknown> = { index: o.index ?? 0, data: p.data, mime: o.mime };
+      if (typeof o.through === 'number') params.through = o.through;
+      return request<SaveResult>('file.save', params, p.transfer);
     },
     async saveAs(name, data, mime) {
       const p = await payload(data);
@@ -311,6 +356,40 @@ function bridge(port: MessagePort, opts: ConnectOptions): FilexApp {
       const p = await payload(data);
       return request<DownloadResult>('ui.download', { name, data: p.data, mime }, p.transfer);
     },
+    async print(name, pdf) {
+      const p = await payload(pdf);
+      return request<PrintResult>('ui.print', { name, data: p.data, mime: 'application/pdf' }, p.transfer);
+    },
+    coedit: {
+      join(index = 0) {
+        return request<CoEditHello>('coedit.join', { index });
+      },
+      subscribe(from: number) {
+        return request<void>('coedit.subscribe', { from });
+      },
+      append(kind: CoEditKind, body: unknown) {
+        return request<CoEditAppendResult>('coedit.append', { kind, body });
+      },
+      async lease(op: 'acquire' | 'release', changesSeen: number) {
+        const r = await request<CoEditLeaseResult>('coedit.lease', { op, changesSeen });
+        return !!r?.granted;
+      },
+      cursor(cursor: unknown) {
+        notify('coedit.cursor', { cursor });
+      },
+      async putBlob(name: string, data: Blob | ArrayBuffer | ArrayBufferView) {
+        const p = await payload(data);
+        if (!(p.data instanceof ArrayBuffer)) throw new FilexError({ code: 'invalid', message: 'a blob is bytes' });
+        await request<void>('coedit.blob.put', { name, data: p.data }, p.transfer);
+      },
+      async getBlob(name: string) {
+        const r = await request<CoEditBlobGetResult>('coedit.blob.get', { name });
+        return r.bytes;
+      },
+      async leave() {
+        await request<void>('coedit.leave');
+      },
+    },
     dirty(on) {
       notify('ui.dirty', { dirty: !!on });
     },