@kud/pcloud

Typed pCloud API client — shared SDK for CLI, MCP, and extensions.

Install

npm install @kud/pcloud

Requires Node.js 20 or later.

Quick start

Username / password

import { PCloudAPI } from "@kud/pcloud"

const api = new PCloudAPI()
await api.authenticate("[email protected]", "password")

const info = await api.userInfo()

OAuth access token

import { PCloudAPI } from "@kud/pcloud"

const api = new PCloudAPI()
api.setAccessToken("your-access-token")

const folder = await api.listFolder("/")

The default API server is https://eapi.pcloud.com (EU endpoint). Pass a second argument to setAccessToken to override it.

API reference

All methods return a typed promise. result: 0 indicates success; a non-zero result with an error string indicates failure.

Authentication

| Method | Description | | ----------------------------------- | ----------------------------------------------- | | authenticate(username, password) | Password auth — stores session token internally | | setAccessToken(token, apiServer?) | OAuth auth — optionally override the API server |

Account

| Method | Description | | ------------ | ------------------------------------- | | userInfo() | Returns account info, quota, and plan |

Files & folders

| Method | Description | | ---------------------------- | ---------------------------------------------- | | listFolder(path?) | List folder contents (default "/") | | stat(path) | File or folder metadata | | createFolder(path) | Create folder if it does not already exist | | deleteFolder(folderid) | Delete folder and all its contents recursively | | copyFile(fileid, topath) | Copy file to a destination path | | moveFile(fileid, topath) | Move file to a destination path | | renameFile(fileid, toname) | Rename file in place | | deleteFile(fileid) | Permanently delete a file | | getFileLink(fileid) | Get a temporary download link | | checksumFile(fileid) | Returns SHA-256, SHA-1, and MD5 checksums |

Revisions

| Method | Description | | ------------------------------------ | ------------------------------------ | | listRevisions(fileid) | List available revisions for a file | | revertRevision(fileid, revisionid) | Revert a file to a previous revision |

Sharing

| Method | Description | | ------------------------------------------ | -------------------------------- | | listShares() | List active shares | | shareFolder(folderid, mail, permissions) | Share a folder with another user | | acceptShare(sharerequestid) | Accept an incoming request | | declineShare(sharerequestid) | Decline an incoming request | | removeShare(shareid) | End an accepted share |

listShares() answers with two objects split by direction — { shares: { outgoing, incoming }, requests: { outgoing, incoming } } — never a flat array.

Note the ids. An accepted share carries a shareid and reports its permissions as four booleans; a pending request carries a sharerequestid and the permissions bitmask. Both are numbers, so nothing in the type system catches sending the wrong one — pCloud answers Please provide 'shareid'. and the operation silently does not happen.

Public links

| Method | Description | | ------------------------------------------------ | --------------------------------- | | getFilePublink(fileid, expire?, maxdownloads?) | Create a public link for a file | | getFolderPublink(folderid, expire?) | Create a public link for a folder | | listPublinks() | List all active public links | | deletePublink(code) | Delete a public link by code |

Zip

| Method | Description | | ---------------------------------------------- | ------------------------------------- | | getZipLink(fileids[], folderids?, filename?) | Get a download link for a zip archive |

Trash

| Method | Description | | -------------------------- | ----------------------------- | | listTrash() | List items in the trash | | restoreFromTrash(fileid) | Restore a file from the trash |

Rewind

pCloud's web app has a Rewind feature, but no public API behind it — listrewindevents returns a 404 under every spelling. listRewindFiles and restoreFromRewind exist on the client and will fail; they are kept only so a caller gets a clear error rather than a missing method.

What the API does expose are the three pieces Rewind is built from: the change log says what happened and when, the trash holds deletions not yet purged, and revisions hold prior versions. Replaying the change log backwards over those two recovery paths reaches the same outcome, and that is what this package ships:

import { planRewind, applyRewind } from "@kud/pcloud"

const plan = await planRewind(api, new Date("2026-07-30T20:30:00Z"))
// → { actions, since, scanned }  — nothing has happened yet

const outcomes = await applyRewind(api, plan)
// → [{ action, ok, detail }, …]

| Function | Description | | ------------------------------------- | ------------------------------------------------------- | | planRewind(api, since, pathPrefix?) | Work out what undoing everything since since requires | | applyRewind(api, plan) | Execute a plan, reporting each action's outcome | | pathResolver(api, entries?) | Turn diff metadata into readable paths |

Planning is separate from applying so a caller can show the cost first. A deletion is undone by restoring from trash and a modification by reverting to the newest revision predating the cutoff; a creation is reported and never acted on, since the only way to undo one is to delete real data — which is indistinguishable from the accident being repaired.

pathResolver seeds itself from the diff stream before falling back to listFolderById, because a deleted folder can no longer be listed — and its children are exactly the files someone is trying to recover.

Authentication helpers

| Export | Description | | ----------------------------- | ------------------------------------------------------------- | | sessionLogin(options) | Email and password login, including two-factor | | OAuthFlow | Browser OAuth flow, for callers with a registered application | | TokenStore | Reads and writes the stored credential | | resolveAuth(options?) | An authenticated client from whatever credential is available | | resolveStoredAuth(options?) | The same, but never starts an interactive flow |

resolveStoredAuth exists because resolveAuth will fall through to an OAuth browser round-trip when the environment carries client credentials — which is the wrong thing to trigger from a precondition check that only wants to know whether a credential is already on hand.

Low-level

| Method | Description | | ---------------------------- | -------------------------------------------------------- | | request<T>(method, params) | Generic request — maps directly to a pCloud API endpoint |

Types

All types are exported from the package root.

| Type | Description | | ------------------------ | ----------------------------------------------------------- | | PCloudFile | File metadata: fileid, name, path, size, modified | | PCloudFolderItem | Item within a folder listing — file or subfolder | | PCloudFolderMetadata | Folder metadata including its contents array | | PCloudFolderResponse | Response wrapper for folder operations | | PCloudUserInfo | Account info: email, quota, usedquota, plan | | PCloudFileLinkResponse | Download link: hosts[] and path | | PCloudChecksumResponse | Checksums: sha256, sha1, md5 | | PCloudRevision | Single revision entry | | PCloudShareItem | Share record with permissions and status | | PCloudPublink | Public link with code, expiry, and download count | | PCloudTrashItem | Trash entry extending PCloudFile with deletetime | | PCloudRewindItem | Rewind entry with fileid, path, and time | | PCloudResponse<T> | Generic response wrapper | | PCloudAuthResponse | Raw authentication response |

Licence

MIT