pcloud-kit

Unofficial, zero-dependency, type-safe pCloud SDK for modern JavaScript runtimes.

A modern alternative to pcloud-sdk-js with full TypeScript support, and no runtime dependencies.

Why

| | pcloud-sdk-js | pcloud-kit | | -------------- | -------------------------------------------- | --------------------------------------------- | | Runtime deps | isomorphic-fetch, form-data, invariant | none | | TypeScript | untyped JS | strict, exactOptionalPropertyTypes | | Module format | CJS | ESM only, sideEffects: false | | Progress | XHR events | stream-based byte counts | | Errors | raw rejected JSON | typed PcloudApiError / PcloudNetworkError | | API style | callback or promise | promise only | | Environments | Node + browser | Node + browser (platform-neutral build) | | EU/US failover | manual | automatic on 5xx |

Requirements

• Node >=22.18.0 — relies on global fetch, Writable.toWeb, openAsBlob, Array.prototype.toSorted
• Browser — any modern browser with fetch, FormData, and ReadableStream

Install

npm install pcloud-kit
# pnpm add pcloud-kit / yarn add pcloud-kit / bun add pcloud-kit

Quick start

import { createClient } from 'pcloud-kit'

const client = createClient({ token: process.env.PCLOUD_TOKEN! })

const root = await client.listfolder(0)
for (const entry of root.contents ?? []) {
	// TypeScript narrows entry to FolderMetadata | FileMetadata via isfolder
	console.log(entry.isfolder ? '[dir]' : '[file]', entry.name)
}

Authentication

OAuth — server-side code flow (Node)

import { buildAuthorizeUrl, getTokenFromCode } from 'pcloud-kit/oauth'

// Step 1: redirect the user to pCloud's consent screen
const url = buildAuthorizeUrl({
	clientId: process.env.PCLOUD_CLIENT_ID!,
	redirectUri: 'https://example.com/callback',
	responseType: 'code',
})

// Step 2: in your callback handler, exchange the code for an access token
const { access_token, locationid } = await getTokenFromCode(
	code,
	process.env.PCLOUD_CLIENT_ID!,
	process.env.PCLOUD_APP_SECRET!,
)

const client = createClient({ token: access_token })

OAuth — browser popup flow

import { initOauthToken, popup } from 'pcloud-kit/oauth-browser'

// On the main page: opens a popup and wires the callback
initOauthToken({
	clientId: 'YOUR_CLIENT_ID',
	redirectUri: 'https://example.com/oauth-callback',
	receiveToken: (token, locationid) => {
		const client = createClient({ token })
	},
})

// On the redirectUri page: reads the token from the URL and passes it back
popup()

For environments where a redirect URI is impractical, initOauthPollToken uses the poll_token response type and simultaneously polls both EU and US servers:

import { initOauthPollToken } from 'pcloud-kit/oauth-browser'

initOauthPollToken({
	clientId: 'YOUR_CLIENT_ID',
	receiveToken: (token, locationid) => {
		/* … */
	},
	onError: (err) => {
		/* … */
	},
})

Username/password session token

If you have a session token from userinfo (the auth field), use type: 'pcloud' — this switches the auth header from access_token= to auth=:

const client = createClient({ token: sessionToken, type: 'pcloud' })

type defaults to 'oauth'.

Convenience methods

These are fully typed and bound directly on the client:

| Method | Signature | Returns | | ------------------ | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | | userinfo | () | Promise<UserInfo> | | listfolder | (folderid?: number, options?: ListFolderOptions) | Promise<FolderMetadata> | | createfolder | (name: string, parentfolderid?: number) | Promise<FolderMetadata> | | deletefile | (fileid: number) | Promise<FileMetadata> | | deletefolder | (folderid: number, recursive?: boolean) | Promise<FolderMetadata> | | movefile | (fileid: number, tofolderid: number) | Promise<FileMetadata> | | movefolder | (folderid: number, tofolderid: number) | Promise<FolderMetadata> | | renamefile | (fileid: number, toname: string) | Promise<FileMetadata> | | renamefolder | (folderid: number, toname: string) | Promise<FolderMetadata> | | getfilelink | (fileid: number) | Promise<string> | | getthumblink | (fileid: number, options?: ThumbOptions) | Promise<string> | | sharefolder | (folderid: number, mail: string, permissions: 'view' \| 'edit', message?: string) | Promise<ShareInfo> | | appshare | (folderid: number, userid: number, clientid: string) | Promise<AppShareInfo> | | login | (params?: Record<string, string>) | Promise<UserInfo> | | register | (email: string, password: string, options?: RegisterOptions) | Promise<number> | | upload | (source: string \| Blob \| File, folderid?: number, options?: UploadOptions) | Promise<{ metadata: FileMetadata; checksums: Checksums }> | | download | (url: string, options?: DownloadOptions) | Promise<ReadableStream<Uint8Array>> | | downloadfile | (fileid: number, destination: string \| WritableStream<Uint8Array>, options?: DownloadOptions) | Promise<FileLocal> | | remoteupload | (url: string, folderid?: number, options?: RemoteUploadOptions) | Promise<{ metadata: FileMetadata }> | | getthumbsfileids | (fileids: number[], receiveThumb: (thumb: ThumbResult) => void, options?: ThumbOptions) | Promise<ThumbResult[]> | | getthumbslinks | (fileids: number[], options?: ThumbOptions) | Promise<ThumbResult[]> |

