fluidcloud — TypeScript/JS SDK for FluidCloud

Official TypeScript/JavaScript client for FluidCloud — file storage with shareable raw links and stable public (hotlinkable) URLs. The SDK hides the upload plumbing (presign → direct-to-storage PUT → complete, including multipart) behind a single upload() call. Zero runtime dependencies — uses the platform fetch (Node 18+ or the browser).

📚 Full documentation: https://cloud.fluidvip.com/docs

Install

npm install fluidcloud

Quick start

import { FluidCloud } from "fluidcloud";

const fc = new FluidCloud({ apiKey: "fck_live_..." }); // baseUrl defaults to prod

const space = await fc.spaces.create("Brand Assets");

// Browser: a File/Blob from an <input>. Node: a Uint8Array/Buffer.
const asset = await fc.files.upload(file, space.id, { public: true });
console.log(asset.public_url); // stable, inline, cacheable hotlink (use as <img src>)

Authentication

Create an API key in the dashboard (Settings → Developer; an active subscription is required) and pass it to the client. The key (fck_live_… / fck_test_…) is sent as X-API-Key. Keys are scoped; a call outside a key's scopes throws PermissionError (HTTP 403 insufficient_scope).

API

fc.spaces.list() / create(name)
fc.folders.list(spaceId, parentId?) / create(name, spaceId, parentId?)
          / rename(id, name) / move(id, parentId) / delete(id) / restore(id)
fc.files.upload(blobOrBytes, spaceId, { folderId?, name?, contentType?, public? })
         .list(spaceId, folderId?) / get(id)
         .rename(id, name) / move(id, folderId) / delete(id) / restore(id)
         .downloadUrl(id)                       // short-lived download URL
         .publicUrl(id)                         // permanent public hotlink (Link)
         .signedUrl(id, { expiresInDays?, permission? })   // expiring (Link)
fc.shares.list({ fileId?, includeInactive? }) / revoke(shareId)
fc.quota.usage()

upload() accepts a Blob/File (browser), or a Uint8Array/ArrayBuffer (Node or browser). It auto-selects single vs multipart (≥100 MB), computes the sha256 for single uploads, and — with { public: true } — sets asset.public_url.

publicUrl() vs signedUrl(): a public link never expires and is served inline

• edge-cached; a signed link expires (1–365 days). Use fc.shares.revoke(link.id) to revoke either.

Errors

All extend FluidCloudError: AuthError (401), QuotaExceededError (402), PermissionError (403), NotFoundError (404), ConflictError (409), ApiError.

Notes

• ESM-only, targets the versioned API (/api/v1).
• Inject a custom fetch via new FluidCloud({ apiKey, fetch }) for tests or runtimes without a global fetch.
• Override the API origin with baseUrl if you have been given a different endpoint.

MIT licensed.