@dropthis/cli 0.3.4 → 0.4.0

package/node_modules/@dropthis/node/README.md

@@ -1,90 +1,218 @@
-# Dropthis Node SDK
+# @dropthis/node
 
-Official Node.js SDK for Dropthis.
+Official Node.js SDK for [dropthis](https://dropthis.app) -- the publish layer between AI and the internet. One API call in, one URL out.
+
+## Install
 
 ```bash
-npm install @dropthis/sdk
+npm install @dropthis/node
 ```
 
-## Publish Anything
+## Quick start
 
-```ts
-import { Dropthis } from "@dropthis/sdk";
+```typescript
+import { Dropthis } from "@dropthis/node";
 
-const dropthis = new Dropthis({ apiKey: process.env.DROPTHIS_API_KEY });
+const dropthis = new Dropthis({ apiKey: "sk_..." });
+const { data, error } = await dropthis.publish("<h1>Hello</h1>");
 
-const { data, error } = await dropthis.publish("./dist", {
-	title: "Generated launch page",
-	visibility: "unlisted",
-});
+console.log(data.url); // https://abc123.dropthis.app
+```
 
-if (error) {
-	console.error(error.message);
-	process.exit(1);
-}
+## Usage
 
-console.log(data.url);
+### Publish an HTML string
+
+```typescript
+const { data } = await dropthis.publish("<h1>Launch page</h1>");
 ```
 
-## Update A Drop
+### Publish a file
+
+```typescript
+const { data } = await dropthis.publish("./report.html");
+```
 
-```ts
-const created = await dropthis.publish("./dist", { title: "Launch" });
-if (created.error) throw new Error(created.error.message);
+### Publish a directory
 
-const updated = await dropthis.update(created.data.id, "./dist", {
-	ifRevision: created.data.revision,
+```typescript
+const { data } = await dropthis.publish("./dist");
+```
+
+### Publish with options
+
+```typescript
+const { data } = await dropthis.publish("./dist", {
+  title: "Q4 Report",
+  visibility: "unlisted",
+  password: "s3cret",
+  expiresAt: "2026-12-31T00:00:00Z",
 });
-if (updated.error) throw new Error(updated.error.message);
+```
+
+### Deploy new content to an existing drop
+
+```typescript
+const created = await dropthis.publish("./dist", { title: "v1" });
 
-const deployments = await dropthis.deployments.list(created.data.id);
+const updated = await dropthis.deploy(created.data.id, "./dist-v2", {
+  ifRevision: created.data.revision,
+});
+```
+
+### Update metadata only
+
+```typescript
+await dropthis.update("drop_abc123", { title: "New title" });
 ```
 
-Supported inputs:
+## Supported inputs
+
+The `publish()` method accepts:
 
-- HTML strings
-- Plain text strings
-- HTTP(S) URLs
-- Local files and folders, uploaded through staged signed URLs
-- Explicit `content`, `files`, `sourceUrl`, and `sourceUrls` objects
+- **HTML string** -- `"<h1>Hello</h1>"`
+- **File path** -- `"./report.html"`
+- **Directory** -- `"./dist"`
+- **Bytes** -- `new Uint8Array(...)`
+- **Explicit object** -- `{ content: "...", contentType: "text/html" }` or `{ files: [...] }`
 
-Large strings, binary inputs, local files, local folders, and explicit `files` are staged through `/uploads`, signed object-store `PUT` requests, upload completion, then a final `upload_id` publish request.
+All inputs are uploaded through staged presigned URLs. The SDK handles this transparently.
 
-## Error Handling
+## Error handling
 
-SDK methods return `{ data, error, headers }`.
+All methods return `{ data, error, headers }`. Check `error` before using `data`.
 
-```ts
-const result = await dropthis.drops.get("drop_123");
+```typescript
+const result = await dropthis.drops.get("drop_abc123");
 
 if (result.error) {
-	console.error(result.error.code, result.error.message);
+  console.error(result.error.code, result.error.message);
+  // error.statusCode, error.requestId also available
+} else {
+  console.log(result.data);
 }
 ```
 
+## Configuration
+
+```typescript
+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.
+  fetch: customFetch,     // Custom fetch implementation.
+});
+```
+
+You can also pass just the API key as a string:
+
+```typescript
+const dropthis = new Dropthis("sk_...");
+```
+
 ## Resources
 
-```ts
-dropthis.auth.requestEmailOtp({ email: "agent@example.com" });
-dropthis.auth.verifyEmailOtp({ email: "agent@example.com", code: "123456" });
+### drops
 
-dropthis.apiKeys.create({ label: "CI" });
+```typescript
+await dropthis.drops.list({ limit: 20 });
+await dropthis.drops.get("drop_abc123");
+await dropthis.drops.create({ uploadId: "upl_abc123", options: { title: "New" } });
+await dropthis.drops.createRaw({ upload_id: "upl_abc123" }); // no snake_case conversion
+await dropthis.drops.update("drop_abc123", { title: "Updated" });
+await dropthis.drops.delete("drop_abc123");
+```
+
+List results support auto-pagination:
+
+```typescript
+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);
+}
+```
 
-dropthis.drops.list({ limit: 20 });
-dropthis.drops.get("drop_123");
-dropthis.drops.update("drop_123", { title: "Updated" });
-dropthis.drops.delete("drop_123");
+### deployments
 
-dropthis.uploads.create({
-	schemaVersion: 1,
-	files: [{ path: "index.html", contentType: "text/html", sizeBytes: 12 }],
+```typescript
+await dropthis.deployments.create("drop_abc123", { uploadId: "upl_xyz789" });
+await dropthis.deployments.createRaw("drop_abc123", { upload_id: "upl_xyz789" });
+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.
+
+```typescript
+await dropthis.uploads.create({
+  schemaVersion: 1,
+  files: [{ path: "index.html", contentType: "text/html", sizeBytes: 1024 }],
+});
+await dropthis.uploads.get("upl_abc123");
+await dropthis.uploads.createPartTargets("upl_abc123", {
+  fileId: "file_xyz",
+  partNumbers: [1, 2, 3],
 });
-dropthis.uploads.get("upl_123");
-dropthis.uploads.complete("upl_123", { files: {} });
-dropthis.uploads.cancel("upl_123");
+await dropthis.uploads.complete("upl_abc123", { files: {} });
+await dropthis.uploads.cancel("upl_abc123");
+```
 
-dropthis.deployments.list("drop_123");
-dropthis.deployments.get("drop_123", "dep_123");
+### auth
 
-dropthis.account.get();
+```typescript
+await dropthis.auth.requestEmailOtp({ email: "you@example.com" });
+await dropthis.auth.verifyEmailOtp({ email: "you@example.com", code: "123456" });
+await dropthis.auth.logout();
 ```
+
+### apiKeys
+
+```typescript
+await dropthis.apiKeys.create({ label: "CI" });
+await dropthis.apiKeys.list();
+await dropthis.apiKeys.delete("key_abc123");
+```
+
+### account
+
+```typescript
+await dropthis.account.get();
+await dropthis.account.update({ displayName: "Jane Doe" });
+await dropthis.account.delete();
+```
+
+## Types
+
+Key types exported from the package:
+
+```typescript
+import type {
+  DropthisClientOptions,
+  DropthisResult,
+  DropthisErrorResponse,
+  DropResponse,
+  DropDeploymentResponse,
+  DropOptions,
+  PrepareOptions,
+  RequestControls,
+  PublishOptions,
+  ListPage,
+  CreateUploadSessionRequest,
+  CreateUploadSessionResponse,
+} from "@dropthis/node";
+```
+
+## Agent skills
+
+For AI coding agents (Cursor, Claude Code, Windsurf, etc.), this SDK ships with a built-in agent skill at `skills/dropthis-node/SKILL.md`. For the CLI skill, see the [CLI repo](https://github.com/dropthis-dev/dropthis-cli).
+
+## Links
+
+- [Website](https://dropthis.app)
+- [GitHub](https://github.com/dropthis-dev/dropthis-node)
+- [npm](https://www.npmjs.com/package/@dropthis/node)