Uploads

// From a Blob or File (browser or Node)
const { metadata, checksums } = await client.upload(new Blob(['hello']), folderId, {
	onBegin: () => console.log('starting'),
	onProgress: ({ loaded, total }) => console.log(loaded, '/', total),
	onFinish: () => console.log('done'),
})

// From a filesystem path (Node only)
await client.upload('/path/to/video.mp4', folderId)

// Remote URL — pCloud fetches it server-side, progress is polled automatically
await client.remoteupload('https://example.com/archive.zip', folderId, {
	onProgress: ({ all }) => console.log(all.downloaded, '/', all.size),
})

Chunked/resumable upload primitives (upload_create, upload_write, upload_save) are available via client.call() — there is no high-level wrapper yet.

Downloads and streaming

// Download a file to disk (Node)
const { path, bytes } = await client.downloadfile(fileId, '/tmp/out.bin')

// Download to any WritableStream (browser or Node)
await client.downloadfile(fileId, writableStream, {
	onProgress: ({ loaded, total }) => {
		/* … */
	},
})

// Get a raw ReadableStream to pipe or consume yourself
const url = await client.getfilelink(fileId)
const stream = await client.download(url)

Error handling

import { PcloudApiError, PcloudNetworkError } from 'pcloud-kit'

try {
	await client.listfolder(0)
} catch (err) {
	if (err instanceof PcloudApiError) {
		// pCloud returned a non-zero result code.
		// `err.params` echoes the method's input params with
		// known secret/sensitive keys stripped, so it's safe to log.
		console.error(err.result, err.method, err.params)
	} else if (err instanceof PcloudNetworkError) {
		// fetch itself failed (timeout, DNS, etc.). The underlying fetch URL
		// may include the auth token as a query param, so `err.message` and
		// `err.cause.message` are scrubbed: values of known secret keys are
		// replaced with `***`. `err.cause` is a plain `{ name, message }`
		// object (not the raw fetch error) to prevent incidental leaks.
		console.error(err.status, err.cause)
	}
}

The error classes can also be imported from pcloud-kit/errors to avoid pulling in the full client.

Logging and proxies

pCloud's HTTP/JSON API requires authentication parameters to travel as query-string values: ?access_token=, ?auth=, and — for register / login — ?password=. The SDK keeps those values out of its own thrown errors (see Error handling), but anything sitting between your app and *.pcloud.com will see the full URL.

If you operate or pass through any of the following, disable query-string capture (or scrub these keys) so tokens and passwords don't end up in stored logs:

• reverse proxies / load balancers (nginx $request, Envoy access logs, ALB/CloudFront request logs)
• APM and tracing (OpenTelemetry HTTP spans, Datadog/New Relic/Sentry breadcrumbs that record outbound URLs)
• CI logs that print fetch URLs on failure

The server-side OAuth code exchange (getTokenFromCode) is exempt: client_id, code, and client_secret travel in the POST body (per RFC 6749 §3.2), so they don't appear in URLs.

Low-level client.call() — 160+ endpoints

The convenience methods cover the most common operations. For everything else, call() is constrained to the PcloudMethodName literal union:

// Typed against ~160 known pCloud method names
const stat = await client.call<{ metadata: FileMetadata }>('stat', { fileid: 12345 })

// Escape hatch for unlisted or future methods
const res = await client.callRaw('some_new_method', { param: 'value' })

call() also accepts an AbortSignal:

const controller = new AbortController()
await client.call('stat', { fileid: 12345 }, { signal: controller.signal })

See the pCloud HTTP API docs for the full method list and parameters.

Advanced client options

const client = createClient({
	token,
	type: 'oauth', // 'oauth' (default) | 'pcloud'
	apiServer: 'eapi.pcloud.com', // default EU server; 'api.pcloud.com' for US
	useProxy: true, // auto-detect nearest server via getapiserver on init
	coalesceReads: false, // disable in-flight deduplication of identical GET reads
})

