@brftech/filex-app-ui 0.53.0 → 0.55.0

package/dist/index.d.ts

@@ -6,6 +6,123 @@ 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. */
+export declare interface CoEditCursorParams {
+    cursor: unknown;
+}
+
+/** 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, a vault, a file
+ * that cannot be shared): the app edits alone.
+ */
+export declare interface CoEditHello {
+    session: string;
+    me: CoEditMember;
+    /** The last entry's seq (0: an empty log). */
+    head: number;
+    /** The last `changes` entry's seq. */
+    changesHead: number;
+    /** The last entry the file on the storage holds. */
+    savedThrough: number;
+}
+
+/** `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,6 +209,19 @@ 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.
+     *
+     * ⚠ filex 0.55 decrypts nothing for an app: the server holds such a file
+     * only as ciphertext and has no key, so `file.read` is refused
+     * (`failed` with `encrypted`), a save is refused, and `readOnly` is true.
+     * The explorer offers no app an encrypted file in the first place; the
+     * field is information, not a promise of plaintext.
+     */
+    encrypted?: 'folder' | 'vault' | 'file';
 }
 
 export declare interface FilexApp {
@@ -120,6 +250,32 @@ 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.55: defined, not offered - every call answers
+     * `unavailable`, and the app edits alone). 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.
+     */
+    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. */
@@ -176,7 +332,17 @@ 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 (the app fell
+* behind, or the connection dropped). `data: {from}` - subscribe again
+* from the last entry the app holds.
+*/
+| 'coedit.dropped';
 
 /** What the host may ask the app (and wait for). */
 export declare type HostRequest = 
@@ -244,12 +410,28 @@ 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;
 };
 
 /** 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'
+/**
+* 0.55.0, editing together (`coedit.*`, task #189): the session's log the
+* host seals, orders through filex's relay and opens again. Defined so an
+* app can be written against them; filex 0.55 offers no relay yet, so each
+* answers `unavailable` - edit alone then (see `CoEditHello`).
+*/
+| '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 +452,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 +533,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.53.0",
+  "version": "0.55.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';
@@ -97,6 +103,32 @@ 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.55: defined, not offered - every call answers
+   * `unavailable`, and the app edits alone). 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.
+   */
+  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. */
@@ -311,6 +343,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 });
     },

package/src/protocol.ts

@@ -52,7 +52,23 @@ export type Method =
   | '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'
+  /**
+   * 0.55.0, editing together (`coedit.*`, task #189): the session's log the
+   * host seals, orders through filex's relay and opens again. Defined so an
+   * app can be written against them; filex 0.55 offers no relay yet, so each
+   * answers `unavailable` - edit alone then (see `CoEditHello`).
+   */
+  | 'coedit.join'
+  | 'coedit.subscribe'
+  | 'coedit.append'
+  | 'coedit.lease'
+  | 'coedit.cursor'
+  | 'coedit.blob.put'
+  | 'coedit.blob.get'
+  | 'coedit.leave';
 
 export const METHODS: readonly Method[] = [
   'session.get',
@@ -71,6 +87,15 @@ export const METHODS: readonly Method[] = [
   'state.get',
   'state.set',
   'license.get',
+  'ui.print',
+  'coedit.join',
+  'coedit.subscribe',
+  'coedit.append',
+  'coedit.lease',
+  'coedit.cursor',
+  'coedit.blob.put',
+  'coedit.blob.get',
+  'coedit.leave',
 ];
 
 /** What the host tells the app, unasked. */
@@ -84,7 +109,17 @@ export 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 (the app fell
+   * behind, or the connection dropped). `data: {from}` - subscribe again
+   * from the last entry the app holds.
+   */
+  | 'coedit.dropped';
 
 /** What the host may ask the app (and wait for). */
 export type HostRequest =
@@ -178,6 +213,19 @@ export 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.
+   *
+   * ⚠ filex 0.55 decrypts nothing for an app: the server holds such a file
+   * only as ciphertext and has no key, so `file.read` is refused
+   * (`failed` with `encrypted`), a save is refused, and `readOnly` is true.
+   * The explorer offers no app an encrypted file in the first place; the
+   * field is information, not a promise of plaintext.
+   */
+  encrypted?: 'folder' | 'vault' | 'file';
 }
 
 /** What `session.get` answers — what the app knows about where it runs. */
