@dropthis/node

@dropthis/node

Official Node.js SDK for dropthis -- the publish layer between AI and the internet. One API call in, one URL out.

Install

npm install @dropthis/node

Quick start

import { Dropthis } from "@dropthis/node";

const dropthis = new Dropthis({ apiKey: "sk_..." });
const { data, error } = await dropthis.publish("<h1>Hello</h1>");

console.log(data.url); // https://abc123.dropthis.app

Usage

Publish an HTML string

const { data } = await dropthis.publish("<h1>Launch page</h1>");

Publish a file

const { data } = await dropthis.publish("./report.html");

Publish a directory

const { data } = await dropthis.publish("./dist");

Publish with options

const { data } = await dropthis.publish("./dist", {
  title: "Q4 Report",
  visibility: "unlisted",
  password: "s3cret",
  expiresAt: "2026-12-31T00:00:00Z",
});

Deploy new content to an existing drop

const created = await dropthis.publish("./dist", { title: "v1" });

const updated = await dropthis.deploy(created.data.id, "./dist-v2", {
  ifRevision: created.data.revision,
});

Update metadata only

await dropthis.update("drop_abc123", { title: "New title" });

Supported inputs

The publish() and deploy() methods accept:

• HTML/text string -- "<h1>Hello</h1>" (auto-detected as inline content)
• File path -- "./report.html" (local file)
• Directory -- "./dist" (local directory, bundled)
• Array of paths -- ["./dist", "./extra.css"] (multi-path bundle)
• URL object -- new URL("https://example.com/page") (source fetch)
• Bytes -- new Uint8Array(...) (raw bytes)
• Explicit content -- { kind: "content", content: "...", contentType?: "text/html", path?: "page.html" }
• Source URL -- { kind: "source_url", sourceUrl: "https://example.com/page" }
• File bundle -- { kind: "files", files: [{ path, content?, contentBase64?, bytes?, contentType? }], entry? }

Drop settings (title, visibility, password, noindex, expiresAt, slug, metadata) go in the second options argument, not in the input object.

All inputs are uploaded through staged presigned URLs. The SDK handles this transparently.

Explicit input examples

// Inline content with explicit MIME type
await dropthis.publish({
  kind: "content",
  content: "<h1>Hello</h1>",
  contentType: "text/html",
});

// Fetch and re-publish a remote URL
await dropthis.publish({
  kind: "source_url",
  sourceUrl: "https://example.com/report",
});

// Multi-file bundle with explicit entry point
await dropthis.publish(
  {
    kind: "files",
    files: [
      { path: "index.html", content: "<h1>Hello</h1>" },
      { path: "style.css", content: "body { margin: 0; }" },
    ],
    entry: "index.html",
  },
  { title: "My Site" },
);

Prepare (validate without sending)

prepare() resolves and validates the input locally, returning the prepared request object without making any API calls. It throws PublishInputError on invalid input (e.g. missing file).

import { Dropthis, PublishInputError } from "@dropthis/node";

try {
  const prepared = await dropthis.prepare("./dist");
  console.log("Ready to publish:", prepared.kind);
} catch (e) {
  if (e instanceof PublishInputError) {
    console.error("Bad input:", e.message);
  }
}

Error handling

All methods return DropthisResult<T> -- either { data: T, error: null, headers } or { data: null, error, headers }. API errors never throw; check error before using data.

const result = await dropthis.drops.get("drop_abc123");

if (result.error) {
  console.error(result.error.code, result.error.message);
  // Also available: error.statusCode, error.requestId, error.suggestion,
  //                 error.retryable, error.param, error.currentRevision
} else {
  console.log(result.data);
}

Local input validation errors (e.g. file_not_found) are also returned as { error: { code: "file_not_found", ... } } rather than thrown -- except for prepare(), which throws PublishInputError.

Configuration

const dropthis = new Dropthis({
  apiKey: "sk_...",        // Required. Defaults to DROPTHIS_API_KEY env var.
  baseUrl: "https://...",  // Override API base URL.
  timeoutMs: 30_000,       // Request timeout in milliseconds (default: 30s).
  uploadTimeoutMs: 120_000, // Timeout for signed-PUT file uploads (default: 120s).
  fetch: customFetch,      // Custom fetch implementation.
});

You can also pass just the API key as a string:

const dropthis = new Dropthis("sk_...");

Resources

drops

await dropthis.drops.list({ limit: 20 });
await dropthis.drops.get("drop_abc123");
await dropthis.drops.update("drop_abc123", { title: "Updated" });
await dropthis.drops.delete("drop_abc123");

List results support auto-pagination:

const page = await dropthis.drops.list();
const allDrops = await page.data.autoPagingToArray({ limit: 100 });

// Or iterate
for await (const drop of page.data) {
  console.log(drop.url);
}

To change a drop's content, use client.deploy(dropId, newInput). drops.update() is for settings only (title, visibility, password, noindex, expiresAt, slug, metadata).

deployments

await dropthis.deployments.list("drop_abc123");
await dropthis.deployments.get("drop_abc123", "dep_xyz789");

uploads

Low-level upload session management. Most users should use publish() instead.

await dropthis.uploads.create({
  schemaVersion: 1,
  files: [{ path: "index.html", contentType: "text/html", sizeBytes: 1024 }],
});
await dropthis.uploads.get("upl_abc123");
await dropthis.uploads.complete("upl_abc123", { files: {} });
await dropthis.uploads.cancel("upl_abc123");

auth

await dropthis.auth.requestEmailOtp({ email: "[e-mail]" });
await dropthis.auth.verifyEmailOtp({ email: "[e-mail]", code: "123456" });
await dropthis.auth.logout();

apiKeys

await dropthis.apiKeys.create({ label: "CI" });
await dropthis.apiKeys.list();
await dropthis.apiKeys.delete("key_abc123");

account

await dropthis.account.get();
await dropthis.account.update({ displayName: "Jane Doe" });
await dropthis.account.delete();

Cloudflare Workers (edge)

Use the fs-free entry point for Cloudflare Workers and other edge runtimes. It does not import node:fs, node:path, or node:crypto.

import { DropthisEdge } from "@dropthis/node/edge";

const dropthis = new DropthisEdge({ apiKey: env.DROPTHIS_API_KEY });
const { data, error } = await dropthis.publish("<h1>Hello from the edge</h1>");

DropthisEdge accepts the in-memory subset of PublishInput: inline strings, Uint8Array, URL, and the explicit { kind: "content" }, { kind: "source_url" }, and { kind: "files" } forms. Local file paths and string[] path arrays are not supported (no filesystem on the edge).

DropthisEdge exposes the same publish(input, options?) and deploy(dropId, input, options?) methods, plus the drops, deployments, account, and apiKeys resource accessors.

Types

Key types exported from the package:

import type {
  DropthisClientOptions,
  DropthisResult,
  DropthisErrorResponse,
  DropResponse,
  DropDeploymentResponse,
  DropOptions,
  PrepareOptions,
  RequestControls,
  PublishOptions,
  PublishInput,
  PublishFileInput,
  ListPage,
  CreateUploadSessionRequest,
  CreateUploadSessionResponse,
} from "@dropthis/node";

Agent skills

For AI coding agents (Cursor, Claude Code, Windsurf, etc.), install the dropthis-skills package:

npx skills add dropthis-dev/dropthis-skills

Links

• Website
• GitHub
• npm