@nextcloud/files 3.0.0-beta.9 → 3.0.0

package/README.md

@@ -1,3 +1,55 @@
-# @nextcloud/files [![npm last version](https://img.shields.io/npm/v/@nextcloud/files.svg?style=flat-square)](https://www.npmjs.com/package/@nextcloud/files) ![Codecov](https://img.shields.io/codecov/c/github/nextcloud/nextcloud-files?style=flat-square)
+# @nextcloud/files
+[![npm last version](https://img.shields.io/npm/v/@nextcloud/files.svg?style=flat-square)](https://www.npmjs.com/package/@nextcloud/files) [![Code coverage](https://img.shields.io/codecov/c/github/nextcloud-libraries/nextcloud-files?style=flat-square)](https://app.codecov.io/gh/nextcloud-libraries/nextcloud-files) [![Project documentation](https://img.shields.io/badge/documentation-online-blue?style=flat-square)](https://nextcloud-libraries.github.io/nextcloud-files/)
 
 Nextcloud Files helpers for Nextcloud apps and libraries
+
+## Usage example
+
+### Using WebDAV to query favorite nodes
+
+```ts
+import { davGetClient, davRootPath, getFavoriteNodes } from '@nextcloud/files'
+
+const client = davGetClient()
+// query favorites for the root folder (meaning all favorites)
+const favorites = await getFavoriteNodes(client)
+// which is the same as writing:
+const favorites = await getFavoriteNodes(client, '/', davRootPath)
+```
+
+### Using WebDAV to list all nodes in directory
+
+```ts
+import {
+    davGetClient,
+    davGetDefaultPropfind,
+    davResultToNode,
+    davRootPath,
+    davRemoteURL
+} from '@nextcloud/files'
+
+// Get the DAV client for the default remote
+const client = davGetClient()
+// which is the same as writing
+const client = davGetClient(davRemoteURL)
+// of cause you can also configure another WebDAV remote
+const client = davGetClient('https://example.com/dav')
+
+const path = '/my-folder/' // the directory you want to list
+
+// Query the directory content using the webdav library
+// `davRootPath` is the files root, for Nextcloud this is '/files/USERID', by default the current user is used
+const results = client.getDirectoryContents(`${davRootPath}${path}`, {
+    details: true,
+    // Query all required properties for a Node
+    data: davGetDefaultPropfind()
+})
+
+// Convert the result to an array of Node
+const nodes = results.data.map((result) => davResultToNode(r))
+// If you specified a different root in the `getDirectoryContents` you must add this also on the `davResultToNode` call:
+const nodes = results.data.map((result) => davResultToNode(r, myRoot))
+// Same if you used a different remote URL:
+const nodes = results.data.map((result) => davResultToNode(r, myRoot, myRemoteURL))
+
+```

package/dist/dav/dav.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @copyright Copyright (c) 2023 John Molakvoæ <skjnldsv@protonmail.com>
+ *
+ * @author John Molakvoæ <skjnldsv@protonmail.com>
+ * @author Ferdinand Thiessen <opensource@fthiessen.de>
+ *
+ * @license AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+import type { FileStat, WebDAVClient } from 'webdav';
+import type { Node } from '../files/node';
+/**
+ * The DAV root path for the current user
+ */
+export declare const davRootPath: string;
+/**
+ * The DAV remote URL used as base URL for the WebDAV client
+ */
+export declare const davRemoteURL: string;
+/**
+ * Get a WebDAV client configured to include the Nextcloud request token
+ *
+ * @param remoteURL The DAV server remote URL
+ */
+export declare const davGetClient: (remoteURL?: string) => WebDAVClient;
+/**
+ * Use WebDAV to query for favorite Nodes
+ *
+ * @param davClient The WebDAV client to use for performing the request
+ * @param path Base path for the favorites, if unset all favorites are queried
+ * @param davRoot The root path for the DAV user (defaults to `davRootPath`)
+ * @example
+ * ```js
+ * import { davGetClient, davRootPath, getFavoriteNodes } from '@nextcloud/files'
+ *
+ * const client = davGetClient()
+ * // query favorites for the root
+ * const favorites = await getFavoriteNodes(client)
+ * // which is the same as writing:
+ * const favorites = await getFavoriteNodes(client, '/', davRootPath)
+ * ```
+ */
+export declare const getFavoriteNodes: (davClient: WebDAVClient, path?: string, davRoot?: string) => Promise<Node[]>;
+/**
+ * Covert DAV result `FileStat` to `Node`
+ *
+ * @param node The DAV result
+ * @param filesRoot The DAV files root path
+ * @param remoteURL The DAV server remote URL (same as on `davGetClient`)
+ */
+export declare const davResultToNode: (node: FileStat, filesRoot?: string, remoteURL?: string) => Node;

package/dist/dav/davPermissions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse the webdav permission string to a permission enum
+ *
+ * @param permString The DAV permission string
+ */
+export declare const davParsePermissions: (permString?: string) => number;

package/dist/dav/davProperties.d.ts

@@ -0,0 +1,57 @@
+export type DavProperty = {
+    [key: string]: string;
+};
+export declare const defaultDavProperties: string[];
+export declare const defaultDavNamespaces: {
+    d: string;
+    nc: string;
+    oc: string;
+    ocs: string;
+};
+/**
+ * Register custom DAV properties
+ *
+ * Can be used if your app introduces custom DAV properties, so e.g. the files app can make use of it.
+ *
+ * @param prop The property
+ * @param namespace The namespace of the property
+ */
+export declare const registerDavProperty: (prop: string, namespace?: DavProperty) => boolean;
+/**
+ * Get the registered dav properties
+ */
+export declare const getDavProperties: () => string;
+/**
+ * Get the registered dav namespaces
+ */
+export declare const getDavNameSpaces: () => string;
+/**
+ * Get the default PROPFIND request body
+ */
+export declare const davGetDefaultPropfind: () => string;
+/**
+ * Get the REPORT body to filter for favorite nodes
+ */
+export declare const davGetFavoritesReport: () => string;
+/**
+ * Get the SEARCH body to search for recently modified files
+ *
+ * @param lastModified Oldest timestamp to include (Unix timestamp)
+ * @example
+ * ```ts
+ * // SEARCH for recent files need a different DAV endpoint
+ * const client = davGetClient(generateRemoteUrl('dav'))
+ * // Timestamp of last week
+ * const lastWeek = Math.round(Date.now() / 1000) - (60 * 60 * 24 * 7)
+ * const contentsResponse = await client.getDirectoryContents(path, {
+ *     details: true,
+ *     data: davGetRecentSearch(lastWeek),
+ *     headers: {
+ *         method: 'SEARCH',
+ *         'Content-Type': 'application/xml; charset=utf-8',
+ *     },
+ *     deep: true,
+ * }) as ResponseDataDetailed<FileStat[]>
+ * ```
+ */
+export declare const davGetRecentSearch: (lastModified: number) => string;

package/dist/fileAction.d.ts

@@ -1,5 +1,5 @@
 /**
- * @copyright Copyright (c) 2021 John Molakvoæ <skjnldsv@protonmail.com>
+ * @copyright Copyright (c) 2023 John Molakvoæ <skjnldsv@protonmail.com>
  *
  * @author John Molakvoæ <skjnldsv@protonmail.com>
  *
@@ -19,57 +19,79 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  *
  */
-import { Node } from "./files/node";
+import { Node } from './files/node';
+import { View } from './navigation/view';
+export declare enum DefaultType {
+    DEFAULT = "default",
+    HIDDEN = "hidden"
+}
 interface FileActionData {
     /** Unique ID */
     id: string;
     /** Translatable string displayed in the menu */
-    displayName: (files: Node[], view: any) => string;
+    displayName: (files: Node[], view: View) => string;
+    /** Translatable title for of the action */
+    title?: (files: Node[], view: View) => string;
     /** Svg as inline string. <svg><path fill="..." /></svg> */
-    iconSvgInline: (files: Node[], view: any) => string;
+    iconSvgInline: (files: Node[], view: View) => string;
     /** Condition wether this action is shown or not */
-    enabled?: (files: Node[], view: any) => boolean;
+    enabled?: (files: Node[], view: View) => boolean;
     /**
      * Function executed on single file action
-     * @returns true if the action was executed successfully,
+     * @return true if the action was executed successfully,
      * false otherwise and null if the action is silent/undefined.
      * @throws Error if the action failed
      */
-    exec: (file: Node, view: any, dir: string) => Promise<boolean | null>;
+    exec: (file: Node, view: View, dir: string) => Promise<boolean | null>;
     /**
      * Function executed on multiple files action
-     * @returns true if the action was executed successfully,
+     * @return true if the action was executed successfully,
      * false otherwise and null if the action is silent/undefined.
      * @throws Error if the action failed
      */
-    execBatch?: (files: Node[], view: any, dir: string) => Promise<(boolean | null)[]>;
+    execBatch?: (files: Node[], view: View, dir: string) => Promise<(boolean | null)[]>;
     /** This action order in the list */
     order?: number;
-    /** Make this action the default */
-    default?: boolean;
+    /**
+     * This action's parent id in the list.
+     * If none found, will be displayed as a top-level action.
+     */
+    parent?: string;
+    /**
+     * Make this action the default.
+     * If multiple actions are default, the first one
+     * will be used. The other ones will be put as first
+     * entries in the actions menu iff DefaultType.Hidden is not used.
+     * A DefaultType.Hidden action will never be shown
+     * in the actions menu even if another action takes
+     * its place as default.
+     */
+    default?: DefaultType;
     /**
      * If true, the renderInline function will be called
      */
-    inline?: (file: Node, view: any) => boolean;
+    inline?: (file: Node, view: View) => boolean;
     /**
      * If defined, the returned html element will be
      * appended before the actions menu.
      */
-    renderInline?: (file: Node, view: any) => HTMLElement;
+    renderInline?: (file: Node, view: View) => Promise<HTMLElement | null>;
 }
 export declare class FileAction {
     private _action;
     constructor(action: FileActionData);
     get id(): string;
-    get displayName(): (files: Node[], view: any) => string;
-    get iconSvgInline(): (files: Node[], view: any) => string;
-    get enabled(): ((files: Node[], view: any) => boolean) | undefined;
-    get exec(): (file: Node, view: any, dir: string) => Promise<boolean | null>;
-    get execBatch(): ((files: Node[], view: any, dir: string) => Promise<(boolean | null)[]>) | undefined;
+    get displayName(): (files: Node[], view: View) => string;
+    get title(): ((files: Node[], view: View) => string) | undefined;
+    get iconSvgInline(): (files: Node[], view: View) => string;
+    get enabled(): ((files: Node[], view: View) => boolean) | undefined;
+    get exec(): (file: Node, view: View, dir: string) => Promise<boolean | null>;
+    get execBatch(): ((files: Node[], view: View, dir: string) => Promise<(boolean | null)[]>) | undefined;
     get order(): number | undefined;
-    get default(): boolean | undefined;
-    get inline(): ((file: Node, view: any) => boolean) | undefined;
-    get renderInline(): ((file: Node, view: any) => HTMLElement) | undefined;
+    get parent(): string | undefined;
+    get default(): DefaultType | undefined;
+    get inline(): ((file: Node, view: View) => boolean) | undefined;
+    get renderInline(): ((file: Node, view: View) => Promise<HTMLElement | null>) | undefined;
     private validateAction;
 }
 export declare const registerFileAction: (action: FileAction) => void;

package/dist/fileListHeaders.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @copyright Copyright (c) 2023 John Molakvoæ <skjnldsv@protonmail.com>
+ *
+ * @author John Molakvoæ <skjnldsv@protonmail.com>
+ *
+ * @license AGPL-3.0-or-later
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+import { Folder } from './files/folder';
+import { View } from './navigation/view';
+export interface HeaderData {
+    /** Unique ID */
+    id: string;
+    /** Order */
+    order: number;
+    /** Condition wether this header is shown or not */
+    enabled?: (folder: Folder, view: View) => boolean;
+    /** Executed when file list is initialized */
+    render: (el: HTMLElement, folder: Folder, view: View) => void;
+    /** Executed when root folder changed */
+    updated(folder: Folder, view: View): any;
+}
+export declare class Header {
+    private _header;
+    constructor(header: HeaderData);
+    get id(): string;
+    get order(): number;
+    get enabled(): ((folder: Folder, view: View) => boolean) | undefined;
+    get render(): (el: HTMLElement, folder: Folder, view: View) => void;
+    get updated(): (folder: Folder, view: View) => any;
+    private validateHeader;
+}
+export declare const registerFileListHeaders: (header: Header) => void;
+export declare const getFileListHeaders: () => Header[];

package/dist/files/folder.d.ts

@@ -21,7 +21,7 @@
  */
 import { FileType } from './fileType';
 import { Node } from './node';
-import NodeData from './nodeData';
+import { NodeData } from './nodeData';
 export declare class Folder extends Node {
     constructor(data: NodeData);
     get type(): FileType;

package/dist/files/node.d.ts

@@ -1,6 +1,16 @@
 import { Permission } from '../permissions';
 import { FileType } from './fileType';
-import NodeData, { Attribute } from './nodeData';
+import { Attribute, NodeData } from './nodeData';
+export declare enum NodeStatus {
+    /** This is a new node and it doesn't exists on the filesystem yet */
+    NEW = "new",
+    /** This node has failed and is unavailable  */
+    FAILED = "failed",
+    /** This node is currently loading or have an operation in progress */
+    LOADING = "loading",
+    /** This node is locked and cannot be modified */
+    LOCKED = "locked"
+}
 export declare abstract class Node {
     private _data;
     private _attributes;
@@ -10,6 +20,10 @@ export declare abstract class Node {
      * Get the source url to this object
      */
     get source(): string;
+    /**
+     * Get the encoded source url to this object for requests purposes
+     */
+    get encodedSource(): string;
     /**
      * Get this object name
      */
@@ -68,9 +82,18 @@ export declare abstract class Node {
      */
     get path(): string;
     /**
-     * Get the file id if defined in attributes
+     * Get the node id if defined.
+     * Will look for the fileid in attributes if undefined.
      */
     get fileid(): number | undefined;
+    /**
+     * Get the node status.
+     */
+    get status(): NodeStatus | undefined;
+    /**
+     * Set the node status.
+     */
+    set status(status: NodeStatus | undefined);
     /**
      * Move the node to a new destination
      *
@@ -81,6 +104,12 @@ export declare abstract class Node {
     /**
      * Rename the node
      * This aliases the move method for easier usage
+     *
+     * @param basename The new name of the node
+     */
+    rename(basename: string): void;
+    /**
+     * Update the mtime if exists.
      */
-    rename(basename: any): void;
+    private updateMtime;
 }

package/dist/files/nodeData.d.ts

@@ -19,11 +19,12 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  *
  */
-import { Permission } from "../permissions";
+import { Permission } from '../permissions';
+import { NodeStatus } from './node';
 export interface Attribute {
     [key: string]: any;
 }
-export default interface NodeData {
+export interface NodeData {
     /** Unique ID */
     id?: number;
     /**
@@ -36,7 +37,7 @@ export default interface NodeData {
     mtime?: Date;
     /** Creation time */
     crtime?: Date;
-    /** The mime type */
+    /** The mime type Optional for folders only */
     mime?: string;
     /** The node size type */
     size?: number;
@@ -44,6 +45,7 @@ export default interface NodeData {
     permissions?: Permission;
     /** The owner  UID of this node */
     owner: string | null;
+    /** The node attributes */
     attributes?: Attribute;
     /**
      * The absolute root of the home relative to the service.
@@ -51,9 +53,20 @@ export default interface NodeData {
      * e.g. /files/emma
      */
     root?: string;
+    /** The node status */
+    status?: NodeStatus;
 }
+/**
+ * Check if a node source is from a specific DAV service
+ *
+ * @param source The source to check
+ * @param davService Pattern to check if source is DAV ressource
+ */
 export declare const isDavRessource: (source: string, davService: RegExp) => boolean;
 /**
  * Validate Node construct data
+ *
+ * @param data The node data
+ * @param davService Pattern to check if source is DAV ressource
  */
 export declare const validateData: (data: NodeData, davService: RegExp) => void;

package/dist/humanfilesize.d.ts

@@ -23,7 +23,21 @@
 /**
  * Format a file size in a human-like format. e.g. 42GB
  *
+ * The default for Nextcloud is like Windows using binary sizes but showing decimal units,
+ * meaning 1024 bytes will show as 1KB instead of 1KiB or like on Apple 1.02 KB
+ *
  * @param size in bytes
  * @param skipSmallSizes avoid rendering tiny sizes and return '< 1 KB' instead
+ * @param binaryPrefixes True if size binary prefixes like `KiB` should be used as per IEC 80000-13
+ * @param base1000 Set to true to use base 1000 as per SI or used by Apple (default is base 1024 like Linux or Windows)
+ */
+export declare function formatFileSize(size: number | string, skipSmallSizes?: boolean, binaryPrefixes?: boolean, base1000?: boolean): string;
+/**
+ * Returns a file size in bytes from a humanly readable string
+ * Note: `b` and `B` are both parsed as bytes and not as bit or byte.
+ *
+ * @param  {string} value file size in human-readable format
+ * @param  {boolean} forceBinary for backwards compatibility this allows values to be base 2 (so 2KB means 2048 bytes instead of 2000 bytes)
+ * @return {number} or null if string could not be parsed
  */
-export declare function formatFileSize(size: number | string, skipSmallSizes?: boolean, binaryPrefixes?: boolean): string;
+export declare function parseFileSize(value: string, forceBinary?: boolean): number | null;