grommunio / grommunio-web

plugins/filesbackendSeafile/php/Model/AccountStoreV1Encoder.php

Indentation +43 added lines, -43 removed lines

@@ -7,48 +7,48 @@
  */
 class AccountStoreV1Encoder
 {
-    /**
-     * Encode an account setting value
-     *
-     * {@see AccountStore::encryptBackendConfigProperty()}
-     *
-     * @param string $value
-     * @return string encoded
-     */
-    public static function encode(string $value): string
-    {
-        $nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
-        $encrypted = sodium_crypto_secretbox($value, $nonce, hex2bin(FILES_ACCOUNTSTORE_V1_SECRET_KEY));
-        return bin2hex($nonce) . bin2hex($encrypted);
-    }
+	/**
+	 * Encode an account setting value
+	 *
+	 * {@see AccountStore::encryptBackendConfigProperty()}
+	 *
+	 * @param string $value
+	 * @return string encoded
+	 */
+	public static function encode(string $value): string
+	{
+		$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
+		$encrypted = sodium_crypto_secretbox($value, $nonce, hex2bin(FILES_ACCOUNTSTORE_V1_SECRET_KEY));
+		return bin2hex($nonce) . bin2hex($encrypted);
+	}
 
-    /**
-     * Decode an encoded account setting value
-     *
-     * {@see AccountStore::decryptBackendConfigProperty()}
-     *
-     * @param string $valueInHex
-     * @return string decoded
-     */
-    public static function decode(string $valueInHex): string
-    {
-        $value = hex2bin($valueInHex);
-        if (!is_string($value)) {
-            throw new \UnexpectedValueException(sprintf('Not an envelope of an encrypted value. Raw binary length of envelope is %d.', strlen($valueInHex)));
-        }
-        $nonce = substr($value, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
-        if (!is_string($nonce) || strlen($nonce) !== SODIUM_CRYPTO_SECRETBOX_NONCEBYTES) {
-            throw new \UnexpectedValueException(sprintf('Not an encrypted value. Raw binary length is %d which is below %d.', strlen($value), SODIUM_CRYPTO_SECRETBOX_NONCEBYTES));
-        }
-        $encrypted = substr($value, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, strlen($value));
-        if (!is_string($encrypted)) {
-            throw new \UnexpectedValueException(sprintf('Not an encrypted value. Raw binary length is %d.', strlen($value)));
-        }
-        $result = sodium_crypto_secretbox_open($encrypted, $nonce, hex2bin(FILES_ACCOUNTSTORE_V1_SECRET_KEY));
-        // Decryption failed, password might have changed
-        if (false === $result) {
-            throw new \UnexpectedValueException("invalid password");
-        }
-        return $result;
-    }
+	/**
+	 * Decode an encoded account setting value
+	 *
+	 * {@see AccountStore::decryptBackendConfigProperty()}
+	 *
+	 * @param string $valueInHex
+	 * @return string decoded
+	 */
+	public static function decode(string $valueInHex): string
+	{
+		$value = hex2bin($valueInHex);
+		if (!is_string($value)) {
+			throw new \UnexpectedValueException(sprintf('Not an envelope of an encrypted value. Raw binary length of envelope is %d.', strlen($valueInHex)));
+		}
+		$nonce = substr($value, 0, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES);
+		if (!is_string($nonce) || strlen($nonce) !== SODIUM_CRYPTO_SECRETBOX_NONCEBYTES) {
+			throw new \UnexpectedValueException(sprintf('Not an encrypted value. Raw binary length is %d which is below %d.', strlen($value), SODIUM_CRYPTO_SECRETBOX_NONCEBYTES));
+		}
+		$encrypted = substr($value, SODIUM_CRYPTO_SECRETBOX_NONCEBYTES, strlen($value));
+		if (!is_string($encrypted)) {
+			throw new \UnexpectedValueException(sprintf('Not an encrypted value. Raw binary length is %d.', strlen($value)));
+		}
+		$result = sodium_crypto_secretbox_open($encrypted, $nonce, hex2bin(FILES_ACCOUNTSTORE_V1_SECRET_KEY));
+		// Decryption failed, password might have changed
+		if (false === $result) {
+			throw new \UnexpectedValueException("invalid password");
+		}
+		return $result;
+	}
 }

plugins/filesbackendSeafile/php/class.pluginseafile.php

Indentation +2 added lines, -2 removed lines

@@ -8,7 +8,7 @@ 
 final class PluginFilesbackendSeafile extends Plugin
 {
 
-    /**
+	/**
 	 * Called to initialize the plugin and register for hooks.
 	 *
 	 * @return void
@@ -30,7 +30,7 @@ 
 			case 'server.core.settings.init.before':
 				$this->onBeforeSettingsInit($data);
 				break;
-            default:
+			default:
 		}
 	}
 

plugins/filesbackendSeafile/php/lib/seafapi/SeafileApi.php

Indentation +1583 added lines, -1583 removed lines

@@ -24,1587 +24,1587 @@
  */
 final class SeafileApi
 {
-    public const USER_PREFIX_AUTH_TOKEN = '@auth:token:';
-
-    public const TYPE_DIR = 'dir';
-    public const TYPE_FILE = 'file';
-    public const TYPE_REPO = 'repo';
-    public const TYPE_SREPO = 'srepo';
-    public const TYPE_GREPO = 'grepo';
-
-    public const TYPES = self::TYPES_FILE + self::TYPES_DIR_LIKE;
-    public const TYPES_DIR_LIKE = self::TYPES_DIR + self::TYPES_REPO;
-    public const TYPES_DIR = [self::TYPE_DIR => self::TYPE_DIR];
-    public const TYPES_FILE = [self::TYPE_FILE => self::TYPE_FILE];
-    public const TYPES_REPO = [self::TYPE_REPO => self::TYPE_REPO, self::TYPE_SREPO => self::TYPE_SREPO, self::TYPE_GREPO => self::TYPE_GREPO];
-
-    /**
-     * @const string
-     */
-    public const STRING_SUCCESS = 'success';
-
-    /**
-     * Error codes
-     */
-    public const ERROR_CODE_FEATURES = 802;
-    public const ERROR_CODE_NO_CURL = 803;
-    public const ERROR_CODE_FILE_IO = 808;
-
-    /**
-     * default curl options
-     */
-    private const CURL_OPTION_DEFAULTS = [
-        CURLOPT_AUTOREFERER => true,
-        CURLOPT_TIMEOUT => 10,
-        CURLOPT_RETURNTRANSFER => true,
-        CURLOPT_FOLLOWLOCATION => false,
-    ];
-
-    /**
-     * @var array shared curl options between all requests
-     */
-    private array $curlSharedOptions = self::CURL_OPTION_DEFAULTS;
-
-    /**
-     * jsonDecode accept flags
-     *
-     * @see jsonDecode
-     */
-    private const JSON_DECODE_ACCEPT_MASK = 31;                         # 1 1111 accept bitmask (five bits with the msb flags)
-    private const JSON_DECODE_ACCEPT_JSON = 16;                         # 1 0000 JSON text
-    private const JSON_DECODE_ACCEPT_DEFAULT = 23;                      # 1 0111 default: string, array or object
-    private const JSON_DECODE_ACCEPT_OBJECT = 17;                       # 1 0001 object
-    private const JSON_DECODE_ACCEPT_ARRAY = 18;                        # 1 0010 array
-    private const JSON_DECODE_ACCEPT_STRING = 20;                       # 1 0100 string
-    private const JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS = 24;             # 1 1000 array with only objects (incl. none)
-    private const JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT = 25;          # 1 1001 array with one single object, return that item
-    private const JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT_NULLABLE = 26; # 1 1010 array with one single object, return that item, or empty array, return null
-    private const JSON_DECODE_ACCEPT_SUCCESS_STRING = 28;               # 1 1100 string "success"
-    private const JSON_DECODE_ACCEPT_SUCCESS_OBJECT = 29;               # 1 1101 object with single "success" property and value true
-
-    /**
-     * @const string ASCII upper-case characters part of a hexit
-     */
-    private const HEX_ALPHA_UPPER = 'ABCDEF';
-
-    /**
-     * @const string ASCII lower-case characters part of a hexit
-     */
-    private const HEX_ALPHA_LOWER = 'abcdef';
-
-    /**
-     * @var string Server base URL
-     */
-    private string $baseurl;
-
-    /**
-     * @var string Username
-     */
-    private string $user;
-
-    /**
-     * @var string Password
-     */
-    private string $pass;
-
-    private ?CurlHandle $handle = null;
-
-    /**
-     * @var string
-     */
-    private string $token = '';
-
-    /**
-     * constructor
-     *
-     * @param string $baseurl
-     * @param string $user
-     * @param string $pass
-     * @param string|null $otp
-     */
-    public function __construct(string $baseurl, string $user, string $pass, string $otp = null)
-    {
-        if (!(function_exists('curl_version'))) {
-            throw new ConnectionException('PHP-CURL not installed', self::ERROR_CODE_NO_CURL);
-        }
-
-        $this->baseurl = $baseurl;
-        $this->user = $user;
-        $this->pass = $pass;
-        // trigger_error(sprintf("ctor: %s:%s", $user, $pass), E_USER_NOTICE);
-
-        $this->setTokenByUsernameAndPassword($otp);
-    }
-
-    /**
-     * ping (with authentication)
-     *
-     * @link https://download.seafile.com/published/web-api/home.md#user-content-Quick%20Start
-     *
-     * @return string "pong"
-     */
-    public function ping(): string
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/ping/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_STRING,
-        );
-    }
-
-    /**
-     * get server version
-     *
-     * @throws Exception
-     * @return string
-     */
-    public function getServerVersion(): string
-    {
-        $serverInfo = $this->getServerInformation();
-        if (
-            !is_string($serverInfo->version ?? null)
-            || !is_array($serverInfo->features ?? null)
-        ) {
-            throw new InvalidResponseException('We could not retrieve list of server features.', self::ERROR_CODE_FEATURES);
-        }
-
-        $isSeafilePro = in_array('seafile-pro', $serverInfo->features, true);
-        $edition = $isSeafilePro ? 'Professional' : 'Community';
-
-        return "$serverInfo->version ($edition)";
-    }
-
-    /**
-     * get server information
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/server-info.md#user-content-Get%20Server%20Information
-     *
-     * @throws Exception
-     * @return object
-     */
-    public function getServerInformation(): object
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/server-info/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * check account info
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/account.md#user-content-Check%20Account%20Info
-     * @return object
-     */
-    public function checkAccountInfo(): object
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/account/info/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]]
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * list seafile server libraries
-     *
-     * that are all libraries a user can access.
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-List%20Libraries
-     *
-     * @throws Exception
-     * @return object[]
-     */
-    public function listLibraries(): array
-    {
-        return $this->listLibrariesCached(true);
-    }
-
-    /**
-     * get default library
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Get%20Default%20Library
-     *
-     * @return object{exists: bool, repo_id: string}
-     */
-    public function getDefaultLibrary(): object
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/default-repo/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * create a library
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Create%20Library
-     *
-     * @param string $name of library
-     * @return object
-     */
-    public function createLibrary(string $name): object
-    {
-        $name = trim($name, "/");
-
-        return $this->jsonDecode(
-            $this->post(
-                "$this->baseurl/api2/repos/",
-                ['name' => $name],
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * name a library
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Rename%20Library
-     */
-    public function nameLibrary(string $lib, string $name): void
-    {
-        $lib = $this->verifyLib($lib);
-        $fields = ['repo_name' => $name];
-        $_ = $this->jsonDecode(
-            $this->post(
-                "$this->baseurl/api2/repos/$lib/?op=rename",
-                $fields,
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_SUCCESS_STRING,
-        );
-        unset($_);
-    }
-
-    /**
-     * rename a library
-     *
-     * do nothing if the library can not be found
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Rename%20Library
-     *
-     * @param string $oldName
-     * @param string $newName
-     * @return void
-     */
-    public function renameLibrary(string $oldName, string $newName): void
-    {
-        $lib = $this->getLibraryIdByLibraryName($oldName);
-        if (null === $lib) {
-            return; // no library to rename
-        }
-
-        $this->nameLibrary($lib, $newName);
-    }
-
-    /**
-     * delete a library by name
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Delete%20Library
-     *
-     * @param string $name
-     * @return void
-     */
-    public function deleteLibraryByName(string $name): void
-    {
-        $id = $this->getLibraryIdByLibraryName($name);
-        if (null === $id) {
-            return; // library already gone
-        }
-
-        $this->deleteLibraryById($id);
-    }
-
-    /**
-     * delete a library by id
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Delete%20Library
-     *
-     * @param string $id
-     * @return void
-     */
-    public function deleteLibraryById(string $id): void
-    {
-        $lib = $this->verifyLib($id);
-
-        $_ = $this->jsonDecode(
-            $this->delete(
-                "$this->baseurl/api2/repos/$lib/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_SUCCESS_STRING,
-        );
-        unset($_);
-    }
-
-    /**
-     * get library info array from path
-     *
-     * @param string $libNamedPath with the library name as first component
-     * @throws Exception
-     * @throws InvalidResponseException
-     * @return object with 'id' and 'name' of library, both NULL if not found
-     */
-    public function getLibraryFromPath(string $libNamedPath): object
-    {
-        $libraries = $this->listLibrariesCached();
-        $libraries = array_column($libraries, null, 'name');
-
-        $name = explode('/', ltrim($this->normalizePath($libNamedPath), '/'), 2)[0];
-
-        return (object)[
-            'id' => $libraries[$name]->id ?? null,
-            'name' => $libraries[$name]->name ?? null,
-        ];
-    }
-
-    /**
-     * list all share links
-     *
-     * all folder/file download share links in all libraries created by user.
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/share-links.md#user-content-List%20all%20Share%20Links
-     *
-     * @return object[]
-     * @throws Exception
-     * @throws InvalidResponseException
-     * @noinspection PhpUnused
-     */
-    public function listAllShareLinks(): array
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api/v2.1/share-links/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS,
-        );
-    }
-
-    /**
-     * Create Share Link
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/share-links.md#user-content-Create%20Share%20Link
-     *
-     * @param string $lib
-     * @param string $path
-     * @param ?string $password [optional]
-     * @param ?int|DateTimeInterface $expire [optional] number of days to expire (int) or DateTime to expire
-     * @param ?array $permissions [optional] see seafile api docs
-     * @return object
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @throws InvalidResponseException
-     */
-    public function createShareLink(string $lib, string $path, string $password = null, $expire = null, array $permissions = null): object
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-
-        $fields = [
-            'repo_id' => $lib,
-            'path' => $path,
-        ];
-        if (null !== $password) {
-            $fields['password'] = $password;
-        }
-        if (null !== $expire) {
-            $expireTime = $expire;
-            if (is_int($expire)) {
-                $expireDays = max(1, min(365, (int)$expire));
-                $expireTime = (new DateTimeImmutable())->add(
-                    new \DateInterval("P{$expireDays}D")
-                );
-            }
-            if (!$expireTime instanceof DateTimeInterface) {
-                throw new InvalidArgumentException('Expire type mismatch: ' . gettype($expireTime));
-            }
-            $fields['expiration_time'] = $expireTime->format(\DATE_ATOM);
-        }
-        if (null !== $permissions) {
-            try {
-                $fields['permissions'] = json_encode($permissions, JSON_THROW_ON_ERROR);
-            } /** @noinspection PhpMultipleClassDeclarationsInspection */ catch (JsonException $ex) {
-                throw new InvalidArgumentException('permissions');
-            }
-        }
-
-        return $this->jsonDecode(
-            $this->post(
-                "$this->baseurl/api/v2.1/share-links/",
-                $fields,
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * List Share Links of a Library
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/share-links.md#user-content-List%20all%20Share%20Links
-     *
-     * @param ?string $lib [optional] library id (guid), default/null for all libraries
-     * @throws Exception
-     * @return object[]
-     */
-    public function listShareLinksOfALibrary(string $lib = null): array
-    {
-        $lib = $this->verifyLib($lib ?? '', true);
-
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api/v2.1/share-links/?repo_id=$lib",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS,
-        );
-    }
-
-    /**
-     * check password (of a share link by token)
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1-admin/share-links.md#user-content-Check%20Password
-     *
-     * @param string $token of share link
-     * @param string $password in plain
-     * @return object
-     * @throws Exception
-     * @throws InvalidResponseException
-     * @noinspection PhpUnused
-     */
-    public function checkShareLinkPassword(string $token, string $password): object
-    {
-        $tokenEncoded = rawurlencode($token);
-
-        return $this->jsonDecode(
-            $this->post(
-                "$this->baseurl/api/v2.1/admin/share-links/$tokenEncoded/check-password/",
-                ['password' => $password],
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_SUCCESS_OBJECT,
-        );
-    }
-
-    /**
-     * share Link of a folder (or file)
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/share-links.md#user-content-List%20Share%20Link%20of%20a%20Folder%20(File)
-     *
-     * @param string $lib
-     * @param string $path
-     * @return object the share link
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @throws InvalidResponseException
-     * @noinspection PhpUnused
-     */
-    public function listShareLinksOfAFolder(string $lib, string $path): ?object
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api/v2.1/share-links/?repo_id=$lib&path=$pathEncoded",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT_NULLABLE,
-        );
-    }
-
-    /**
-     * Delete Share Link
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/share-links.md#user-content-Delete%20Share%20Link
-     *
-     * @param string $token
-     * @throws Exception
-     * @return object success {"success": true}
-     */
-    public function deleteShareLink(string $token): object
-    {
-        $token = $this->verifyToken($token);
-
-        return $this->jsonDecode(
-            $this->delete(
-                "$this->baseurl/api/v2.1/share-links/$token/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_SUCCESS_OBJECT,
-        );
-    }
-
-    /**
-     * search user
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/user-search.md#user-content-Search%20User
-     *
-     * @param string $search
-     * @throws Exception
-     * @return object
-     */
-    public function searchUser(string $search): object
-    {
-        $searchEncoded = rawurlencode($search);
-
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/search-user/?q=$searchEncoded",
-                [CURLOPT_HTTPHEADER => ['Authorization: Token ' . $this->token]],
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * list groups for user sharing
-     *
-     * @throws Exception
-     * @throws InvalidResponseException
-     * @return array|object|string
-     * @link (undocumented)
-     *
-     */
-    public function shareableGroups(): array
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api/v2.1/shareable-groups/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS,
-        );
-    }
-
-    /**
-     * Share a Library to Group
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/share.md#user-content-Share%20a%20Library%20to%20Group
-     *
-     * @param string $lib
-     * @param string $path
-     * @param int|int[] $group
-     * @param string|null $permission [optional] r, rw, admin (default: r)
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @return array
-     */
-    public function shareLibraryPathToGroup(string $lib, string $path, $group, string $permission = null)
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-
-        $fields = [
-            'share_type' => 'group',
-            'group_id' => $group,
-            'permission' => $permission ?? 'r',
-        ];
-        return $this->jsonDecode(
-            $this->put(
-                "$this->baseurl/api2/repos/$lib/dir/shared_items/?p=$pathEncoded",
-                $fields,
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * Share a Library to User
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/share.md#user-content-Share%20a%20Library%20to%20User
-     *
-     * @param string $lib
-     * @param string $path
-     * @param string $user
-     * @param string|null $permission [optional] r, rw, admin (default: r)
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @return array
-     */
-    public function shareLibraryPathToUser(string $lib, string $path, string $user, string $permission = null)
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-
-        $fields = [
-            'share_type' => 'user',
-            'username' => $user,
-            'permission' => $permission ?? 'r',
-        ];
-        return $this->jsonDecode(
-            $this->put(
-                "$this->baseurl/api2/repos/$lib/dir/shared_items/?p=$pathEncoded",
-                $fields,
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            // either array of objects -or- failure object
-            self::JSON_DECODE_ACCEPT_ARRAY | self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * Unshare a Library to Group
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/share.md#user-content-Unshare%20a%20Library%20from%20Group
-     *
-     * @param string $lib
-     * @param string $path
-     * @param int $group
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @return object
-     */
-    public function unshareLibraryPathToGroup(string $lib, string $path, int $group): object
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-
-        return $this->jsonDecode(
-            $this->delete(
-                "$this->baseurl/api2/repos/$lib/dir/shared_items/?p=$pathEncoded&share_type=group&group_id=$group",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_SUCCESS_OBJECT,
-        );
-    }
-
-    /**
-     * Unshare a Library to User
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/share.md#user-content-Unshare%20a%20Library%20from%20User
-     *
-     * @param string $lib
-     * @param string $path
-     * @param string|string[] $user
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @return object
-     */
-    public function unshareLibraryPathToUser(string $lib, string $path, $user): object
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-        $userEncoded = rawurlencode($user);
-
-        return $this->jsonDecode(
-            $this->delete(
-                "$this->baseurl/api2/repos/$lib/dir/shared_items/?p=$pathEncoded&share_type=user&username=$userEncoded",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_SUCCESS_OBJECT,
-        );
-    }
-
-    /**
-     * list user shares for a library path
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/share.md#user-content-List%20Shared%20Users%20of%20a%20Library
-     *
-     * @param string $lib
-     * @param string $path
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @throws InvalidResponseException
-     * @return array<int, object>
-     */
-    public function listSharesOfLibraryPath(string $lib, string $path): array
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/repos/$lib/dir/shared_items/?p=$pathEncoded",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS,
-        );
-    }
-
-    /**
-     * create a new directory
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/directories.md#user-content-Create%20New%20Directory
-     *
-     * @param string $lib library id (guid)
-     * @param string $path of the directory to create (e.g.: "/path/to/new-directory", leading and trailing slashes can be omitted)
-     * @throws InvalidArgumentException|Exception
-     * @return string|object the common "success" or the object with error_msg property
-     */
-    public function createNewDirectory(string $lib, string $path)
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-
-        return $this->jsonDecode(
-            $this->post(
-                "$this->baseurl/api2/repos/$lib/dir/?p=$pathEncoded",
-                ['operation' => 'mkdir'],
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_STRING | self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * delete a file
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/file.md#user-content-Delete%20File
-     *
-     * @param string $lib library id (guid)
-     * @param string $path of the fle to delete (e.g.: "/path/to/file-to-delete", leading and trailing slashes can be omitted)
-     * @throws InvalidArgumentException|Exception
-     * @return string|object the common "success" or the known object with error_msg property
-     */
-    public function deleteFile(string $lib, string $path)
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-
-        return $this->jsonDecode(
-            $this->delete(
-                "$this->baseurl/api2/repos/$lib/file/?p=$pathEncoded",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_STRING | self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * get a file download URL
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/file.md#user-content-Download%20File
-     *
-     * @param string $lib
-     * @param string $path
-     * @return string download URL (http/s)
-     * @throws InvalidArgumentException|Exception
-     */
-    public function downloadFile(string $lib, string $path): string
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/repos/$lib/file/?p=$pathEncoded",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_STRING,
-        );
-    }
-
-    /**
-     * download a file
-     *
-     * get file contents of a file in a library
-     *
-     * @param string $lib
-     * @param string $path
-     * @throws InvalidArgumentException|Exception
-     * @return string|false on failure
-     */
-    public function downloadFileAsBuffer(string $lib, string $path)
-    {
-        $url = $this->downloadFile($lib, $path);
-
-        return $this->get($url);
-    }
-
-    /**
-     * download a file to a local file
-     *
-     * @param string $lib
-     * @param string $path
-     * @param string $localPath path to a file - existing or not - on the local file-system
-     * @throws InvalidArgumentException|Exception
-     * @return bool success/failure
-     */
-    public function downloadFileToFile(string $lib, string $path, string $localPath): bool
-    {
-        $handle = fopen($localPath, 'wb');
-        if (false === $handle) {
-            throw new Exception('failed to open local path for writing', self::ERROR_CODE_FILE_IO);
-        }
-
-        try {
-            $result = $this->downloadFileToStream($lib, $path, $handle);
-        } finally {
-            $close = fclose($handle);
-        }
-
-        if (!$close) {
-            throw new Exception('failed to close local path handle', self::ERROR_CODE_FILE_IO);
-        }
-
-        return $result;
-    }
-
-    /**
-     * download a file to a stream handle
-     *
-     * @param string $lib
-     * @param string $path
-     * @param resource $handle stream handle
-     * @throws InvalidArgumentException|Exception
-     * @return bool success/failure
-     */
-    public function downloadFileToStream(string $lib, string $path, $handle): bool
-    {
-        $url = $this->downloadFile($lib, $path);
-
-        return $this->get($url, [CURLOPT_RETURNTRANSFER => true, CURLOPT_FILE => $handle]);
-    }
-
-    /**
-     * list items in directory
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/directories.md#user-content-List%20Items%20in%20Directory
-     *
-     * @param string $lib
-     * @param string $path
-     * @return array
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @throws InvalidResponseException
-     */
-    public function listItemsInDirectory(string $lib, string $path): array
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-
-        $result = $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/repos/$lib/dir/?p=$pathEncoded",
-                [CURLOPT_HTTPHEADER => ['Authorization: Token ' . $this->token]],
-            ),
-        );
-
-        if (is_object($result)) {
-            // likely a folder not found.
-            $result = [];
-        }
-
-        return $result;
-    }
-
-    /**
-     * move a file
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/file.md#user-content-Move%20File
-     *
-     * @param string $lib
-     * @param string $path
-     * @param string $dstLib
-     * @param string $dstDir
-     * @return object
-     * @throws InvalidArgumentException|Exception
-     */
-    public function moveFile(string $lib, string $path, string $dstLib, string $dstDir): object
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-        $dstLib = $this->verifyLib($dstLib);
-        $dstDir = $this->normalizePath($dstDir);
-
-        return $this->jsonDecode(
-            $this->post(
-                "$this->baseurl/api2/repos/$lib/file/?p=$pathEncoded",
-                ['operation' => 'move', 'dst_repo' => $dstLib, 'dst_dir' => $dstDir],
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * rename a file
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/file.md#user-content-Move%20File
-     *
-     * @param string $lib library id (guid)
-     * @param string $path of the file to rename (e.g. "/path/to/file-to-rename")
-     * @param string $newName new basename for the basename of $path (e.g. "new-file-name")
-     * @return string|object the common "success" or the known object with error_msg property
-     * @throws Exception
-     */
-    public function renameFile(string $lib, string $path, string $newName)
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        $pathEncoded = rawurlencode($path);
-
-        return $this->jsonDecode(
-            $this->post(
-                "$this->baseurl/api2/repos/$lib/file/?p=$pathEncoded",
-                ['operation' => 'rename', 'newname' => $newName],
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_STRING | self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * simplified file upload routine for string buffer
-     *
-     * @param string $lib
-     * @param string $path
-     * @param string $buffer
-     * @throws InvalidArgumentException
-     * @throws Exception
-     * @return object
-     */
-    public function uploadBuffer(string $lib, string $path, string $buffer): object
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-
-        $parentDir = dirname($path);
-        $uploadLink = $this->uploadGetLink($lib, $parentDir);
-        $fileName = basename($path);
-
-        return $this->uploadFileBuffer($uploadLink, $parentDir, '', $buffer, $fileName);
-    }
-
-    /**
-     * simplified file upload routine for standard file
-     *
-     * @param string $lib
-     * @param string $path path in seafile to upload the file as
-     * @param string $file path of file to upload
-     * @throws InvalidArgumentException
-     * @throws Exception
-     * @return object
-     */
-    public function uploadFile(string $lib, string $path, string $file): object
-    {
-        $lib = $this->verifyLib($lib);
-        $path = $this->normalizePath($path);
-        if (!is_file($file) && !is_readable($file)) {
-            throw new InvalidArgumentException(sprintf('Not a readable file: %s', $file));
-        }
-
-        $parentDir = dirname($path);
-        $uploadLink = $this->uploadGetLink($lib, $parentDir);
-        $fileName = basename($path);
-
-        return $this->uploadFilePath($uploadLink, $parentDir, '', $file, $fileName);
-    }
-
-    /**
-     * upload string buffer as a file
-     *
-     * same as {@see SeafileApi::uploadFile()} with the option to upload without a
-     * concrete file on the system. the temporary file to upload is created
-     * from the string buffer.
-     *
-     * @param string $uploadLink from {@see uploadGetLink}
-     * @param string $parentDir the parent directory to upload the file to
-     * @param string $relativePath the name of the file, subdirectories possible (e.g. uploading a folder)
-     * @param string $buffer file contents to upload as string (not the file-name)
-     * @param string $fileName to use as basename for the data
-     * @param bool $replace
-     * @throws Exception
-     * @return object
-     */
-    public function uploadFileBuffer(
-        string $uploadLink, string $parentDir, string $relativePath,
-        string $buffer, string $fileName = 'upload.dat', bool $replace = false
-    ): object
-    {
-        $tmpHandle = tmpfile();
-        if (false === $tmpHandle) {
-            throw new Exception('Upload data rejected: Unable to open temporary stream.');
-        }
-
-        $meta = stream_get_meta_data($tmpHandle);
-        $tmpFile = $meta['uri'];
-        if (!is_file($tmpFile)) {
-            fclose($tmpHandle);
-            throw new Exception('Upload data rejected: No file with temporary stream.');
-        }
-
-        $bytes = fwrite($tmpHandle, $buffer);
-        if (false === $bytes) {
-            fclose($tmpHandle);
-            throw new Exception('Upload data rejected: Failed to write to temporary stream.');
-        }
-
-        $diff = strlen($buffer) - $bytes;
-        if ($diff !== 0) {
-            fclose($tmpHandle);
-            throw new Exception(sprintf("Upload data rejected: Unexpected difference writing to temporary stream: %d bytes", $diff));
-        }
-
-        $result = rewind($tmpHandle);
-        if (false === $result) {
-            fclose($tmpHandle);
-            throw new Exception('Upload data rejected: Failed to rewind temporary stream.');
-        }
-
-        $result = $this->uploadFilePath($uploadLink, $parentDir, $relativePath, $tmpFile, $fileName, $replace);
-        fclose($tmpHandle);
-
-        return $result;
-    }
-
-    /**
-     * upload file
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/file-upload.md#user-content-Upload%20File
-     *
-     * @param string $uploadLink from {@see uploadGetLink}
-     * @param string $parentDir the parent directory to upload a file to
-     * @param string $relativePath to place the file in under $uploadPath (can include subdirectories)
-     * @param string $path path of the file to upload
-     * @param ?string $fileName to use as basename for the file (the name used in Seafile)
-     * @param bool $replace
-     * @return object
-     * @throws Exception
-     */
-    public function uploadFilePath(
-        string $uploadLink, string $parentDir, string $relativePath,
-        string $path, string $fileName = null, bool $replace = false
-    ): object
-    {
-        $parentDir = $this->normalizePath($parentDir);
-        $relativePath = ltrim('/', $this->normalizePath($relativePath));
-        $fileName = $fileName ?? basename($path);
-
-        $fields = [
-            'file' => new CURLFile($path, 'application/octet-stream', $fileName),
-            'parent_dir' => $parentDir,
-            'relative_path' => $relativePath,
-            'replace' => $replace ? '1' : '0',
-        ];
-
-        return $this->jsonDecode(
-            $this->post(
-                "$uploadLink?ret-json=1",
-                $fields,
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT,
-        );
-    }
-
-    /**
-     * get file upload link
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/file-upload.md#user-content-Get%20Upload%20Link
-     *
-     * @param string $lib
-     * @param string $uploadDir the directory to upload file(s) to
-     * @return string upload link (https?://...)
-     * @throws InvalidArgumentException|Exception
-     */
-    public function uploadGetLink(string $lib, string $uploadDir): string
-    {
-        $lib = $this->verifyLib($lib);
-        $uploadDir = $this->normalizePath($uploadDir);
-        $pathEncoded = rawurlencode($uploadDir);
-
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/repos/$lib/upload-link/?p=$pathEncoded",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_STRING,
-        );
-    }
-
-    public function generateUserAuthToken(string $email): object
-    {
-        return $this->jsonDecode(
-            $this->post(
-                "$this->baseurl/api/v2.1/admin/generate-user-auth-token/",
-                ['email' => $email],
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    public function getUserActivity(string $email, int $page = 1, int $perPage = 25): object
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api/v2.1/admin/user-activities/?user=$email&page=$page&per_page=$perPage",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-    }
-
-    /**
-     * set authorization token
-     *
-     * @param string $token
-     * @return void
-     */
-    public function setToken(string $token): void
-    {
-        $this->token = $token;
-    }
-
-    public function listDevices(): array
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/devices/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-        );
-    }
-
-    public function listStarredItems(): object
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api/v2.1/starred-items/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-        );
-    }
-
-    public function listGroups(): object
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/groups/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-        );
-    }
-
-    public function listInvitations(): array
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api/v2.1/invitations/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-        );
-    }
-
-    /**
-     * @param string $start e.g. date('Y-m-d', time() - 7776000 ); // 3 months
-     * @param string $end e.g. date('Y-m-d', time());
-     *
-     * @return array
-     */
-    public function getLoginLog(string $start, string $end): array
-    {
-        $start = rawurlencode($start);
-        $end = rawurlencode($end);
-
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api/v2.1/admin/logs/login/?start=$start&end=$end",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-        );
-    }
-
-    public function listUploadLinks(): array
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api/v2.1/upload-links/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-        );
-    }
-
-    public function listRepoApiTokens(string $lib): object
-    {
-        $lib = $this->verifyLib($lib);
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api/v2.1/repos/$lib/repo-api-tokens/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-        );
-    }
-
-    /**
-     * internal api implementation to get library by name
-     *
-     * @param string $name
-     * @throws Exception
-     * @return ?string id (guid) of the library, null if library does not exist
-     */
-    private function getLibraryIdByLibraryName(string $name): ?string
-    {
-        $name = explode('/', $this->normalizePath($name), 2)[1];
-
-        $libraries = $this->listLibrariesCached();
-        $libraries = array_column($libraries, null, 'name');
-        return $libraries[$name]->id ?? null;
-    }
-
-    /**
-     * List libraries a user can access.
-     *
-     * internal api implementation for {@see listLibrariesCached()} and {@see listLibraries()}
-     *
-     * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-List%20Libraries
-     *
-     * @throws Exception
-     * @return object[]
-     */
-    private function listLibrariesDo(): array
-    {
-        return $this->jsonDecode(
-            $this->get(
-                "$this->baseurl/api2/repos/",
-                [CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
-            ),
-            self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS,
-        );
-    }
-
-    /**
-     * like {@see listLibraries()} but cached.
-     *
-     * @param bool $invalidate
-     * @throws Exception
-     * @throws InvalidResponseException
-     * @return void
-     */
-    private function listLibrariesCached(bool $invalidate = false): array
-    {
-        static $librariesCache;
-
-        return $librariesCache = ($invalidate ? null : $librariesCache) ?? $this->listLibrariesDo();
-    }
-
-    /**
-     * normalize path
-     *
-     * normalizes the path component separator <slash> "/" <U002F> U+002F SOLIDUS
-     * with first character being the slash, no consecutive slashes within the
-     * path and no terminating slash.
-     *
-     * @param string $path
-     * @return string
-     */
-    private function normalizePath(string $path): string
-    {
-        $buffer = rtrim($path, '/');
-        $buffer = preg_replace('~/{2,}~', '/', $buffer);
-        '' === $buffer && $buffer = '/';
-        '/' === $buffer[0] || $buffer = "/$buffer";
-
-        return $buffer;
-    }
-
-    /**
-     * verify library id
-     *
-     * verifies the format of a library id. can be used in URLs
-     * afterwards. case normalization to lowercase.
-     *
-     * example library id strings:
-     *  - 21b941c2-5411-4372-a514-00b62ab99ef2 (from the docs)
-     *  - 79144b25-f772-42b6-a1c0-60e6359f5884 (from a server)
-     *
-     * @param string $lib
-     * @param bool $allowEmpty
-     * @return string library id
-     */
-    private function verifyLib(string $lib, bool $allowEmpty = false): string
-    {
-        if ($allowEmpty && ('' === $lib)) {
-            return $lib;
-        }
-
-        $buffer = strtr($lib, self::HEX_ALPHA_UPPER, self::HEX_ALPHA_LOWER);
-        $format = '%04x%04x-%04x-%04x-%04x-%04x%04x%04x';
-        $values = sscanf($buffer, $format);
-        $result = vsprintf($format, $values);
-
-        if ($buffer !== $result) {
-            throw new InvalidArgumentException(sprintf('Not a library id: "%s"', $lib));
-        }
-
-        return $result;
-    }
-
-    /**
-     * verify share link token
-     *
-     * verifies the format of a share link token. can be used in URLs
-     * afterwards. case normalization to lowercase.
-     *
-     * @param string $token e.g. "0a29ff44dc0b4b56be74"
-     * @return string
-     */
-    private function verifyToken(string $token): string
-    {
-        $buffer = strtr($token, self::HEX_ALPHA_UPPER, self::HEX_ALPHA_LOWER);
-        $format = '%04x%04x%04x%04x%04x';
-        $values = sscanf($buffer, $format);
-        $result = vsprintf($format, $values);
-
-        if ($buffer !== $result) {
-            throw new InvalidArgumentException(sprintf('Not a token: "%s"', $token));
-        }
-
-        return $result;
-    }
-
-    /**
-     * authenticate class against seafile api
-     *
-     * @link https://download.seafile.com/published/web-api/home.md#user-content-Quick%20Start
-     *
-     * @param string|null $otp (optional) Seafile OTP (if user uses OTP access)
-     * @return void
-     */
-    private function setTokenByUsernameAndPassword(string $otp = null): void
-    {
-        // @auth:token:<email> : password is auth token
-        if (0 === strpos($this->user, $needle = self::USER_PREFIX_AUTH_TOKEN)) {
-            $this->user = \substr($this->user, strlen($needle)) ?: '';
-            $this->token = $this->pass;
-            if ('pong' !== $this->ping()) {
-                throw new ConnectionException('token authentication failure');
-            }
-            return;
-        }
-
-        $data = $this->jsonDecode(
-            $this->post(
-                "$this->baseurl/api2/auth-token/",
-                ['username' => $this->user, 'password' => $this->pass],
-                $otp ? [CURLOPT_HTTPHEADER => ["X-SEAFILE-OTP: $otp"]] : [],
-            ),
-            self::JSON_DECODE_ACCEPT_OBJECT,
-        );
-        $this->token = (string)$data->token;
-    }
-
-    /**
-     * http request with get method
-     *
-     * @param string $url
-     * @param array $curlOptions
-     * @return bool|string
-     */
-    private function get(string $url, array $curlOptions = [])
-    {
-        $curlOptions += $this->curlSharedOptions;
-
-        return $this->curlExec($url, $curlOptions);
-    }
-
-    /**
-     * http request with post method
-     *
-     * @param string $url
-     * @param array $fields
-     * @param array $curlOptions
-     * @return bool|string
-     */
-    private function post(string $url, array $fields = [], array $curlOptions = [])
-    {
-        $curlOptions += $this->curlSharedOptions;
-        $curlOptions[CURLOPT_POST] = true;
-        $curlOptions[CURLOPT_POSTFIELDS] = $fields;
-
-        return $this->curlExec($url, $curlOptions);
-    }
-
-    /**
-     * http request with put method
-     *
-     * @param string $url
-     * @param array $fields
-     * @param array $curlOptions
-     * @return bool|string
-     */
-    public function put(string $url, array $fields = [], array $curlOptions = [])
-    {
-        $curlOptions += $this->curlSharedOptions;
-        $curlOptions[CURLOPT_CUSTOMREQUEST] = 'PUT';
-        $curlOptions[CURLOPT_POSTFIELDS] = $fields;
-
-        return $this->curlExec($url, $curlOptions);
-    }
-
-    /**
-     * http request with delete method
-     *
-     * @param string $url
-     * @param array $curlOptions
-     * @return bool|string
-     */
-    public function delete(string $url, array $curlOptions = [])
-    {
-
-        $curlOptions += $this->curlSharedOptions;
-        $curlOptions[CURLOPT_CUSTOMREQUEST] = 'DELETE';
-
-        return $this->curlExec($url, $curlOptions);
-    }
-
-    /**
-     * json decode handler
-     *
-     * decode json with structural acceptance
-     *
-     * @param string $jsonText
-     * @param int $flags decode accept flag
-     * @throws InvalidResponseException
-     * @return string|object|array
-     */
-    private function jsonDecode(string $jsonText, int $flags = self::JSON_DECODE_ACCEPT_DEFAULT)
-    {
-        $accept = $flags & self::JSON_DECODE_ACCEPT_MASK;
-        if (0 === $accept) {
-            return $jsonText;
-        }
-
-        try {
-            $result = json_decode($jsonText, false, 512, JSON_THROW_ON_ERROR);
-        } /** @noinspection PhpMultipleClassDeclarationsInspection */ catch (JsonException $e) {
-            throw JsonDecodeException::create(sprintf('json decode error of %s', JsonDecodeException::shorten($jsonText)), $jsonText, $e);
-        }
-
-        if (self::JSON_DECODE_ACCEPT_JSON === $accept) {
-            return $result;
-        }
-
-        if (self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS === $accept) {
-            if (is_array($result) && $result === array_filter($result, 'is_object')) {
-                return $result;
-            }
-            throw JsonDecodeException::create(sprintf('json decode accept %5d error [%s] of %s', decbin($accept), gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
-        }
-
-        if (self::JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT_NULLABLE === $accept) {
-            if (is_array($result)
-                && (
-                    (count($result) === 1 && is_object($result[0] ?? null))
-                    || (count($result) === 0)
-                )
-            ) {
-                return $result[0] ?? null;
-            }
-            throw JsonDecodeException::create(sprintf('json decode accept %5d error [%s] of %s', decbin($accept), gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
-        }
-
-        if (self::JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT === $accept) {
-            if (is_array($result) && is_object($result[0] ?? null) && count($result) === 1) {
-                return $result[0];
-            }
-            throw JsonDecodeException::create(sprintf('json decode accept %5d error [%s] of %s', decbin($accept), gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
-        }
-
-        if (self::JSON_DECODE_ACCEPT_SUCCESS_OBJECT === $accept) {
-            if (is_object($result) && (array)$result === ['success' => true]) {
-                return $result;
-            }
-            throw JsonDecodeException::create(sprintf('json decode accept %5d error [%s] of %s', decbin($accept), gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
-        }
-
-        if (self::JSON_DECODE_ACCEPT_SUCCESS_STRING === $accept) {
-            if (self::STRING_SUCCESS === $result) {
-                return $result;
-            }
-            throw JsonDecodeException::create(sprintf('json decode accept %5d error [%s] of %s', decbin($accept), gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
-        }
-
-        if (is_string($result) && (self::JSON_DECODE_ACCEPT_STRING !== ($accept & self::JSON_DECODE_ACCEPT_STRING))) {
-            throw JsonDecodeException::create(sprintf('json decode type %s not accepted; of %s', gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
-        }
-
-        if (is_array($result) && (self::JSON_DECODE_ACCEPT_ARRAY !== ($accept & self::JSON_DECODE_ACCEPT_ARRAY))) {
-            throw JsonDecodeException::create(sprintf('json decode type %s not accepted; of %s', gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
-        }
-
-        if (is_object($result) && (self::JSON_DECODE_ACCEPT_OBJECT !== ($accept & self::JSON_DECODE_ACCEPT_OBJECT))) {
-            throw JsonDecodeException::create(sprintf('json decode type %s not accepted; of %s', gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
-        }
-
-        return $result;
-    }
-
-
-    /**
-     * execute curl with url and options
-     *
-     * @param string $url
-     * @param array $options
-     * @return bool|string
-     */
-    private function curlExec(string $url, array $options)
-    {
-        $handle = curl_init($url);
-        if (!($handle instanceof CurlHandle)) {
-            throw new ConnectionException('Unable to initialise cURL session.', self::ERROR_CODE_NO_CURL);
-        }
-
-        $this->handle = $handle;
-
-        if (!curl_setopt_array($this->handle, $options)) {
-            throw new Exception("Error setting cURL request options.");
-        }
-        $result = curl_exec($this->handle);
-        $this->curlExecHandleResult($result);
-        curl_close($this->handle);
-
-        return $result;
-    }
-
-    /**
-     * internal handling of curl_exec() return
-     *
-     * {@see curlExec()}
-     *
-     * @param bool|string $curlResult return value from curl_exec();
-     * @throws ConnectionException
-     * @return void
-     */
-    private function curlExecHandleResult($curlResult): void
-    {
-        if (empty($curlResult)) {
-            throw new ConnectionException(curl_error($this->handle), -1);
-        }
-
-        $code = (int)curl_getinfo($this->handle)['http_code'];
-
-        $codeIsInErrorRange = $code >= 400 && $code <= 600;
-        $codeIsNotInNonErrorCodes = !in_array($code, [200, 201, 202, 203, 204, 205, 206, 207, 301], true);
-
-        if ($codeIsInErrorRange || $codeIsNotInNonErrorCodes) {
-            ConnectionException::throwCurlResult($code, $curlResult);
-        }
-    }
+	public const USER_PREFIX_AUTH_TOKEN = '@auth:token:';
+
+	public const TYPE_DIR = 'dir';
+	public const TYPE_FILE = 'file';
+	public const TYPE_REPO = 'repo';
+	public const TYPE_SREPO = 'srepo';
+	public const TYPE_GREPO = 'grepo';
+
+	public const TYPES = self::TYPES_FILE + self::TYPES_DIR_LIKE;
+	public const TYPES_DIR_LIKE = self::TYPES_DIR + self::TYPES_REPO;
+	public const TYPES_DIR = [self::TYPE_DIR => self::TYPE_DIR];
+	public const TYPES_FILE = [self::TYPE_FILE => self::TYPE_FILE];
+	public const TYPES_REPO = [self::TYPE_REPO => self::TYPE_REPO, self::TYPE_SREPO => self::TYPE_SREPO, self::TYPE_GREPO => self::TYPE_GREPO];
+
+	/**
+	 * @const string
+	 */
+	public const STRING_SUCCESS = 'success';
+
+	/**
+	 * Error codes
+	 */
+	public const ERROR_CODE_FEATURES = 802;
+	public const ERROR_CODE_NO_CURL = 803;
+	public const ERROR_CODE_FILE_IO = 808;
+
+	/**
+	 * default curl options
+	 */
+	private const CURL_OPTION_DEFAULTS = [
+		CURLOPT_AUTOREFERER => true,
+		CURLOPT_TIMEOUT => 10,
+		CURLOPT_RETURNTRANSFER => true,
+		CURLOPT_FOLLOWLOCATION => false,
+	];
+
+	/**
+	 * @var array shared curl options between all requests
+	 */
+	private array $curlSharedOptions = self::CURL_OPTION_DEFAULTS;
+
+	/**
+	 * jsonDecode accept flags
+	 *
+	 * @see jsonDecode
+	 */
+	private const JSON_DECODE_ACCEPT_MASK = 31;                         # 1 1111 accept bitmask (five bits with the msb flags)
+	private const JSON_DECODE_ACCEPT_JSON = 16;                         # 1 0000 JSON text
+	private const JSON_DECODE_ACCEPT_DEFAULT = 23;                      # 1 0111 default: string, array or object
+	private const JSON_DECODE_ACCEPT_OBJECT = 17;                       # 1 0001 object
+	private const JSON_DECODE_ACCEPT_ARRAY = 18;                        # 1 0010 array
+	private const JSON_DECODE_ACCEPT_STRING = 20;                       # 1 0100 string
+	private const JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS = 24;             # 1 1000 array with only objects (incl. none)
+	private const JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT = 25;          # 1 1001 array with one single object, return that item
+	private const JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT_NULLABLE = 26; # 1 1010 array with one single object, return that item, or empty array, return null
+	private const JSON_DECODE_ACCEPT_SUCCESS_STRING = 28;               # 1 1100 string "success"
+	private const JSON_DECODE_ACCEPT_SUCCESS_OBJECT = 29;               # 1 1101 object with single "success" property and value true
+
+	/**
+	 * @const string ASCII upper-case characters part of a hexit
+	 */
+	private const HEX_ALPHA_UPPER = 'ABCDEF';
+
+	/**
+	 * @const string ASCII lower-case characters part of a hexit
+	 */
+	private const HEX_ALPHA_LOWER = 'abcdef';
+
+	/**
+	 * @var string Server base URL
+	 */
+	private string $baseurl;
+
+	/**
+	 * @var string Username
+	 */
+	private string $user;
+
+	/**
+	 * @var string Password
+	 */
+	private string $pass;
+
+	private ?CurlHandle $handle = null;
+
+	/**
+	 * @var string
+	 */
+	private string $token = '';
+
+	/**
+	 * constructor
+	 *
+	 * @param string $baseurl
+	 * @param string $user
+	 * @param string $pass
+	 * @param string|null $otp
+	 */
+	public function __construct(string $baseurl, string $user, string $pass, string $otp = null)
+	{
+		if (!(function_exists('curl_version'))) {
+			throw new ConnectionException('PHP-CURL not installed', self::ERROR_CODE_NO_CURL);
+		}
+
+		$this->baseurl = $baseurl;
+		$this->user = $user;
+		$this->pass = $pass;
+		// trigger_error(sprintf("ctor: %s:%s", $user, $pass), E_USER_NOTICE);
+
+		$this->setTokenByUsernameAndPassword($otp);
+	}
+
+	/**
+	 * ping (with authentication)
+	 *
+	 * @link https://download.seafile.com/published/web-api/home.md#user-content-Quick%20Start
+	 *
+	 * @return string "pong"
+	 */
+	public function ping(): string
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/ping/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_STRING,
+		);
+	}
+
+	/**
+	 * get server version
+	 *
+	 * @throws Exception
+	 * @return string
+	 */
+	public function getServerVersion(): string
+	{
+		$serverInfo = $this->getServerInformation();
+		if (
+			!is_string($serverInfo->version ?? null)
+			|| !is_array($serverInfo->features ?? null)
+		) {
+			throw new InvalidResponseException('We could not retrieve list of server features.', self::ERROR_CODE_FEATURES);
+		}
+
+		$isSeafilePro = in_array('seafile-pro', $serverInfo->features, true);
+		$edition = $isSeafilePro ? 'Professional' : 'Community';
+
+		return "$serverInfo->version ($edition)";
+	}
+
+	/**
+	 * get server information
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/server-info.md#user-content-Get%20Server%20Information
+	 *
+	 * @throws Exception
+	 * @return object
+	 */
+	public function getServerInformation(): object
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/server-info/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * check account info
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/account.md#user-content-Check%20Account%20Info
+	 * @return object
+	 */
+	public function checkAccountInfo(): object
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/account/info/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]]
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * list seafile server libraries
+	 *
+	 * that are all libraries a user can access.
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-List%20Libraries
+	 *
+	 * @throws Exception
+	 * @return object[]
+	 */
+	public function listLibraries(): array
+	{
+		return $this->listLibrariesCached(true);
+	}
+
+	/**
+	 * get default library
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Get%20Default%20Library
+	 *
+	 * @return object{exists: bool, repo_id: string}
+	 */
+	public function getDefaultLibrary(): object
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/default-repo/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * create a library
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Create%20Library
+	 *
+	 * @param string $name of library
+	 * @return object
+	 */
+	public function createLibrary(string $name): object
+	{
+		$name = trim($name, "/");
+
+		return $this->jsonDecode(
+			$this->post(
+				"$this->baseurl/api2/repos/",
+				['name' => $name],
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * name a library
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Rename%20Library
+	 */
+	public function nameLibrary(string $lib, string $name): void
+	{
+		$lib = $this->verifyLib($lib);
+		$fields = ['repo_name' => $name];
+		$_ = $this->jsonDecode(
+			$this->post(
+				"$this->baseurl/api2/repos/$lib/?op=rename",
+				$fields,
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_SUCCESS_STRING,
+		);
+		unset($_);
+	}
+
+	/**
+	 * rename a library
+	 *
+	 * do nothing if the library can not be found
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Rename%20Library
+	 *
+	 * @param string $oldName
+	 * @param string $newName
+	 * @return void
+	 */
+	public function renameLibrary(string $oldName, string $newName): void
+	{
+		$lib = $this->getLibraryIdByLibraryName($oldName);
+		if (null === $lib) {
+			return; // no library to rename
+		}
+
+		$this->nameLibrary($lib, $newName);
+	}
+
+	/**
+	 * delete a library by name
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Delete%20Library
+	 *
+	 * @param string $name
+	 * @return void
+	 */
+	public function deleteLibraryByName(string $name): void
+	{
+		$id = $this->getLibraryIdByLibraryName($name);
+		if (null === $id) {
+			return; // library already gone
+		}
+
+		$this->deleteLibraryById($id);
+	}
+
+	/**
+	 * delete a library by id
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-Delete%20Library
+	 *
+	 * @param string $id
+	 * @return void
+	 */
+	public function deleteLibraryById(string $id): void
+	{
+		$lib = $this->verifyLib($id);
+
+		$_ = $this->jsonDecode(
+			$this->delete(
+				"$this->baseurl/api2/repos/$lib/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_SUCCESS_STRING,
+		);
+		unset($_);
+	}
+
+	/**
+	 * get library info array from path
+	 *
+	 * @param string $libNamedPath with the library name as first component
+	 * @throws Exception
+	 * @throws InvalidResponseException
+	 * @return object with 'id' and 'name' of library, both NULL if not found
+	 */
+	public function getLibraryFromPath(string $libNamedPath): object
+	{
+		$libraries = $this->listLibrariesCached();
+		$libraries = array_column($libraries, null, 'name');
+
+		$name = explode('/', ltrim($this->normalizePath($libNamedPath), '/'), 2)[0];
+
+		return (object)[
+			'id' => $libraries[$name]->id ?? null,
+			'name' => $libraries[$name]->name ?? null,
+		];
+	}
+
+	/**
+	 * list all share links
+	 *
+	 * all folder/file download share links in all libraries created by user.
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/share-links.md#user-content-List%20all%20Share%20Links
+	 *
+	 * @return object[]
+	 * @throws Exception
+	 * @throws InvalidResponseException
+	 * @noinspection PhpUnused
+	 */
+	public function listAllShareLinks(): array
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api/v2.1/share-links/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS,
+		);
+	}
+
+	/**
+	 * Create Share Link
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/share-links.md#user-content-Create%20Share%20Link
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @param ?string $password [optional]
+	 * @param ?int|DateTimeInterface $expire [optional] number of days to expire (int) or DateTime to expire
+	 * @param ?array $permissions [optional] see seafile api docs
+	 * @return object
+	 * @throws Exception
+	 * @throws InvalidArgumentException
+	 * @throws InvalidResponseException
+	 */
+	public function createShareLink(string $lib, string $path, string $password = null, $expire = null, array $permissions = null): object
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+
+		$fields = [
+			'repo_id' => $lib,
+			'path' => $path,
+		];
+		if (null !== $password) {
+			$fields['password'] = $password;
+		}
+		if (null !== $expire) {
+			$expireTime = $expire;
+			if (is_int($expire)) {
+				$expireDays = max(1, min(365, (int)$expire));
+				$expireTime = (new DateTimeImmutable())->add(
+					new \DateInterval("P{$expireDays}D")
+				);
+			}
+			if (!$expireTime instanceof DateTimeInterface) {
+				throw new InvalidArgumentException('Expire type mismatch: ' . gettype($expireTime));
+			}
+			$fields['expiration_time'] = $expireTime->format(\DATE_ATOM);
+		}
+		if (null !== $permissions) {
+			try {
+				$fields['permissions'] = json_encode($permissions, JSON_THROW_ON_ERROR);
+			} /** @noinspection PhpMultipleClassDeclarationsInspection */ catch (JsonException $ex) {
+				throw new InvalidArgumentException('permissions');
+			}
+		}
+
+		return $this->jsonDecode(
+			$this->post(
+				"$this->baseurl/api/v2.1/share-links/",
+				$fields,
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * List Share Links of a Library
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/share-links.md#user-content-List%20all%20Share%20Links
+	 *
+	 * @param ?string $lib [optional] library id (guid), default/null for all libraries
+	 * @throws Exception
+	 * @return object[]
+	 */
+	public function listShareLinksOfALibrary(string $lib = null): array
+	{
+		$lib = $this->verifyLib($lib ?? '', true);
+
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api/v2.1/share-links/?repo_id=$lib",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS,
+		);
+	}
+
+	/**
+	 * check password (of a share link by token)
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1-admin/share-links.md#user-content-Check%20Password
+	 *
+	 * @param string $token of share link
+	 * @param string $password in plain
+	 * @return object
+	 * @throws Exception
+	 * @throws InvalidResponseException
+	 * @noinspection PhpUnused
+	 */
+	public function checkShareLinkPassword(string $token, string $password): object
+	{
+		$tokenEncoded = rawurlencode($token);
+
+		return $this->jsonDecode(
+			$this->post(
+				"$this->baseurl/api/v2.1/admin/share-links/$tokenEncoded/check-password/",
+				['password' => $password],
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_SUCCESS_OBJECT,
+		);
+	}
+
+	/**
+	 * share Link of a folder (or file)
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/share-links.md#user-content-List%20Share%20Link%20of%20a%20Folder%20(File)
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @return object the share link
+	 * @throws Exception
+	 * @throws InvalidArgumentException
+	 * @throws InvalidResponseException
+	 * @noinspection PhpUnused
+	 */
+	public function listShareLinksOfAFolder(string $lib, string $path): ?object
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api/v2.1/share-links/?repo_id=$lib&path=$pathEncoded",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT_NULLABLE,
+		);
+	}
+
+	/**
+	 * Delete Share Link
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/share-links.md#user-content-Delete%20Share%20Link
+	 *
+	 * @param string $token
+	 * @throws Exception
+	 * @return object success {"success": true}
+	 */
+	public function deleteShareLink(string $token): object
+	{
+		$token = $this->verifyToken($token);
+
+		return $this->jsonDecode(
+			$this->delete(
+				"$this->baseurl/api/v2.1/share-links/$token/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_SUCCESS_OBJECT,
+		);
+	}
+
+	/**
+	 * search user
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/user-search.md#user-content-Search%20User
+	 *
+	 * @param string $search
+	 * @throws Exception
+	 * @return object
+	 */
+	public function searchUser(string $search): object
+	{
+		$searchEncoded = rawurlencode($search);
+
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/search-user/?q=$searchEncoded",
+				[CURLOPT_HTTPHEADER => ['Authorization: Token ' . $this->token]],
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * list groups for user sharing
+	 *
+	 * @throws Exception
+	 * @throws InvalidResponseException
+	 * @return array|object|string
+	 * @link (undocumented)
+	 *
+	 */
+	public function shareableGroups(): array
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api/v2.1/shareable-groups/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS,
+		);
+	}
+
+	/**
+	 * Share a Library to Group
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/share.md#user-content-Share%20a%20Library%20to%20Group
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @param int|int[] $group
+	 * @param string|null $permission [optional] r, rw, admin (default: r)
+	 * @throws Exception
+	 * @throws InvalidArgumentException
+	 * @return array
+	 */
+	public function shareLibraryPathToGroup(string $lib, string $path, $group, string $permission = null)
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+
+		$fields = [
+			'share_type' => 'group',
+			'group_id' => $group,
+			'permission' => $permission ?? 'r',
+		];
+		return $this->jsonDecode(
+			$this->put(
+				"$this->baseurl/api2/repos/$lib/dir/shared_items/?p=$pathEncoded",
+				$fields,
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * Share a Library to User
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/share.md#user-content-Share%20a%20Library%20to%20User
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @param string $user
+	 * @param string|null $permission [optional] r, rw, admin (default: r)
+	 * @throws Exception
+	 * @throws InvalidArgumentException
+	 * @return array
+	 */
+	public function shareLibraryPathToUser(string $lib, string $path, string $user, string $permission = null)
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+
+		$fields = [
+			'share_type' => 'user',
+			'username' => $user,
+			'permission' => $permission ?? 'r',
+		];
+		return $this->jsonDecode(
+			$this->put(
+				"$this->baseurl/api2/repos/$lib/dir/shared_items/?p=$pathEncoded",
+				$fields,
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			// either array of objects -or- failure object
+			self::JSON_DECODE_ACCEPT_ARRAY | self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * Unshare a Library to Group
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/share.md#user-content-Unshare%20a%20Library%20from%20Group
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @param int $group
+	 * @throws Exception
+	 * @throws InvalidArgumentException
+	 * @return object
+	 */
+	public function unshareLibraryPathToGroup(string $lib, string $path, int $group): object
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+
+		return $this->jsonDecode(
+			$this->delete(
+				"$this->baseurl/api2/repos/$lib/dir/shared_items/?p=$pathEncoded&share_type=group&group_id=$group",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_SUCCESS_OBJECT,
+		);
+	}
+
+	/**
+	 * Unshare a Library to User
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/share.md#user-content-Unshare%20a%20Library%20from%20User
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @param string|string[] $user
+	 * @throws Exception
+	 * @throws InvalidArgumentException
+	 * @return object
+	 */
+	public function unshareLibraryPathToUser(string $lib, string $path, $user): object
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+		$userEncoded = rawurlencode($user);
+
+		return $this->jsonDecode(
+			$this->delete(
+				"$this->baseurl/api2/repos/$lib/dir/shared_items/?p=$pathEncoded&share_type=user&username=$userEncoded",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_SUCCESS_OBJECT,
+		);
+	}
+
+	/**
+	 * list user shares for a library path
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/share.md#user-content-List%20Shared%20Users%20of%20a%20Library
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @throws Exception
+	 * @throws InvalidArgumentException
+	 * @throws InvalidResponseException
+	 * @return array<int, object>
+	 */
+	public function listSharesOfLibraryPath(string $lib, string $path): array
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/repos/$lib/dir/shared_items/?p=$pathEncoded",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS,
+		);
+	}
+
+	/**
+	 * create a new directory
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/directories.md#user-content-Create%20New%20Directory
+	 *
+	 * @param string $lib library id (guid)
+	 * @param string $path of the directory to create (e.g.: "/path/to/new-directory", leading and trailing slashes can be omitted)
+	 * @throws InvalidArgumentException|Exception
+	 * @return string|object the common "success" or the object with error_msg property
+	 */
+	public function createNewDirectory(string $lib, string $path)
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+
+		return $this->jsonDecode(
+			$this->post(
+				"$this->baseurl/api2/repos/$lib/dir/?p=$pathEncoded",
+				['operation' => 'mkdir'],
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_STRING | self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * delete a file
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/file.md#user-content-Delete%20File
+	 *
+	 * @param string $lib library id (guid)
+	 * @param string $path of the fle to delete (e.g.: "/path/to/file-to-delete", leading and trailing slashes can be omitted)
+	 * @throws InvalidArgumentException|Exception
+	 * @return string|object the common "success" or the known object with error_msg property
+	 */
+	public function deleteFile(string $lib, string $path)
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+
+		return $this->jsonDecode(
+			$this->delete(
+				"$this->baseurl/api2/repos/$lib/file/?p=$pathEncoded",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_STRING | self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * get a file download URL
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/file.md#user-content-Download%20File
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @return string download URL (http/s)
+	 * @throws InvalidArgumentException|Exception
+	 */
+	public function downloadFile(string $lib, string $path): string
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/repos/$lib/file/?p=$pathEncoded",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_STRING,
+		);
+	}
+
+	/**
+	 * download a file
+	 *
+	 * get file contents of a file in a library
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @throws InvalidArgumentException|Exception
+	 * @return string|false on failure
+	 */
+	public function downloadFileAsBuffer(string $lib, string $path)
+	{
+		$url = $this->downloadFile($lib, $path);
+
+		return $this->get($url);
+	}
+
+	/**
+	 * download a file to a local file
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @param string $localPath path to a file - existing or not - on the local file-system
+	 * @throws InvalidArgumentException|Exception
+	 * @return bool success/failure
+	 */
+	public function downloadFileToFile(string $lib, string $path, string $localPath): bool
+	{
+		$handle = fopen($localPath, 'wb');
+		if (false === $handle) {
+			throw new Exception('failed to open local path for writing', self::ERROR_CODE_FILE_IO);
+		}
+
+		try {
+			$result = $this->downloadFileToStream($lib, $path, $handle);
+		} finally {
+			$close = fclose($handle);
+		}
+
+		if (!$close) {
+			throw new Exception('failed to close local path handle', self::ERROR_CODE_FILE_IO);
+		}
+
+		return $result;
+	}
+
+	/**
+	 * download a file to a stream handle
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @param resource $handle stream handle
+	 * @throws InvalidArgumentException|Exception
+	 * @return bool success/failure
+	 */
+	public function downloadFileToStream(string $lib, string $path, $handle): bool
+	{
+		$url = $this->downloadFile($lib, $path);
+
+		return $this->get($url, [CURLOPT_RETURNTRANSFER => true, CURLOPT_FILE => $handle]);
+	}
+
+	/**
+	 * list items in directory
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/directories.md#user-content-List%20Items%20in%20Directory
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @return array
+	 * @throws Exception
+	 * @throws InvalidArgumentException
+	 * @throws InvalidResponseException
+	 */
+	public function listItemsInDirectory(string $lib, string $path): array
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+
+		$result = $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/repos/$lib/dir/?p=$pathEncoded",
+				[CURLOPT_HTTPHEADER => ['Authorization: Token ' . $this->token]],
+			),
+		);
+
+		if (is_object($result)) {
+			// likely a folder not found.
+			$result = [];
+		}
+
+		return $result;
+	}
+
+	/**
+	 * move a file
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/file.md#user-content-Move%20File
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @param string $dstLib
+	 * @param string $dstDir
+	 * @return object
+	 * @throws InvalidArgumentException|Exception
+	 */
+	public function moveFile(string $lib, string $path, string $dstLib, string $dstDir): object
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+		$dstLib = $this->verifyLib($dstLib);
+		$dstDir = $this->normalizePath($dstDir);
+
+		return $this->jsonDecode(
+			$this->post(
+				"$this->baseurl/api2/repos/$lib/file/?p=$pathEncoded",
+				['operation' => 'move', 'dst_repo' => $dstLib, 'dst_dir' => $dstDir],
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * rename a file
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/file.md#user-content-Move%20File
+	 *
+	 * @param string $lib library id (guid)
+	 * @param string $path of the file to rename (e.g. "/path/to/file-to-rename")
+	 * @param string $newName new basename for the basename of $path (e.g. "new-file-name")
+	 * @return string|object the common "success" or the known object with error_msg property
+	 * @throws Exception
+	 */
+	public function renameFile(string $lib, string $path, string $newName)
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		$pathEncoded = rawurlencode($path);
+
+		return $this->jsonDecode(
+			$this->post(
+				"$this->baseurl/api2/repos/$lib/file/?p=$pathEncoded",
+				['operation' => 'rename', 'newname' => $newName],
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_STRING | self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * simplified file upload routine for string buffer
+	 *
+	 * @param string $lib
+	 * @param string $path
+	 * @param string $buffer
+	 * @throws InvalidArgumentException
+	 * @throws Exception
+	 * @return object
+	 */
+	public function uploadBuffer(string $lib, string $path, string $buffer): object
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+
+		$parentDir = dirname($path);
+		$uploadLink = $this->uploadGetLink($lib, $parentDir);
+		$fileName = basename($path);
+
+		return $this->uploadFileBuffer($uploadLink, $parentDir, '', $buffer, $fileName);
+	}
+
+	/**
+	 * simplified file upload routine for standard file
+	 *
+	 * @param string $lib
+	 * @param string $path path in seafile to upload the file as
+	 * @param string $file path of file to upload
+	 * @throws InvalidArgumentException
+	 * @throws Exception
+	 * @return object
+	 */
+	public function uploadFile(string $lib, string $path, string $file): object
+	{
+		$lib = $this->verifyLib($lib);
+		$path = $this->normalizePath($path);
+		if (!is_file($file) && !is_readable($file)) {
+			throw new InvalidArgumentException(sprintf('Not a readable file: %s', $file));
+		}
+
+		$parentDir = dirname($path);
+		$uploadLink = $this->uploadGetLink($lib, $parentDir);
+		$fileName = basename($path);
+
+		return $this->uploadFilePath($uploadLink, $parentDir, '', $file, $fileName);
+	}
+
+	/**
+	 * upload string buffer as a file
+	 *
+	 * same as {@see SeafileApi::uploadFile()} with the option to upload without a
+	 * concrete file on the system. the temporary file to upload is created
+	 * from the string buffer.
+	 *
+	 * @param string $uploadLink from {@see uploadGetLink}
+	 * @param string $parentDir the parent directory to upload the file to
+	 * @param string $relativePath the name of the file, subdirectories possible (e.g. uploading a folder)
+	 * @param string $buffer file contents to upload as string (not the file-name)
+	 * @param string $fileName to use as basename for the data
+	 * @param bool $replace
+	 * @throws Exception
+	 * @return object
+	 */
+	public function uploadFileBuffer(
+		string $uploadLink, string $parentDir, string $relativePath,
+		string $buffer, string $fileName = 'upload.dat', bool $replace = false
+	): object
+	{
+		$tmpHandle = tmpfile();
+		if (false === $tmpHandle) {
+			throw new Exception('Upload data rejected: Unable to open temporary stream.');
+		}
+
+		$meta = stream_get_meta_data($tmpHandle);
+		$tmpFile = $meta['uri'];
+		if (!is_file($tmpFile)) {
+			fclose($tmpHandle);
+			throw new Exception('Upload data rejected: No file with temporary stream.');
+		}
+
+		$bytes = fwrite($tmpHandle, $buffer);
+		if (false === $bytes) {
+			fclose($tmpHandle);
+			throw new Exception('Upload data rejected: Failed to write to temporary stream.');
+		}
+
+		$diff = strlen($buffer) - $bytes;
+		if ($diff !== 0) {
+			fclose($tmpHandle);
+			throw new Exception(sprintf("Upload data rejected: Unexpected difference writing to temporary stream: %d bytes", $diff));
+		}
+
+		$result = rewind($tmpHandle);
+		if (false === $result) {
+			fclose($tmpHandle);
+			throw new Exception('Upload data rejected: Failed to rewind temporary stream.');
+		}
+
+		$result = $this->uploadFilePath($uploadLink, $parentDir, $relativePath, $tmpFile, $fileName, $replace);
+		fclose($tmpHandle);
+
+		return $result;
+	}
+
+	/**
+	 * upload file
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/file-upload.md#user-content-Upload%20File
+	 *
+	 * @param string $uploadLink from {@see uploadGetLink}
+	 * @param string $parentDir the parent directory to upload a file to
+	 * @param string $relativePath to place the file in under $uploadPath (can include subdirectories)
+	 * @param string $path path of the file to upload
+	 * @param ?string $fileName to use as basename for the file (the name used in Seafile)
+	 * @param bool $replace
+	 * @return object
+	 * @throws Exception
+	 */
+	public function uploadFilePath(
+		string $uploadLink, string $parentDir, string $relativePath,
+		string $path, string $fileName = null, bool $replace = false
+	): object
+	{
+		$parentDir = $this->normalizePath($parentDir);
+		$relativePath = ltrim('/', $this->normalizePath($relativePath));
+		$fileName = $fileName ?? basename($path);
+
+		$fields = [
+			'file' => new CURLFile($path, 'application/octet-stream', $fileName),
+			'parent_dir' => $parentDir,
+			'relative_path' => $relativePath,
+			'replace' => $replace ? '1' : '0',
+		];
+
+		return $this->jsonDecode(
+			$this->post(
+				"$uploadLink?ret-json=1",
+				$fields,
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT,
+		);
+	}
+
+	/**
+	 * get file upload link
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/file-upload.md#user-content-Get%20Upload%20Link
+	 *
+	 * @param string $lib
+	 * @param string $uploadDir the directory to upload file(s) to
+	 * @return string upload link (https?://...)
+	 * @throws InvalidArgumentException|Exception
+	 */
+	public function uploadGetLink(string $lib, string $uploadDir): string
+	{
+		$lib = $this->verifyLib($lib);
+		$uploadDir = $this->normalizePath($uploadDir);
+		$pathEncoded = rawurlencode($uploadDir);
+
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/repos/$lib/upload-link/?p=$pathEncoded",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_STRING,
+		);
+	}
+
+	public function generateUserAuthToken(string $email): object
+	{
+		return $this->jsonDecode(
+			$this->post(
+				"$this->baseurl/api/v2.1/admin/generate-user-auth-token/",
+				['email' => $email],
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	public function getUserActivity(string $email, int $page = 1, int $perPage = 25): object
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api/v2.1/admin/user-activities/?user=$email&page=$page&per_page=$perPage",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+	}
+
+	/**
+	 * set authorization token
+	 *
+	 * @param string $token
+	 * @return void
+	 */
+	public function setToken(string $token): void
+	{
+		$this->token = $token;
+	}
+
+	public function listDevices(): array
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/devices/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+		);
+	}
+
+	public function listStarredItems(): object
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api/v2.1/starred-items/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+		);
+	}
+
+	public function listGroups(): object
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/groups/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+		);
+	}
+
+	public function listInvitations(): array
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api/v2.1/invitations/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+		);
+	}
+
+	/**
+	 * @param string $start e.g. date('Y-m-d', time() - 7776000 ); // 3 months
+	 * @param string $end e.g. date('Y-m-d', time());
+	 *
+	 * @return array
+	 */
+	public function getLoginLog(string $start, string $end): array
+	{
+		$start = rawurlencode($start);
+		$end = rawurlencode($end);
+
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api/v2.1/admin/logs/login/?start=$start&end=$end",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+		);
+	}
+
+	public function listUploadLinks(): array
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api/v2.1/upload-links/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+		);
+	}
+
+	public function listRepoApiTokens(string $lib): object
+	{
+		$lib = $this->verifyLib($lib);
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api/v2.1/repos/$lib/repo-api-tokens/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+		);
+	}
+
+	/**
+	 * internal api implementation to get library by name
+	 *
+	 * @param string $name
+	 * @throws Exception
+	 * @return ?string id (guid) of the library, null if library does not exist
+	 */
+	private function getLibraryIdByLibraryName(string $name): ?string
+	{
+		$name = explode('/', $this->normalizePath($name), 2)[1];
+
+		$libraries = $this->listLibrariesCached();
+		$libraries = array_column($libraries, null, 'name');
+		return $libraries[$name]->id ?? null;
+	}
+
+	/**
+	 * List libraries a user can access.
+	 *
+	 * internal api implementation for {@see listLibrariesCached()} and {@see listLibraries()}
+	 *
+	 * @link https://download.seafile.com/published/web-api/v2.1/libraries.md#user-content-List%20Libraries
+	 *
+	 * @throws Exception
+	 * @return object[]
+	 */
+	private function listLibrariesDo(): array
+	{
+		return $this->jsonDecode(
+			$this->get(
+				"$this->baseurl/api2/repos/",
+				[CURLOPT_HTTPHEADER => ["Authorization: Token $this->token"]],
+			),
+			self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS,
+		);
+	}
+
+	/**
+	 * like {@see listLibraries()} but cached.
+	 *
+	 * @param bool $invalidate
+	 * @throws Exception
+	 * @throws InvalidResponseException
+	 * @return void
+	 */
+	private function listLibrariesCached(bool $invalidate = false): array
+	{
+		static $librariesCache;
+
+		return $librariesCache = ($invalidate ? null : $librariesCache) ?? $this->listLibrariesDo();
+	}
+
+	/**
+	 * normalize path
+	 *
+	 * normalizes the path component separator <slash> "/" <U002F> U+002F SOLIDUS
+	 * with first character being the slash, no consecutive slashes within the
+	 * path and no terminating slash.
+	 *
+	 * @param string $path
+	 * @return string
+	 */
+	private function normalizePath(string $path): string
+	{
+		$buffer = rtrim($path, '/');
+		$buffer = preg_replace('~/{2,}~', '/', $buffer);
+		'' === $buffer && $buffer = '/';
+		'/' === $buffer[0] || $buffer = "/$buffer";
+
+		return $buffer;
+	}
+
+	/**
+	 * verify library id
+	 *
+	 * verifies the format of a library id. can be used in URLs
+	 * afterwards. case normalization to lowercase.
+	 *
+	 * example library id strings:
+	 *  - 21b941c2-5411-4372-a514-00b62ab99ef2 (from the docs)
+	 *  - 79144b25-f772-42b6-a1c0-60e6359f5884 (from a server)
+	 *
+	 * @param string $lib
+	 * @param bool $allowEmpty
+	 * @return string library id
+	 */
+	private function verifyLib(string $lib, bool $allowEmpty = false): string
+	{
+		if ($allowEmpty && ('' === $lib)) {
+			return $lib;
+		}
+
+		$buffer = strtr($lib, self::HEX_ALPHA_UPPER, self::HEX_ALPHA_LOWER);
+		$format = '%04x%04x-%04x-%04x-%04x-%04x%04x%04x';
+		$values = sscanf($buffer, $format);
+		$result = vsprintf($format, $values);
+
+		if ($buffer !== $result) {
+			throw new InvalidArgumentException(sprintf('Not a library id: "%s"', $lib));
+		}
+
+		return $result;
+	}
+
+	/**
+	 * verify share link token
+	 *
+	 * verifies the format of a share link token. can be used in URLs
+	 * afterwards. case normalization to lowercase.
+	 *
+	 * @param string $token e.g. "0a29ff44dc0b4b56be74"
+	 * @return string
+	 */
+	private function verifyToken(string $token): string
+	{
+		$buffer = strtr($token, self::HEX_ALPHA_UPPER, self::HEX_ALPHA_LOWER);
+		$format = '%04x%04x%04x%04x%04x';
+		$values = sscanf($buffer, $format);
+		$result = vsprintf($format, $values);
+
+		if ($buffer !== $result) {
+			throw new InvalidArgumentException(sprintf('Not a token: "%s"', $token));
+		}
+
+		return $result;
+	}
+
+	/**
+	 * authenticate class against seafile api
+	 *
+	 * @link https://download.seafile.com/published/web-api/home.md#user-content-Quick%20Start
+	 *
+	 * @param string|null $otp (optional) Seafile OTP (if user uses OTP access)
+	 * @return void
+	 */
+	private function setTokenByUsernameAndPassword(string $otp = null): void
+	{
+		// @auth:token:<email> : password is auth token
+		if (0 === strpos($this->user, $needle = self::USER_PREFIX_AUTH_TOKEN)) {
+			$this->user = \substr($this->user, strlen($needle)) ?: '';
+			$this->token = $this->pass;
+			if ('pong' !== $this->ping()) {
+				throw new ConnectionException('token authentication failure');
+			}
+			return;
+		}
+
+		$data = $this->jsonDecode(
+			$this->post(
+				"$this->baseurl/api2/auth-token/",
+				['username' => $this->user, 'password' => $this->pass],
+				$otp ? [CURLOPT_HTTPHEADER => ["X-SEAFILE-OTP: $otp"]] : [],
+			),
+			self::JSON_DECODE_ACCEPT_OBJECT,
+		);
+		$this->token = (string)$data->token;
+	}
+
+	/**
+	 * http request with get method
+	 *
+	 * @param string $url
+	 * @param array $curlOptions
+	 * @return bool|string
+	 */
+	private function get(string $url, array $curlOptions = [])
+	{
+		$curlOptions += $this->curlSharedOptions;
+
+		return $this->curlExec($url, $curlOptions);
+	}
+
+	/**
+	 * http request with post method
+	 *
+	 * @param string $url
+	 * @param array $fields
+	 * @param array $curlOptions
+	 * @return bool|string
+	 */
+	private function post(string $url, array $fields = [], array $curlOptions = [])
+	{
+		$curlOptions += $this->curlSharedOptions;
+		$curlOptions[CURLOPT_POST] = true;
+		$curlOptions[CURLOPT_POSTFIELDS] = $fields;
+
+		return $this->curlExec($url, $curlOptions);
+	}
+
+	/**
+	 * http request with put method
+	 *
+	 * @param string $url
+	 * @param array $fields
+	 * @param array $curlOptions
+	 * @return bool|string
+	 */
+	public function put(string $url, array $fields = [], array $curlOptions = [])
+	{
+		$curlOptions += $this->curlSharedOptions;
+		$curlOptions[CURLOPT_CUSTOMREQUEST] = 'PUT';
+		$curlOptions[CURLOPT_POSTFIELDS] = $fields;
+
+		return $this->curlExec($url, $curlOptions);
+	}
+
+	/**
+	 * http request with delete method
+	 *
+	 * @param string $url
+	 * @param array $curlOptions
+	 * @return bool|string
+	 */
+	public function delete(string $url, array $curlOptions = [])
+	{
+
+		$curlOptions += $this->curlSharedOptions;
+		$curlOptions[CURLOPT_CUSTOMREQUEST] = 'DELETE';
+
+		return $this->curlExec($url, $curlOptions);
+	}
+
+	/**
+	 * json decode handler
+	 *
+	 * decode json with structural acceptance
+	 *
+	 * @param string $jsonText
+	 * @param int $flags decode accept flag
+	 * @throws InvalidResponseException
+	 * @return string|object|array
+	 */
+	private function jsonDecode(string $jsonText, int $flags = self::JSON_DECODE_ACCEPT_DEFAULT)
+	{
+		$accept = $flags & self::JSON_DECODE_ACCEPT_MASK;
+		if (0 === $accept) {
+			return $jsonText;
+		}
+
+		try {
+			$result = json_decode($jsonText, false, 512, JSON_THROW_ON_ERROR);
+		} /** @noinspection PhpMultipleClassDeclarationsInspection */ catch (JsonException $e) {
+			throw JsonDecodeException::create(sprintf('json decode error of %s', JsonDecodeException::shorten($jsonText)), $jsonText, $e);
+		}
+
+		if (self::JSON_DECODE_ACCEPT_JSON === $accept) {
+			return $result;
+		}
+
+		if (self::JSON_DECODE_ACCEPT_ARRAY_OF_OBJECTS === $accept) {
+			if (is_array($result) && $result === array_filter($result, 'is_object')) {
+				return $result;
+			}
+			throw JsonDecodeException::create(sprintf('json decode accept %5d error [%s] of %s', decbin($accept), gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
+		}
+
+		if (self::JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT_NULLABLE === $accept) {
+			if (is_array($result)
+				&& (
+					(count($result) === 1 && is_object($result[0] ?? null))
+					|| (count($result) === 0)
+				)
+			) {
+				return $result[0] ?? null;
+			}
+			throw JsonDecodeException::create(sprintf('json decode accept %5d error [%s] of %s', decbin($accept), gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
+		}
+
+		if (self::JSON_DECODE_ACCEPT_ARRAY_SINGLE_OBJECT === $accept) {
+			if (is_array($result) && is_object($result[0] ?? null) && count($result) === 1) {
+				return $result[0];
+			}
+			throw JsonDecodeException::create(sprintf('json decode accept %5d error [%s] of %s', decbin($accept), gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
+		}
+
+		if (self::JSON_DECODE_ACCEPT_SUCCESS_OBJECT === $accept) {
+			if (is_object($result) && (array)$result === ['success' => true]) {
+				return $result;
+			}
+			throw JsonDecodeException::create(sprintf('json decode accept %5d error [%s] of %s', decbin($accept), gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
+		}
+
+		if (self::JSON_DECODE_ACCEPT_SUCCESS_STRING === $accept) {
+			if (self::STRING_SUCCESS === $result) {
+				return $result;
+			}
+			throw JsonDecodeException::create(sprintf('json decode accept %5d error [%s] of %s', decbin($accept), gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
+		}
+
+		if (is_string($result) && (self::JSON_DECODE_ACCEPT_STRING !== ($accept & self::JSON_DECODE_ACCEPT_STRING))) {
+			throw JsonDecodeException::create(sprintf('json decode type %s not accepted; of %s', gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
+		}
+
+		if (is_array($result) && (self::JSON_DECODE_ACCEPT_ARRAY !== ($accept & self::JSON_DECODE_ACCEPT_ARRAY))) {
+			throw JsonDecodeException::create(sprintf('json decode type %s not accepted; of %s', gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
+		}
+
+		if (is_object($result) && (self::JSON_DECODE_ACCEPT_OBJECT !== ($accept & self::JSON_DECODE_ACCEPT_OBJECT))) {
+			throw JsonDecodeException::create(sprintf('json decode type %s not accepted; of %s', gettype($result), JsonDecodeException::shorten($jsonText)), $jsonText);
+		}
+
+		return $result;
+	}
+
+
+	/**
+	 * execute curl with url and options
+	 *
+	 * @param string $url
+	 * @param array $options
+	 * @return bool|string
+	 */
+	private function curlExec(string $url, array $options)
+	{
+		$handle = curl_init($url);
+		if (!($handle instanceof CurlHandle)) {
+			throw new ConnectionException('Unable to initialise cURL session.', self::ERROR_CODE_NO_CURL);
+		}
+
+		$this->handle = $handle;
+
+		if (!curl_setopt_array($this->handle, $options)) {
+			throw new Exception("Error setting cURL request options.");
+		}
+		$result = curl_exec($this->handle);
+		$this->curlExecHandleResult($result);
+		curl_close($this->handle);
+
+		return $result;
+	}
+
+	/**
+	 * internal handling of curl_exec() return
+	 *
+	 * {@see curlExec()}
+	 *
+	 * @param bool|string $curlResult return value from curl_exec();
+	 * @throws ConnectionException
+	 * @return void
+	 */
+	private function curlExecHandleResult($curlResult): void
+	{
+		if (empty($curlResult)) {
+			throw new ConnectionException(curl_error($this->handle), -1);
+		}
+
+		$code = (int)curl_getinfo($this->handle)['http_code'];
+
+		$codeIsInErrorRange = $code >= 400 && $code <= 600;
+		$codeIsNotInNonErrorCodes = !in_array($code, [200, 201, 202, 203, 204, 205, 206, 207, 301], true);
+
+		if ($codeIsInErrorRange || $codeIsNotInNonErrorCodes) {
+			ConnectionException::throwCurlResult($code, $curlResult);
+		}
+	}
 }

plugins/filesbackendSeafile/php/lib/seafapi/autoload.php

Indentation +15 added lines, -15 removed lines

@@ -5,23 +5,23 @@
 namespace Datamate\SeafileApi;
 
 if (!is_callable('spl_autoload_register')) {
-    throw new \RuntimeException('spl_autoload_register: n/a');
+	throw new \RuntimeException('spl_autoload_register: n/a');
 }
 
 \spl_autoload_register(
-    static function ($className) {
-        $namespacePrefix = __NAMESPACE__ . '\\';
-        $basePath = __DIR__ . '/';
-        if (0 !== strpos($className, $namespacePrefix)) {
-            return;
-        }
+	static function ($className) {
+		$namespacePrefix = __NAMESPACE__ . '\\';
+		$basePath = __DIR__ . '/';
+		if (0 !== strpos($className, $namespacePrefix)) {
+			return;
+		}
 
-        $classNamespaceSuffix = substr($className, strlen($namespacePrefix));
-        $classFileName = $basePath . str_replace('\\', '/', $classNamespaceSuffix) . '.php';
-        if (is_file($classFileName)) {
-            require($classFileName);
-        } else {
-            throw new \RuntimeException(sprintf('class: %s: no such file: %s', $className, $classFileName));
-        }
-    }
+		$classNamespaceSuffix = substr($className, strlen($namespacePrefix));
+		$classFileName = $basePath . str_replace('\\', '/', $classNamespaceSuffix) . '.php';
+		if (is_file($classFileName)) {
+			require($classFileName);
+		} else {
+			throw new \RuntimeException(sprintf('class: %s: no such file: %s', $className, $classFileName));
+		}
+	}
 );

plugins/filesbackendSeafile/php/lib/seafapi/Exception/UnexpectedJsonTextResponseException.php

Indentation +37 added lines, -37 removed lines

@@ -4,41 +4,41 @@
 
 final class UnexpectedJsonTextResponseException extends InvalidResponseException
 {
-    /**
-     * @var string the unexpected JSON Text of the API response
-     */
-    private $jsonText;
-
-    /**
-     * utility method to shorten a string (e.g. to create shorter messages)
-     *
-     * @param string $buffer
-     * @param int $size
-     * @return string ASCII, printable with other characters escaped (C-slashes)
-     */
-    public static function shorten(string $buffer, int $size = 32): string
-    {
-        if ($size >= $len = strlen($buffer)) {
-            $buffer = addcslashes($buffer, "\0..\37\42\134\177..\377");
-            return "\"$buffer\"";
-        }
-
-        $buffer = substr($buffer, 0, max(0, $size - 8));
-        $buffer = addcslashes($buffer, "\0..\37\42\134\177..\377");
-
-        return "($len) \"$buffer ...";
-    }
-
-    public static function create(string $message, string $jsonText, \Throwable $previous = null): UnexpectedJsonTextResponseException
-    {
-        $exception = new self($message, 500, $previous);
-        $exception->jsonText = $jsonText;
-
-        return $exception;
-    }
-
-    public function getJsonText(): string
-    {
-        return $this->jsonText;
-    }
+	/**
+	 * @var string the unexpected JSON Text of the API response
+	 */
+	private $jsonText;
+
+	/**
+	 * utility method to shorten a string (e.g. to create shorter messages)
+	 *
+	 * @param string $buffer
+	 * @param int $size
+	 * @return string ASCII, printable with other characters escaped (C-slashes)
+	 */
+	public static function shorten(string $buffer, int $size = 32): string
+	{
+		if ($size >= $len = strlen($buffer)) {
+			$buffer = addcslashes($buffer, "\0..\37\42\134\177..\377");
+			return "\"$buffer\"";
+		}
+
+		$buffer = substr($buffer, 0, max(0, $size - 8));
+		$buffer = addcslashes($buffer, "\0..\37\42\134\177..\377");
+
+		return "($len) \"$buffer ...";
+	}
+
+	public static function create(string $message, string $jsonText, \Throwable $previous = null): UnexpectedJsonTextResponseException
+	{
+		$exception = new self($message, 500, $previous);
+		$exception->jsonText = $jsonText;
+
+		return $exception;
+	}
+
+	public function getJsonText(): string
+	{
+		return $this->jsonText;
+	}
 }

plugins/filesbackendSeafile/php/lib/seafapi/Exception/ConnectionException.php

Indentation +150 added lines, -150 removed lines

@@ -12,154 +12,154 @@
  */
 final class ConnectionException extends Exception
 {
-    /**
-     * HTTP status code of the response
-     */
-    private ?int $responseCode = null;
-
-    /**
-     * HTTP raw response (if any)
-     */
-    private ?string $responseBodyRaw = null;
-
-    private const HTTP_STATUS = [
-        200 => 'OK',
-        201 => 'Created',
-        202 => 'Accepted',
-        301 => 'Moved Permanently',
-        400 => 'Bad Request',
-        401 => 'Unauthorized',
-        403 => 'Forbidden',
-        404 => 'Not Found',
-        409 => 'Conflict',
-        429 => 'Too Many Requests',
-        440 => 'REPO_PASSWD_REQUIRED',
-        441 => 'REPO_PASSWD_MAGIC_REQUIRED',
-        500 => 'Internal Server Error',
-        520 => 'OPERATION_FAILED',
-    ];
-
-    /**
-     * @param int $code HTTP status code, e.g. curl_getinfo($curl)['http_code']
-     * @param bool|string $curlResult return value from curl_exec();
-     * @throws ConnectionException
-     * @return no-return
-     */
-    public static function throwCurlResult(int $code, string|bool $curlResult): never
-    {
-        $exception = new self(self::reasonPhrase($code), $code);
-        $exception->responseCode = $code;
-        $exception->responseBodyRaw = is_string($curlResult) ? $curlResult : null;
-
-        throw $exception;
-    }
-
-    private static function reasonPhrase(int $code): string
-    {
-        return sprintf('%s %s', $code, self::HTTP_STATUS[$code] ?? "UNKNOWN_PHRASE");
-    }
-
-    public function __construct(string $message = "", int $code = 0, ?Throwable $previous = null)
-    {
-        // trigger E_USER_NOTICE if code is not known
-        $isHttpCode = 100 <= $code && $code < 600;
-        $isKnownHttpCode = $isHttpCode && isset(self::HTTP_STATUS[$code]);
-        $isKnownCode = $code === -1 || $isKnownHttpCode;
-        $this->responseCode = $isHttpCode ? $code : null;
-        $isKnownCode || trigger_error(sprintf("%s: Unknown code: %s (%s)", __CLASS__, $code, gettype($code)), E_USER_NOTICE);
-
-        parent::__construct($message, $code, $previous);
-    }
-
-    public function getStatusCode(): ?int
-    {
-        return $this->responseCode;
-    }
-
-    /**
-     * @param int $code
-     * @throws ConnectionException
-     * @return void
-     */
-    public function assertStatusCode(int $code): void
-    {
-        if ($this->responseCode !== $code) {
-            throw $this;
-        }
-    }
-
-    /**
-     * The raw response body
-     *
-     * @return string|null
-     */
-    public function getRawResponse(): ?string
-    {
-        return $this->responseBodyRaw;
-    }
-
-    /**
-     * Response body parsed as JSON Object
-     *
-     * @return null|object - null either if the parsed response is NULL or if it can't be parsed as object
-     */
-    public function tryParsedResponse(): ?object
-    {
-        /**
-         * @noinspection JsonEncodingApiUsageInspection
-         * @noinspection RedundantSuppression
-         */
-        $result = json_decode((string)$this->responseBodyRaw, false);
-        return is_object($result) ? $result : null;
-    }
-
-    public function getReasonPhrase(): ?string
-    {
-        $code = $this->responseCode;
-
-        if (!is_int($code)) {
-            return null;
-        }
-
-        return self::HTTP_STATUS[$code] ?? null;
-
-    }
-
-    /**
-     * A seafile JSON response may contain error information, try to get them.
-     *
-     * It is not fool-proof or overly complete but often more informative than just looking at JSON response dumps.
-     *
-     * @return null|array|string[] messages, null if n/a otherwise array of messages (which can not be empty)
-     */
-    public function tryApiErrorMessages(): ?array
-    {
-        $response = $this->tryParsedResponse();
-        if (null === $response) {
-            return null;
-        }
-
-        $buffer = [];
-
-        // {"error_msg": ... }
-        if (isset($response->error_msg) && is_string($response->error_msg)) {
-             $buffer[] = $response->error_msg;
-        }
-
-        // {"detail": "Invalid token header. No credentials provided."}
-        if (isset($response->detail) && is_string($response->detail)) {
-            $buffer[] = $response->detail;
-        }
-
-        // {"non_field_errors": [ "string...", ...]}
-        if (isset($response->non_field_errors) && is_array($response->non_field_errors)) {
-            foreach ($response->non_field_errors as $message) {
-                if (is_string($message)) {
-                    $buffer[] = $message;
-                }
-            }
-        }
-
-        return empty($buffer) ? null : $buffer;
-    }
+	/**
+	 * HTTP status code of the response
+	 */
+	private ?int $responseCode = null;
+
+	/**
+	 * HTTP raw response (if any)
+	 */
+	private ?string $responseBodyRaw = null;
+
+	private const HTTP_STATUS = [
+		200 => 'OK',
+		201 => 'Created',
+		202 => 'Accepted',
+		301 => 'Moved Permanently',
+		400 => 'Bad Request',
+		401 => 'Unauthorized',
+		403 => 'Forbidden',
+		404 => 'Not Found',
+		409 => 'Conflict',
+		429 => 'Too Many Requests',
+		440 => 'REPO_PASSWD_REQUIRED',
+		441 => 'REPO_PASSWD_MAGIC_REQUIRED',
+		500 => 'Internal Server Error',
+		520 => 'OPERATION_FAILED',
+	];
+
+	/**
+	 * @param int $code HTTP status code, e.g. curl_getinfo($curl)['http_code']
+	 * @param bool|string $curlResult return value from curl_exec();
+	 * @throws ConnectionException
+	 * @return no-return
+	 */
+	public static function throwCurlResult(int $code, string|bool $curlResult): never
+	{
+		$exception = new self(self::reasonPhrase($code), $code);
+		$exception->responseCode = $code;
+		$exception->responseBodyRaw = is_string($curlResult) ? $curlResult : null;
+
+		throw $exception;
+	}
+
+	private static function reasonPhrase(int $code): string
+	{
+		return sprintf('%s %s', $code, self::HTTP_STATUS[$code] ?? "UNKNOWN_PHRASE");
+	}
+
+	public function __construct(string $message = "", int $code = 0, ?Throwable $previous = null)
+	{
+		// trigger E_USER_NOTICE if code is not known
+		$isHttpCode = 100 <= $code && $code < 600;
+		$isKnownHttpCode = $isHttpCode && isset(self::HTTP_STATUS[$code]);
+		$isKnownCode = $code === -1 || $isKnownHttpCode;
+		$this->responseCode = $isHttpCode ? $code : null;
+		$isKnownCode || trigger_error(sprintf("%s: Unknown code: %s (%s)", __CLASS__, $code, gettype($code)), E_USER_NOTICE);
+
+		parent::__construct($message, $code, $previous);
+	}
+
+	public function getStatusCode(): ?int
+	{
+		return $this->responseCode;
+	}
+
+	/**
+	 * @param int $code
+	 * @throws ConnectionException
+	 * @return void
+	 */
+	public function assertStatusCode(int $code): void
+	{
+		if ($this->responseCode !== $code) {
+			throw $this;
+		}
+	}
+
+	/**
+	 * The raw response body
+	 *
+	 * @return string|null
+	 */
+	public function getRawResponse(): ?string
+	{
+		return $this->responseBodyRaw;
+	}
+
+	/**
+	 * Response body parsed as JSON Object
+	 *
+	 * @return null|object - null either if the parsed response is NULL or if it can't be parsed as object
+	 */
+	public function tryParsedResponse(): ?object
+	{
+		/**
+		 * @noinspection JsonEncodingApiUsageInspection
+		 * @noinspection RedundantSuppression
+		 */
+		$result = json_decode((string)$this->responseBodyRaw, false);
+		return is_object($result) ? $result : null;
+	}
+
+	public function getReasonPhrase(): ?string
+	{
+		$code = $this->responseCode;
+
+		if (!is_int($code)) {
+			return null;
+		}
+
+		return self::HTTP_STATUS[$code] ?? null;
+
+	}
+
+	/**
+	 * A seafile JSON response may contain error information, try to get them.
+	 *
+	 * It is not fool-proof or overly complete but often more informative than just looking at JSON response dumps.
+	 *
+	 * @return null|array|string[] messages, null if n/a otherwise array of messages (which can not be empty)
+	 */
+	public function tryApiErrorMessages(): ?array
+	{
+		$response = $this->tryParsedResponse();
+		if (null === $response) {
+			return null;
+		}
+
+		$buffer = [];
+
+		// {"error_msg": ... }
+		if (isset($response->error_msg) && is_string($response->error_msg)) {
+			 $buffer[] = $response->error_msg;
+		}
+
+		// {"detail": "Invalid token header. No credentials provided."}
+		if (isset($response->detail) && is_string($response->detail)) {
+			$buffer[] = $response->detail;
+		}
+
+		// {"non_field_errors": [ "string...", ...]}
+		if (isset($response->non_field_errors) && is_array($response->non_field_errors)) {
+			foreach ($response->non_field_errors as $message) {
+				if (is_string($message)) {
+					$buffer[] = $message;
+				}
+			}
+		}
+
+		return empty($buffer) ? null : $buffer;
+	}
 }