@@ -221,6 +269,12 @@ export 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 interface SaveResult {
@@ -246,6 +300,143 @@ export interface DownloadResult {
   size: 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 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 interface PrintResult {
+  /** The browser's print dialog was opened with the PDF. */
+  printed: true;
+  size: number;
+}
+
+/* ── editing together (coedit.*, filex 0.55.0: defined, not offered) ────── */
+
+/** What a member appends: the editor's changes, a lock request, a release. */
+export type CoEditKind = 'changes' | 'lock' | 'release';
+
+/** A member of the session. */
+export 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.join` params: join (or start) the session of an opened file. */
+export interface CoEditJoinParams {
+  index?: number;
+}
+
+/**
+ * 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, a vault, a file
+ * that cannot be shared): the app edits alone.
+ */
+export interface CoEditHello {
+  session: string;
+  me: CoEditMember;
+  /** The last entry's seq (0: an empty log). */
+  head: number;
+  /** The last `changes` entry's seq. */
+  changesHead: number;
+  /** The last entry the file on the storage holds. */
+  savedThrough: number;
+}
+
+/** `coedit.subscribe` params: entries after `from` arrive as `coedit.entry`. */
+export interface CoEditSubscribeParams {
+  from: number;
+}
+
+/** `coedit.append` params: the host seals it and the relay places it. */
+export interface CoEditAppendParams {
+  kind: CoEditKind;
+  body: unknown;
+}
+
+export interface CoEditAppendResult {
+  /** Where it landed; it comes back as a `coedit.entry` too. */
+  seq: number;
+}
+
+/** `coedit.lease`: the changes lease (one writer at a time, one that has
+ *  seen every change). */
+export interface CoEditLeaseParams {
+  op: 'acquire' | 'release';
+  /** The seq of the last `changes` entry the app applied. */
+  changesSeen: number;
+}
+
+export interface CoEditLeaseResult {
+  granted: boolean;
+}
+
+/** `coedit.cursor` params: passed to the other members, not kept. */
+export interface CoEditCursorParams {
+  cursor: unknown;
+}
+
+/** `coedit.blob.put` / `coedit.blob.get`: the session's sealed blobs (the
+ *  base document, images added while editing). A name, not a path. */
+export interface CoEditBlobPutParams {
+  name: string;
+  data: ArrayBuffer;
+}
+
+export interface CoEditBlobGetParams {
+  name: string;
+}
+
+export interface CoEditBlobGetResult {
+  name: string;
+  bytes: ArrayBuffer;
+}
+
+interface CoEditEntryBase {
+  seq: number;
+  /** The relay's time, Unix ms - the same for every member. */
+  at: number;
+  client: string;
+}
+
+/** One entry of the session's log, opened and checked by filex. */
+export type CoEditEntry =
+  | (CoEditEntryBase & { kind: CoEditKind; body: unknown })
+  | (CoEditEntryBase & { kind: 'join'; member: CoEditMember })
+  | (CoEditEntryBase & { kind: 'leave' })
+  | (CoEditEntryBase & { kind: 'saved'; through: number });
+
+/** `coedit.cursor` event data. */
+export interface CoEditCursor {
+  client: string;
+  cursor: unknown;
+}
+
 /**
  * `file.saveAs`: a NEW file, in a folder the person picks in filex's own
  * folder dialog (the one its Move to… uses), which opens in the opened
@@ -325,6 +516,13 @@ export const LIMITS = {
   connectTimeoutMs: 10_000,
   /** The largest file `ui.download` hands the person (streamed or not). */
   maxDownloadBytes: 256 << 20,
+  /**
+   * 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.
+   */
+  maxPrintBytes: 64 << 20,
 } as const;
 
 /* ── guards ────────────────────────────────────────────────────────────── */