@brftech/filex-core 0.43.2 → 0.44.0

package/dist/index.d.ts

@@ -3507,6 +3507,8 @@ export declare function applyThemeToEl(el: HTMLElement, id: string, dark: boolea
  */
 export declare function applyToAllFolders(view: FolderViewDefault): void;
 
+declare type ArchiveCreateFormat = 'zip' | '7z' | 'tar' | 'tar.gz' | 'tar.bz2' | 'tar.xz';
+
 export declare interface ArchiveEntry {
     name: string;
     size: number;
@@ -3514,6 +3516,16 @@ export declare interface ArchiveEntry {
     lastModified?: number;
 }
 
+/**
+ * archiveFormatLabel — how an archive format is written wherever a person
+ * reads it: the create dialog, the admin Archives page, its provider cards.
+ *
+ * Upper case (ZIP, TAR.GZ, RAR), except 7z, which its own project writes in
+ * lower case. One rule in one place: the dialog wrote "7z" while the admin
+ * page wrote "7Z" for the same format (measured, 0.44.0 integration of #48).
+ */
+export declare function archiveFormatLabel(format: string): string;
+
 /** What the mint returns. Mirrors `archiveDownloadInfo` in the Go handler. */
 export declare interface ArchiveTicket {
     /** Path to navigate to. Server-relative, e.g. `/z/<token>`. */
@@ -3787,6 +3799,16 @@ export declare interface Capabilities {
     /** Longest life a new share link may be given, in days (0 = no ceiling).
      *  Read by the share dialogs so they offer only expiries the server keeps. */
     share_max_ttl_days?: number;
+    /** Archive creation policy. Absent on servers older than archive providers.
+     *  `allowed_formats` is what this server can actually make (every format
+     *  but a plain ZIP needs 7-Zip there); empty means it can make none, and
+     *  `encryption` says whether a password can be set. */
+    archive?: {
+        enabled: boolean;
+        default_format: ArchiveCreateFormat | '';
+        allowed_formats: ArchiveCreateFormat[];
+        encryption?: boolean;
+    };
     /** Is the caller a person (`'user'` — a session OR their own API token) or an
      *  integration (`'app'` — a host proxy, a bot, an MCP client)? The explorer
      *  reads it to decide whether to draw the identity-bearing surfaces; see
@@ -3840,6 +3862,23 @@ export declare interface Capabilities {
     };
 }
 
+/** The server's `coverage` object (sync.CatalogueCoverage). */
+export declare interface CatalogCoverage {
+    complete: boolean;
+    reason?: CoverageReason | string;
+    /** `lazy` for a lazily cataloged storage. */
+    mode?: string;
+    /** The lazy behaviour: `background` (A) or `on_open` (B). */
+    fill?: string;
+    catalogued_folders?: number;
+    pending_folders?: number;
+    watched_folders?: number;
+    max_watches?: number;
+    filler?: string;
+    held_back_folders?: number;
+    reconciles?: number;
+}
+
 export declare const ChoiceButtons: DefineComponent<__VLS_Props_10, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & {
 "update:modelValue": (v: string | string[]) => any;
 }, string, PublicProps, Readonly<__VLS_Props_10> & Readonly<{
@@ -4108,6 +4147,79 @@ export declare interface ContextAction {
     shortcutId?: string;
 }
 
+/** `storage_info` → storage name → its incomplete coverage (null = complete). */
+export declare function coverageByStorage(info: unknown): Record<string, CatalogCoverage | null>;
+
+/** A coverage object worth telling anybody about, or null. */
+export declare function coverageIncomplete(c: CatalogCoverage | null | undefined): CatalogCoverage | null;
+
+/** The sentence one storage's coverage is told in: a catalog key and its values. */
+export declare function coverageMessage(c: CatalogCoverage): {
+    key: string;
+    vars: Record<string, number>;
+};
+
+/** What the banner over a listing or a search says, and whether it offers an action. */
+export declare interface CoverageNotice {
+    key: string;
+    vars: Record<string, string | number>;
+    /** The storage the notice is about, when it is about one. */
+    storage?: string;
+    /** Offer "Catalog everything" (an administrator, behaviour B). */
+    offerCatalogAll: boolean;
+}
+
+/**
+ * The notice for what is on screen.
+ *
+ *   - A listing, or a search inside one storage: that storage's coverage.
+ *   - A search that spans every storage (the server searches them all when
+ *     the query is typed at a storage's root and there is more than one):
+ *     the names of the ones not fully cataloged.
+ *
+ * `admin` decides the action only; everybody reads the same sentence.
+ */
+export declare function coverageNotice(opts: {
+    map: Record<string, CatalogCoverage | null>;
+    adapter: string;
+    searching: boolean;
+    crossStorage: boolean;
+    admin: boolean;
+}): CoverageNotice | null;
+
+/**
+ * The share of the folders found so far that are cataloged, 0–99 while any
+ * is still waiting (a floor, so "100%" is never shown beside a notice that
+ * says the work is not done).
+ */
+export declare function coveragePercent(c: CatalogCoverage): number;
+
+/**
+ * catalogCoverage — how much of a storage its catalog covers, as the server
+ * says it, and the one set of rules every view draws that by.
+ *
+ * filex keeps a catalog of every storage, and search, folder sizes and drive
+ * usage are answered from it. While it does not cover a storage in full the
+ * server says so (docs/LAZY-CATALOGUE.md → "Coverage in the UI"):
+ *
+ *   - `first_scan`   — any storage whose first sync has not finished;
+ *   - `lazy_filling` — a lazily cataloged storage whose background pass is
+ *                      still going (behaviour A);
+ *   - `lazy_on_open` — a lazily cataloged storage that catalogs only the
+ *                      folders people open (behaviour B).
+ *
+ * The listing and search responses carry it per storage in `storage_info`,
+ * drive usage per row. A folder row whose own size leaves something out
+ * carries `size_partial` (see useLocale `formatNodeSize`).
+ *
+ * ⚠ One module for the whole explorer: the banner over a listing, the banner
+ * over search results and Home's drive cards read the SAME object through the
+ * SAME rules, so they cannot tell a person two different things about one
+ * storage.
+ */
+/** Why a storage's catalog is not complete. */
+export declare type CoverageReason = 'first_scan' | 'lazy_filling' | 'lazy_on_open';
+
 /**
  * A column store over `specs`, reading and writing through `backing`.
  *
@@ -4791,6 +4903,7 @@ export declare interface EndpointMap {
     capabilities: string | null;
     archiveList: string | null;
     archiveExtract: string | null;
+    archiveCreate: string | null;
     archiveAdd: string | null;
     copy: string | null;
     moveAsync: string | null;
@@ -4938,6 +5051,7 @@ export declare interface ExplorerConfig {
     capabilities?: string;
     archiveList?: string;
     archiveExtract?: string;
+    archiveCreate?: string;
     archiveAdd?: string;
     /** Recursive S3-side copy with "-copy" collision suffix (async). */
     copy?: string;
@@ -5460,6 +5574,13 @@ export declare interface ExplorerConfig {
          * about the person under a label about the drive.
          */
         usedBytes?: number;
+        /**
+         * `usedBytes` counts only part of the storage: its catalog does not cover
+         * all of it yet (the server's `coverage` beside the figure —
+         * lib/catalogCoverage). The card then draws it as a lower bound. Absent:
+         * the explorer uses what the last listing said about the storage.
+         */
+        usedPartial?: boolean;
     }>;
     /**
      * Desktop-shell hook — dragging rows OUT of the window onto the OS.
@@ -5629,6 +5750,13 @@ export declare interface FileNode {
     extension?: string;
     /** Bytes. 0 = directory. */
     size?: number;
+    /**
+     * The folder's size leaves something out: the catalog does not cover all of
+     * it yet (a lazily cataloged folder, or any folder while its storage's first
+     * sync runs). `size` is then a lower bound, or unknown when 0. Draw it with
+     * useLocale `formatNodeSize`, never `formatSize` (docs/LAZY-CATALOGUE.md).
+     */
+    size_partial?: boolean;
     /** Unix ms (backend "last_modified"). */
     last_modified?: number;
     /** MIME. */
@@ -6876,6 +7004,10 @@ export declare interface ManagerResponse {
      *  list is not the whole answer. Absent on other actions and on servers
      *  older than the flag. */
     truncated?: boolean;
+    /** Every storage the caller can open, with how much of it the catalog
+     *  covers (`coverage`, absent when all of it — lib/catalogCoverage). Absent
+     *  on servers older than the lazy catalog. */
+    storage_info?: StorageInfo[];
 }
 
 /** True when the folder has an operator escrow slot. */
@@ -7237,6 +7369,7 @@ export declare interface Operation {
     error: string | null;
     errorDetail: string | null;
     queued: boolean;
+    cancelling: boolean;
     doneCount: number | null;
     totalCount: number | null;
     uploadedBytes: number | null;
@@ -7276,6 +7409,8 @@ export declare interface OperationInput {
     errorDetail?: string | null;
     /** Queue op accepted but not started yet ("Queued"). */
     queued?: boolean;
+    /** Cancellation was accepted and the worker is stopping/cleaning up. */
+    cancelling?: boolean;
     /** Progress counters for queue ops (3/5 items). */
     doneCount?: number;
     totalCount?: number;
@@ -7326,7 +7461,7 @@ export declare interface OperationInput {
  */
 /** `plugin` — an app-plugin job (docs/APP-PLUGINS-API.md); also what any
  *  queue kind this package has no drawing for is shown as. */
-export declare type OperationKind = 'upload' | 'copy' | 'move' | 'delete' | 'convert' | 'archive' | 'plugin' | 'trash';
+export declare type OperationKind = 'upload' | 'copy' | 'move' | 'delete' | 'convert' | 'archive' | 'archive-create' | 'archive-extract' | 'plugin' | 'trash';
 
 export declare const OperationsCenter: DefineComponent<__VLS_Props_31, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_31> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {
 rootEl: HTMLDivElement;
@@ -7604,7 +7739,7 @@ export declare interface PendingOp {
     id: number;
     op_type: PendingOpType;
     /** `cancelled` — somebody stopped it (POST /ops/{id}/cancel). */
-    status: 'pending' | 'running' | 'done' | 'error' | 'cancelled';
+    status: 'pending' | 'running' | 'cancelling' | 'done' | 'error' | 'cancelled';
     progress_total: number;
     progress_done: number;
     /** Running cross-storage transfer's bytes (issue #27); absent otherwise. */
@@ -7619,6 +7754,7 @@ export declare interface PendingOp {
     error_code?: string;
     /** The engine a job needed and the server lacks (`error_code: engine_missing`). */
     error_engine?: string;
+    cancellable: boolean;
     started_at: string | null;
     finished_at: string | null;
     created_at: string | null;
@@ -7635,14 +7771,15 @@ export declare interface PendingOp {
 /** Server-side PendingOp DTO (mirror of Modules\FishApp\Models\PendingOp::toApiArray). */
 export declare interface PendingOpDto {
     id: number;
-    op_type: 'copy' | 'move' | 'delete';
-    status: 'pending' | 'running' | 'done' | 'error';
+    op_type: 'copy' | 'move' | 'delete' | 'archive-create' | 'archive-extract';
+    status: 'pending' | 'running' | 'cancelling' | 'done' | 'error' | 'cancelled';
     progress_total: number;
     progress_done: number;
     target_path: string | null;
     source_dir: string | null;
     source_count: number;
     error_message: string | null;
+    cancellable: boolean;
     started_at: string | null;
     finished_at: string | null;
     created_at: string | null;
@@ -10106,6 +10243,13 @@ export declare const StorageFields: DefineComponent<__VLS_Props_39, {}, {}, {},
  */
 export declare type StorageFieldType = 'string' | 'int' | 'bool' | 'password' | 'select';
 
+/** One entry of a listing's `storage_info`. */
+export declare interface StorageInfo {
+    name: string;
+    read_only?: boolean;
+    coverage?: CatalogCoverage | null;
+}
+
 /** A configured storage, as `GET /api/admin/storages` returns it. */
 export declare interface StorageRow {
     id: number;
@@ -11200,12 +11344,29 @@ export declare function useFileApi(config: ExplorerConfig): {
     revokeShare: (uuid: string) => Promise<{
         success: boolean;
     }>;
-    archiveList: (path: string) => Promise<{
+    archiveList: (path: string, password?: string) => Promise<{
         entries: ArchiveEntry[];
     }>;
-    archiveExtract: (path: string, members?: string[]) => Promise<{
-        keys: string[];
-        count: number;
+    archiveExtract: (path: string, options?: {
+        members?: string[];
+        password?: string;
+        dest?: string;
+    }) => Promise<{
+        op?: PendingOpDto;
+        keys?: string[];
+        count?: number;
+    }>;
+    archiveCreate: (payload: {
+        dest: string;
+        sources: string[];
+        format: ArchiveCreateFormat;
+        password?: string;
+        encrypt_filenames?: boolean;
+        compression?: number;
+        solid?: boolean;
+        dictionary_size_mb?: number;
+    }) => Promise<{
+        op: PendingOpDto;
     }>;
     archiveAdd: (path: string, files: Array<{
         name: string;
@@ -11278,6 +11439,14 @@ localeRef: Ref<LocaleCode | string> | (() => LocaleCode | string)): {
         foreign(text: string): string;
     };
     formatSize: (bytes: number | undefined | null) => string;
+    formatNodeSize: (n: {
+        size?: number | null;
+        size_partial?: boolean;
+    } | null | undefined) => string;
+    nodeSizeHint: (n: {
+        size?: number | null;
+        size_partial?: boolean;
+    } | null | undefined) => string | undefined;
     formatDate: (ms: number | undefined | null, opts?: {
         time?: boolean;
     }) => string;
@@ -11398,6 +11567,7 @@ export declare function useOperations(): {
     error: string | null;
     errorDetail: string | null;
     queued: boolean;
+    cancelling: boolean;
     doneCount: number | null;
     totalCount: number | null;
     uploadedBytes: number | null;
@@ -11418,6 +11588,7 @@ export declare function useOperations(): {
     error: string | null;
     errorDetail: string | null;
     queued: boolean;
+    cancelling: boolean;
     doneCount: number | null;
     totalCount: number | null;
     uploadedBytes: number | null;
@@ -11439,6 +11610,7 @@ export declare function useOperations(): {
     error: string | null;
     errorDetail: string | null;
     queued: boolean;
+    cancelling: boolean;
     doneCount: number | null;
     totalCount: number | null;
     uploadedBytes: number | null;
@@ -11459,6 +11631,7 @@ export declare function useOperations(): {
     error: string | null;
     errorDetail: string | null;
     queued: boolean;
+    cancelling: boolean;
     doneCount: number | null;
     totalCount: number | null;
     uploadedBytes: number | null;
@@ -11490,7 +11663,7 @@ export declare function usePendingOps(config: ExplorerConfig, api: FileApi, opts
     ops: Ref<    {
     id: number;
     op_type: PendingOpType;
-    status: "pending" | "running" | "done" | "error" | "cancelled";
+    status: "pending" | "running" | "cancelling" | "done" | "error" | "cancelled";
     progress_total: number;
     progress_done: number;
     bytes_total?: number | undefined;
@@ -11501,6 +11674,7 @@ export declare function usePendingOps(config: ExplorerConfig, api: FileApi, opts
     error_message: string | null;
     error_code?: string | undefined;
     error_engine?: string | undefined;
+    cancellable: boolean;
     started_at: string | null;
     finished_at: string | null;
     created_at: string | null;
@@ -11514,7 +11688,7 @@ export declare function usePendingOps(config: ExplorerConfig, api: FileApi, opts
     }[], PendingOp[] | {
     id: number;
     op_type: PendingOpType;
-    status: "pending" | "running" | "done" | "error" | "cancelled";
+    status: "pending" | "running" | "cancelling" | "done" | "error" | "cancelled";
     progress_total: number;
     progress_done: number;
     bytes_total?: number | undefined;
@@ -11525,6 +11699,7 @@ export declare function usePendingOps(config: ExplorerConfig, api: FileApi, opts
     error_message: string | null;
     error_code?: string | undefined;
     error_engine?: string | undefined;
+    cancellable: boolean;
     started_at: string | null;
     finished_at: string | null;
     created_at: string | null;