// Swap the token on an existing client (e.g. after token refresh, or
// when reusing a long-lived client across multi-tenant requests).
// Resets the in-flight read coalesce cache so reads under the old
// token can't be served to a caller that now holds a different token.
client.setToken(newToken)

// Re-detect the nearest server
const server = await client.setupProxy()

The client automatically falls back from the EU to the US server (api.pcloud.com) on a 5xx or connection failure — no configuration needed.

Migrating from pcloud-sdk-js

Client creation

// Before
import pCloudSdk from 'pcloud-sdk-js'
const client = pCloudSdk.createClient(token)

// After
import { createClient } from 'pcloud-kit'
const client = createClient({ token })

Listing a folder

The method name and promise shape are identical. You now get discriminated union types for free:

const folder = await client.listfolder(0, { recursive: true })

for (const entry of folder.contents ?? []) {
	if (entry.isfolder) {
		entry.folderid // FolderMetadata — TypeScript knows this
	} else {
		entry.fileid // FileMetadata — TypeScript knows this
	}
}

Upload progress

// Before — XHR ProgressEvent
client.upload(file, folderId, { onProgress: (event) => event.loaded / event.total })

// After — stream-based byte counts
client.upload(file, folderId, {
	onProgress: ({ loaded, total }) => loaded / (total ?? Infinity),
})

Error handling

// Before — raw rejected JSON
.catch((err) => {
  if (err.result === 2000) { /* invalid token */ }
})

// After — typed error classes
.catch((err) => {
  if (err instanceof PcloudApiError && err.result === 2000) { /* invalid token */ }
})

Gaps

• Chunked/resumable uploads — no high-level wrapper; use client.call('upload_create', …) etc. directly.
• Upload progress on file paths (Node) — progress reflects bytes passing through the stream tee, not HTTP body-upload confirmation events.

Development

pnpm install
pnpm exec playwright install chromium   # one-time, for browser tests
pnpm test       # vitest — runs all three projects (see below)
pnpm build      # tsdown (ESM + .d.ts)

The project uses tsdown for bundling, vitest for testing, oxlint for linting, and oxfmt for formatting.

Test layout

pnpm test runs three Vitest projects:

| Project | Location | Environment | Mocking | | ------------------ | ---------------------------------------- | --------------------- | ------------------ | | unit | test/unit/**/*.test.ts | Node | fetch stub | | scenario-node | examples/node/**/*.scenario.test.ts | Node | MSW (msw/node) | | scenario-browser | examples/browser/**/*.scenario.test.ts | Chromium (Playwright) | MSW service worker |

Filter to one project with the matching script:

pnpm test:unit
pnpm test:scenario-node
pnpm test:browser

The unit tests stub fetch directly to assert URL shapes and error handling; the scenario tests drive the SDK end-to-end against MSW handlers shared between Node and the browser.

Examples

examples/ holds runnable scenarios that double as integration tests. They share fixtures and MSW handlers so the same flows are exercised from both Node and the browser.

examples/
  shared/      fixtures, MSW handler factory, scenario runner
  node/        Vitest tests + a tsx-runnable manual script
  browser/     Vitest browser-mode tests + a Vite + React demo page

Manual scenario — Node

Run the same flows the scenario-node tests cover from the command line:

pnpm scenario:node          # MSW-mocked, no network
pnpm scenario:node:real     # hits the real pCloud API (see env vars below)

For --real mode, set:

| Var | Required | Purpose | | ------------------- | -------- | -------------------------------------------------------- | | PCLOUD_TOKEN | yes | OAuth access token (sent as ?access_token=) | | PCLOUD_AUTH_TOKEN | optional | Session token (sent as ?auth=); skipped if unset | | PCLOUD_CLIENT_ID | optional | OAuth app client id; required for the code-exchange step | | PCLOUD_APP_SECRET | optional | OAuth app secret; required for the code-exchange step | | PCLOUD_CODE | optional | Authorization code; required for the code-exchange step |

Steps that lack their required env vars are skipped — you don't have to provide an app secret just to validate listfolder.

Manual scenario — browser

pnpm scenario:browser         # MSW-mocked, no network
pnpm scenario:browser:real    # hits the real pCloud API

Both commands open http://localhost:5173. A small React + Vite page with one button per flow (oauth listfolder, pcloud-mode listfolder, OAuth poll-token, error path).

In MSW mode the inputs are pre-filled with fixture tokens and every flow works against the mocked handlers.

In :real mode the worker is not started and requests go to the live API. Paste a real token into the input(s) — ?access_token= for the oauth-mode button, ?auth= for the pcloud-mode button. The OAuth poll-token and error-path buttons are disabled because they depend on MSW (the OAuth poll button uses a fake client_id and intercepts window.open; the error button overrides the worker handlers).

License

MIT