SDK reference

Install#

npm i @slingdrop/sdk

ESM only, with TypeScript types. Runs in Node 20 or later and modern browsers (it uses fetch, Blob and Web Crypto). Keep API keys on the server; in a browser, use it without a key or with signed upload URLs.

The client#

import { Slingdrop } from "@slingdrop/sdk";

const sd = new Slingdrop({
  apiKey: process.env.SLINGDROP_API_KEY, // sd_…
  // baseUrl: "https://slingdrop.my",    // default; requests go to <baseUrl>/api/v1
  // fetch: myFetch,                     // optional custom fetch (tests, proxies)
});

Without an API key only drops.create works: it sends an anonymous drop (public or passcode, up to 24 hours), like the website does for signed-out visitors. sd.anonymous tells you which mode you're in.

drops#

drops.create#

files is a list of { name, data: Blob, type? }. A / in name keeps folder structure. In Node, await fs.openAsBlob(path) reads big files lazily. Uploads use multipart with 4 parts in flight for files over 10 MB, and retry with backoff.

const { shareUrl } = await sd.drops.create([{ name: "contract.pdf", data }], { vault: true, expiry: "7d" });
// shareUrl = https://slingdrop.my/d/…#k=…   ← only you have this key. Slingdrop can't read the file.

folders#

File a drop with drops.update(id, { folderId }) (null unfiles it). Rename or delete folders with sd.request; see Folders.

reviews#

The loop, the ReviewState shape and a full example are in Reviews & approvals.

hosting#

hosting.templates#

Guides: File hosting and Access rules.

requests#

webhooks#

Standalone helpers#

verifyWebhook(secret, signature, body, toleranceSec?)#

Checks a Slingdrop-Signature header against the raw body, in constant time. Rejects deliveries more than toleranceSec (default 300) seconds old. Returns a boolean.

import { verifyWebhook } from "@slingdrop/sdk";

const body = await req.text(); // the raw body, before JSON.parse
const ok = await verifyWebhook(process.env.SLINGDROP_WEBHOOK_SECRET!, req.headers.get("slingdrop-signature"), body);

signHostedUrl(url, secret, { expiresIn? })#

Signs a hosted file URL locally with a signed-links template's secret, no API call. expiresIn is in seconds (default 3600).

import { signHostedUrl } from "@slingdrop/sdk";

const url = await signHostedUrl("https://cdn.slingdropcontent.my/acme/private/report.pdf", process.env.SLINGDROP_SIGNING_SECRET!, { expiresIn: 600 });
// → …/acme/private/report.pdf?exp=1767225600&sig=…

Errors#

Failed calls throw SlingdropError, with the server's message, the HTTP status and a code such as rate_limited or plan_required.

import { SlingdropError } from "@slingdrop/sdk";

try {
  await sd.drops.create(files, { expiry: "forever" });
} catch (err) {
  if (err instanceof SlingdropError && err.code === "storage_full") {
    // tell the user to free up space
  } else throw err;
}

Exported types#

SlingFile, CreateOptions, Drop, Folder, ReviewState, ReviewComment, HostedObject, HostingSpace, HostingUsage, UploadUrl, SignedUrl, SpaceAccess, AccessMode, AccessTemplate, AccessTemplateInput, JwtConfig, JwtProvider, JwtRule and TemplateTestResult.