@nextcloud/files 3.0.1-beta.0 → 3.1.1

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) [![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,65 @@
+/**
+ * @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
+ * @param headers Optional additional headers to set for every request
+ */
+export declare const davGetClient: (remoteURL?: string, headers?: Record<string, 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

@@ -0,0 +1,99 @@
+/**
+ * @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 { 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: 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: View) => string;
+    /** Condition wether this action is shown or not */
+    enabled?: (files: Node[], view: View) => boolean;
+    /**
+     * Function executed on single file action
+     * @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: View, dir: string) => Promise<boolean | null>;
+    /**
+     * Function executed on multiple files action
+     * @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: View, dir: string) => Promise<(boolean | null)[]>;
+    /** This action order in the list */
+    order?: number;
+    /**
+     * 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: View) => boolean;
+    /**
+     * If defined, the returned html element will be
+     * appended before the actions menu.
+     */
+    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: 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 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;
+export declare const getFileActions: () => FileAction[];
+export {};

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/file.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @copyright Copyright (c) 2022 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 { FileType } from './fileType';
+import { Node } from './node';
+export declare class File extends Node {
+    get type(): FileType;
+}

package/dist/files/fileType.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @copyright Copyright (c) 2022 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/>.
+ *
+ */
+export declare enum FileType {
+    Folder = "folder",
+    File = "file"
+}

package/dist/files/folder.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @copyright Copyright (c) 2022 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 { FileType } from './fileType';
+import { Node } from './node';
+import { NodeData } from './nodeData';
+export declare class Folder extends Node {
+    constructor(data: NodeData);
+    get type(): FileType;
+    get extension(): string | null;
+    get mime(): string;
+}

package/dist/files/node.d.ts

@@ -0,0 +1,115 @@
+import { Permission } from '../permissions';
+import { FileType } from './fileType';
+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;
+    private _knownDavService;
+    constructor(data: NodeData, davService?: RegExp);
+    /**
+     * 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
+     */
+    get basename(): string;
+    /**
+     * Get this object's extension
+     */
+    get extension(): string | null;
+    /**
+     * Get the directory path leading to this object
+     * Will use the relative path to root if available
+     */
+    get dirname(): string;
+    /**
+     * Is it a file or a folder ?
+     */
+    abstract get type(): FileType;
+    /**
+     * Get the file mime
+     */
+    get mime(): string | undefined;
+    /**
+     * Get the file modification time
+     */
+    get mtime(): Date | undefined;
+    /**
+     * Get the file creation time
+     */
+    get crtime(): Date | undefined;
+    /**
+     * Get the file size
+     */
+    get size(): number | undefined;
+    /**
+     * Get the file attribute
+     */
+    get attributes(): Attribute;
+    /**
+     * Get the file permissions
+     */
+    get permissions(): Permission;
+    /**
+     * Get the file owner
+     */
+    get owner(): string | null;
+    /**
+     * Is this a dav-related ressource ?
+     */
+    get isDavRessource(): boolean;
+    /**
+     * Get the dav root of this object
+     */
+    get root(): string | null;
+    /**
+     * Get the absolute path of this object relative to the root
+     */
+    get path(): string;
+    /**
+     * 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
+     *
+     * @param {string} destination the new source.
+     * e.g. https://cloud.domain.com/remote.php/dav/files/emma/Photos/picture.jpg
+     */
+    move(destination: string): void;
+    /**
+     * 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.
+     */
+    private updateMtime;
+}

package/dist/files/nodeData.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @copyright Copyright (c) 2022 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 { Permission } from '../permissions';
+import { NodeStatus } from './node';
+export interface Attribute {
+    [key: string]: any;
+}
+export interface NodeData {
+    /** Unique ID */
+    id?: number;
+    /**
+     * URL to the ressource.
+     * e.g. https://cloud.domain.com/remote.php/dav/files/emma/Photos/picture.jpg
+     * or https://domain.com/Photos/picture.jpg
+     */
+    source: string;
+    /** Last modified time */
+    mtime?: Date;
+    /** Creation time */
+    crtime?: Date;
+    /** The mime type Optional for folders only */
+    mime?: string;
+    /** The node size type */
+    size?: number;
+    /** The node permissions */
+    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.
+     * It is highly recommended to provide that information.
+     * 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): string;
+export declare function parseFileSize(value: string, forceBinary?: boolean): number | null;