Pandafile Pro · Node.js and TypeScript

Send large files from Node.js and TypeScript

Upload a file of any size from a Node.js script, a backend service or a CI pipeline and get a download link back. The official @pandafile/sdk package and its pandafile command line create the transfer, upload every file with resumable uploads, complete it and return the link – with progress, retries and TypeScript types built in.

A single fetch with a multi-gigabyte body is fragile: one dropped connection and you start again from zero. The SDK uploads in chunks with the open tus protocol, uploads several files in parallel, retries what fails and continues at the byte the server already has. It has no runtime dependencies and runs on Node.js 18+, Deno, Bun, browsers and edge runtimes – anything with fetch.

Install

ESM and CommonJS, typed from the OpenAPI document. MIT licence.

npm install @pandafile/sdk

Command line

Progress bar, resume, --json for scripts.

pandafile send file.mov

Safe to try

Test keys make real uploads that email nobody and expire after 24 hours.

pf_test_…

Install and set your API key

The API is included with Pandafile Pro and Team (see pricing). Create a key in Dashboard → Domain & API and keep it in the environment, never in code that is shipped to browsers.

npm install @pandafile/sdk
export PANDAFILE_API_KEY=pf_live_YOUR_KEY   # or pf_test_… while you build

Upload and send a large file

One call does it all. Pass paths to files or folders (folders keep their structure), add recipients to email each of them a personal link, and read the link from the result.

import Pandafile from '@pandafile/sdk';

const pf = new Pandafile(); // reads PANDAFILE_API_KEY

const { url, id, bytes } = await pf.transfers.send({
  files: ['final-cut.mov', 'stills/'],
  recipients: ['client@example.com'],
  title: 'Final cut',
  message: 'Here is the final version – let me know what you think.',
  onProgress: (p) => console.log(`${p.percent.toFixed(1)} %  ${p.filesDone}/${p.filesTotal} files`),
});
console.log(url); // https://pandafile.co/d/k3x9q2m7ab

Prefer CommonJS? const { Pandafile } = require('@pandafile/sdk'); works the same. Every request and response type is exported (Transfer, TransferDetail, CreateTransferBody, Event …), so your editor completes field names and TypeScript catches typos. Options include password, concurrency (files at once, default 3), chunkSize (default 16 MiB) and an AbortSignal to cancel.

Resume after a crash or restart

Dropped connections are retried within a run. To continue after the process dies, save the send state whenever it changes and pass it back: finished files are skipped and the unfinished one resumes.

import { readFileSync, writeFileSync, rmSync } from 'node:fs';
import Pandafile from '@pandafile/sdk';

const pf = new Pandafile();
let state = null;
try { state = JSON.parse(readFileSync('send-state.json', 'utf8')); } catch {}

const ac = new AbortController();
process.once('SIGINT', () => ac.abort()); // Ctrl-C pauses; run again to resume

const res = await pf.transfers.send({
  files: ['huge.mxf'],
  state,
  onState: (s) => writeFileSync('send-state.json', JSON.stringify(s)),
  signal: ac.signal,
});
rmSync('send-state.json', { force: true });
console.log(res.url, res.resumed ? '(resumed)' : '');

The state contains the transfer's upload secret, so keep the file private.

From the command line and CI

The same package installs the pandafile command. It shows a progress bar, resumes when you run the same command again, and with --json prints machine-readable output for scripts. In CI, set PANDAFILE_API_KEY as a secret and run it with npx.

npm install -g @pandafile/sdk
pandafile login                          # paste your key once (stored owner-only)
pandafile send build/ --to qa@example.com --title "Nightly build" --expires 60d

# in a CI job: print only the link
npx @pandafile/sdk send dist/app.zip --json | jq -r .url

Other commands: pandafile ls, pandafile info <id>, pandafile rm <id>, pandafile request create and pandafile webhook listen. The full list is in the CLI reference.

Send a file that is already online

When the file already sits on another server, let Pandafile download it rather than streaming it through your service. Small files come back ready; bigger ones keep importing in the background.

const t = await pf.transfers.fromUrl({
  files: [{ url: 'https://example.com/exports/invoices-march.pdf' }],
  title: 'Invoices March',
  recipients: ['accounts@example.com'],
});
console.log(t.status, t.url); // ready, or uploading
if (t.status === 'uploading') console.log((await pf.transfers.importStatus(t.id)).status);

Check downloads and remind

const detail = await pf.transfers.retrieve(id);
for (const r of detail.recipients) console.log(r.email, r.downloaded ? 'downloaded' : 'not yet');

await pf.transfers.addRecipients(id, ['editor@example.com']);
await pf.transfers.update(id, { extend: true }); // 30 more days (Pro)
for await (const t of pf.transfers.list({ view: 'active' })) console.log(t.id, t.title, t.download_count);

Errors and retries

429, 5xx and network errors are retried with exponential backoff, waiting for Retry-After. Every POST, PATCH and PUT carries an idempotency key, so a retry never creates a second transfer. Anything left is thrown as a typed error.

import { NotFoundError, RateLimitError, PandafileError } from '@pandafile/sdk';

try {
  await pf.transfers.retrieve('nope1234');
} catch (e) {
  if (e instanceof NotFoundError) console.log('gone:', e.code);      // resource_missing
  else if (e instanceof RateLimitError) console.log('retry after', e.retryAfter);
  else if (e instanceof PandafileError) console.error(e.type, e.code, e.status, e.requestId);
  else throw e;
}

React when files are downloaded

Subscribe to events such as transfer.ready and transfer.downloaded and verify each delivery against the raw body:

import express from 'express';
import Pandafile from '@pandafile/sdk';

const app = express();
app.post('/pandafile-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const ok = await Pandafile.webhooks.verify(req.body, req.get('Pandafile-Signature'),
    process.env.PANDAFILE_WEBHOOK_SECRET, 300);
  if (!ok) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

During development, pandafile webhook listen --forward http://localhost:3000/pandafile-webhook --test forwards your events, signed, to a local URL without a tunnel.

Limits

Uploads from Node.js follow the same plan limits as the website: up to 1000 GB per transfer and 1500 GB of storage on Pro, files kept 30 days and extendable up to 90. Test transfers count toward no limit. See the API reference for every endpoint, the SDKs and CLI page for Python versions of these examples, and the MCP server if you want an AI assistant to send files for you. Writing Python? Read sending large files from Python.

Frequently asked questions

How do I upload a large file from Node.js?

Install @pandafile/sdk, set PANDAFILE_API_KEY and call new Pandafile().transfers.send({ files: ["file.mov"] }). The SDK creates the transfer, uploads every file with resumable tus uploads and returns the link.

Does it work with TypeScript and CommonJS?

Yes. The package ships ESM and CommonJS builds with full TypeScript types generated from the OpenAPI document, and has no runtime dependencies.

Can I use it in the browser?

Yes, with File objects from a file input, but never put a live API key in code that strangers can read. Create transfers from your server, or use a file request so people can upload to you without a key.

Is there a command line tool?

Yes. npm install -g @pandafile/sdk installs the pandafile command: pandafile send file.mov --to client@example.com prints the link, shows a progress bar, resumes when you run it again and supports --json for scripts and CI.

Which Node.js versions are supported?

Node.js 18 and newer, plus Deno, Bun, browsers and edge runtimes – anything with fetch.