@dropthis/cli 0.4.1 → 0.6.0

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

@@ -68,39 +68,96 @@ await dropthis.update("drop_abc123", { title: "New title" });
 
 ## Supported inputs
 
-The `publish()` method accepts:
+The `publish()` and `deploy()` methods accept:
 
-- **HTML string** -- `"<h1>Hello</h1>"`
-- **File path** -- `"./report.html"`
-- **Directory** -- `"./dist"`
-- **Bytes** -- `new Uint8Array(...)`
-- **Explicit object** -- `{ content: "...", contentType: "text/html" }` or `{ files: [...] }`
+- **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
+
+```typescript
+// 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).
+
+```typescript
+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 `{ data, error, headers }`. Check `error` before using `data`.
+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`.
 
 ```typescript
 const result = await dropthis.drops.get("drop_abc123");
 
 if (result.error) {
   console.error(result.error.code, result.error.message);
-  // error.statusCode, error.requestId also available
+  // 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
 
 ```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.
+  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.
 });
 ```
 
@@ -117,8 +174,6 @@ const dropthis = new Dropthis("sk_...");
 ```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");
 ```
@@ -135,11 +190,11 @@ for await (const drop of page.data) {
 }
 ```
 
+> 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
 
 ```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");
 ```
@@ -154,10 +209,6 @@ await dropthis.uploads.create({
   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],
-});
 await dropthis.uploads.complete("upl_abc123", { files: {} });
 await dropthis.uploads.cancel("upl_abc123");
 ```
@@ -186,6 +237,21 @@ 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`.
+
+```typescript
+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:
@@ -201,6 +267,8 @@ import type {
   PrepareOptions,
   RequestControls,
   PublishOptions,
+  PublishInput,
+  PublishFileInput,
   ListPage,
   CreateUploadSessionRequest,
   CreateUploadSessionResponse,
@@ -209,7 +277,11 @@ import type {
 
 ## 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).
+For AI coding agents (Cursor, Claude Code, Windsurf, etc.), install the [dropthis-skills](https://github.com/dropthis-dev/dropthis-skills) package:
+
+```bash
+npx skills add dropthis-dev/dropthis-skills
+```
 
 ## Links
 

package/node_modules/@dropthis/node/dist/drops-BPdmUPCT.d.cts

@@ -0,0 +1,394 @@
+type DropthisClientOptions = {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    uploadTimeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+};
+type RequestOptions = {
+    authenticated?: boolean;
+    idempotencyKey?: string;
+    ifRevision?: number;
+    timeoutMs?: number;
+};
+type DropthisErrorResponse = {
+    code: string;
+    message: string;
+    statusCode: number | null;
+    type?: string;
+    title?: string;
+    detail?: string | null;
+    instance?: string | null;
+    param?: string | null;
+    currentRevision?: number;
+    requestId?: string | null;
+    suggestion?: string | null;
+    retryable?: boolean | null;
+    body?: unknown;
+};
+type DropthisResult<T> = {
+    data: T;
+    error: null;
+    headers: Record<string, string>;
+} | {
+    data: null;
+    error: DropthisErrorResponse;
+    headers: Record<string, string>;
+};
+type ActionResolve = {
+    method: string;
+    url?: string | null;
+    endpoint?: string | null;
+};
+type DropAction = {
+    code: string;
+    kind: "api" | "human";
+    priority: "required" | "suggested";
+    message: string;
+    resolve?: ActionResolve | null;
+};
+type TierInfo = {
+    name: string;
+    maxSizeBytes: number;
+    ttlDays: number | null;
+    persistent: boolean;
+    badge: boolean;
+};
+type Limitations = {
+    actions: DropAction[];
+};
+type DropResponse = {
+    id: string;
+    slug: string;
+    url: string;
+    deploymentId: string | null;
+    title: string;
+    contentType: string;
+    visibility: string;
+    status: string;
+    revision: number;
+    contentRevision: number;
+    accessRevision: number;
+    sizeBytes: number;
+    renderMode: string;
+    warnings: Array<Record<string, unknown>>;
+    createdAt: string;
+    expiresAt: string | null;
+    object: string;
+    accessible: boolean;
+    persistent: boolean;
+    badgeApplied: boolean;
+    tier: TierInfo;
+    limitations: Limitations;
+};
+type DropDeploymentResponse = {
+    id: string;
+    dropId: string;
+    revision: number;
+    status: string;
+    storagePrefix: string;
+    entry: string | null;
+    contentType: string;
+    renderMode: string;
+    files: Array<Record<string, unknown>>;
+    warnings: Array<Record<string, unknown>>;
+    sizeBytes: number;
+    classificationVersion: number;
+    classificationReason: string;
+    errorCode: string | null;
+    errorMessage: string | null;
+    createdAt: string;
+    readyAt: string | null;
+    publishedAt: string | null;
+};
+type ListDeploymentsParams = {
+    cursor?: string | null;
+    limit?: number;
+};
+type ListDeploymentsResponse = {
+    deployments: DropDeploymentResponse[];
+    nextCursor: string | null;
+};
+type ListPage<T> = {
+    object: "list";
+    data: T[];
+    hasMore: boolean;
+    nextCursor: string | null;
+    autoPagingToArray(options?: {
+        limit?: number;
+    }): Promise<T[]>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+};
+type Action = {
+    code: string;
+    kind: string;
+    method?: string | null;
+    endpoint?: string | null;
+    message: string;
+};
+type EmailOtpResponse = {
+    ok: true;
+    expiresIn: number;
+    nextAction?: Action | null;
+};
+type SessionResponse = {
+    object: "session";
+    token: string;
+    accountId: string;
+    isNewAccount: boolean;
+    expiresIn: number;
+};
+type ApiKeyResponse = {
+    object: "api_key";
+    id: string;
+    keyLast4: string;
+    label: string;
+    createdAt: string;
+};
+type ApiKeyCreatedResponse = ApiKeyResponse & {
+    key: string;
+    accountId?: string | null;
+    isNewAccount?: boolean;
+};
+type AccountResponse = {
+    id: string;
+    email: string;
+    displayName: string | null;
+    plan: string;
+    status: string;
+    createdAt: string;
+};
+type ListDropsParams = {
+    cursor?: string | null;
+    limit?: number;
+};
+type UploadManifestFile = {
+    path: string;
+    contentType: string;
+    sizeBytes: number;
+    checksumSha256?: string | null;
+};
+type CreateUploadSessionRequest = {
+    schemaVersion?: 1;
+    files: UploadManifestFile[];
+    entry?: string | null;
+};
+type UploadTarget = {
+    strategy: "single_put" | "multipart";
+    url: string;
+    headers: Record<string, string>;
+    expiresAt: string;
+};
+type CreateUploadSessionFileResponse = {
+    fileId: string;
+    path: string;
+    objectKey: string;
+    upload: UploadTarget;
+};
+type UploadSessionFileResponse = {
+    fileId: string;
+    path: string;
+    contentType: string;
+    sizeBytes: number;
+    objectKey: string;
+    verified: boolean;
+};
+type UploadSessionResponse = {
+    uploadId: string;
+    status: string;
+    expiresAt: string;
+    entry?: string | null;
+    files: UploadSessionFileResponse[];
+    nextAction?: Action | null;
+};
+type CreateUploadSessionResponse = {
+    uploadId: string;
+    expiresAt: string;
+    files: CreateUploadSessionFileResponse[];
+    nextAction?: Action | null;
+};
+type CompleteUploadSessionRequest = {
+    files?: Record<string, {
+        parts?: Array<{
+            partNumber: number;
+            etag: string;
+        }> | null;
+    }>;
+};
+type DropOptions = {
+    /** Change the vanity slug (update only). */
+    slug?: string;
+    /** Drop title. */
+    title?: string;
+    /** public (default) or unlisted. */
+    visibility?: "public" | "unlisted";
+    /** Require password to view. Pass `null` to remove password protection. */
+    password?: string | null;
+    /** Prevent search-engine indexing. Pass `null` to allow indexing (default). */
+    noindex?: boolean | null;
+    /** Auto-delete after this ISO 8601 date. Pass `null` to clear. */
+    expiresAt?: string | Date | null;
+    /** Entry file for multi-file bundles (default: index.html). */
+    entry?: string;
+    /** Attach JSON key-value pairs, e.g. `{ source: "ci" }`. */
+    metadata?: Record<string, unknown>;
+};
+type PrepareOptions = {
+    /** Glob patterns to ignore when publishing directories. */
+    ignore?: string[];
+    /** Disable default ignore patterns. */
+    ignoreDefaults?: boolean;
+    /** Override MIME type (auto-detected from extension). */
+    contentType?: string;
+    /** Set filename when publishing from stdin or bytes. */
+    path?: string;
+};
+type RequestControls = {
+    /** Prevent duplicate publishes on retry (auto-generated by CLI). */
+    idempotencyKey?: string;
+    /** Fail if current revision doesn't match -- optimistic lock (update only). */
+    ifRevision?: number;
+};
+type PublishOptions = DropOptions & PrepareOptions & RequestControls;
+type PublishFileInput = {
+    path: string;
+    contentType?: string;
+    content?: string;
+    contentBase64?: string;
+    bytes?: Uint8Array;
+};
+type PublishInput = string | string[] | URL | Uint8Array | {
+    kind: "content";
+    content: string;
+    contentType?: string;
+    path?: string;
+} | {
+    kind: "source_url";
+    sourceUrl: string;
+} | {
+    kind: "files";
+    files: PublishFileInput[];
+    entry?: string;
+};
+
+declare class Transport {
+    readonly apiKey: string | undefined;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly uploadTimeoutMs: number;
+    readonly fetchImpl: typeof globalThis.fetch;
+    constructor(options?: DropthisClientOptions | string);
+    putSignedUrl(url: string, body: Uint8Array | Blob | ReadableStream, headers: Record<string, string>): Promise<DropthisResult<{
+        etag: string | null;
+    }>>;
+    request<T>(method: string, path: string, options?: RequestOptions & {
+        body?: unknown;
+        bodyCase?: "snake" | "raw";
+        params?: Record<string, string | number | boolean | null | undefined>;
+    }): Promise<DropthisResult<T>>;
+}
+
+/**
+ * A file ready to be staged for upload. The body is lazy: the orchestrator
+ * calls `getBody()` per file when it is ready to push bytes to the signed URL.
+ * This keeps the resolution layer pure and lets the filesystem layer (node.ts)
+ * defer reads/streams until upload time.
+ */
+type PreparedUploadFile = {
+    path: string;
+    contentType: string;
+    sizeBytes: number;
+    checksumSha256?: string;
+    getBody(): Promise<Uint8Array | Blob | ReadableStream>;
+};
+type PreparedPublishRequest = {
+    kind: "staged";
+    manifest: CreateUploadSessionRequest;
+    files: PreparedUploadFile[];
+    options: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+} | {
+    kind: "source";
+    sourceUrl: string;
+    options: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * The canonical publish inputs that can be resolved with no filesystem access:
+ * the {@link PublishInput} union minus `string[]` (which is inherently a list
+ * of filesystem paths handled by node.ts).
+ */
+type InMemoryPublishInput = string | URL | Uint8Array | {
+    kind: "content";
+    content: string;
+    contentType?: string;
+    path?: string;
+} | {
+    kind: "source_url";
+    sourceUrl: string;
+} | {
+    kind: "files";
+    files: PublishFileInput[];
+    entry?: string;
+};
+
+declare class AccountResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    get(): Promise<DropthisResult<AccountResponse>>;
+    update(input: {
+        displayName: string | null;
+    }): Promise<DropthisResult<AccountResponse>>;
+    delete(): Promise<DropthisResult<null>>;
+}
+
+declare class ApiKeysResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    list(): Promise<DropthisResult<{
+        object: "list";
+        data: ApiKeyResponse[];
+    }>>;
+    create(input: {
+        label: string;
+    }): Promise<DropthisResult<ApiKeyCreatedResponse>>;
+    delete(keyId: string): Promise<DropthisResult<{
+        ok: true;
+    }>>;
+}
+
+declare class DeploymentsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    list(dropId: string, params?: ListDeploymentsParams): Promise<DropthisResult<ListDeploymentsResponse>>;
+    get(dropId: string, deploymentId: string): Promise<DropthisResult<DropDeploymentResponse>>;
+}
+
+declare class CursorPage<T> implements ListPage<T> {
+    readonly object: "list";
+    readonly data: T[];
+    readonly hasMore: boolean;
+    readonly nextCursor: string | null;
+    private readonly fetchNextPage;
+    constructor(input: {
+        data: T[];
+        hasMore: boolean;
+        nextCursor: string | null;
+        fetchNextPage?: (() => Promise<DropthisResult<CursorPage<T>>>) | undefined;
+    });
+    autoPagingToArray(options?: {
+        limit?: number;
+    }): Promise<T[]>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}
+
+declare class DropsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    list(params?: ListDropsParams): Promise<DropthisResult<CursorPage<DropResponse>>>;
+    get(dropId: string): Promise<DropthisResult<DropResponse>>;
+    update(dropId: string, options?: DropOptions & RequestControls): Promise<DropthisResult<DropResponse>>;
+    delete(dropId: string): Promise<DropthisResult<null>>;
+}
+
+export { AccountResource as A, type CompleteUploadSessionRequest as C, DeploymentsResource as D, type EmailOtpResponse as E, type InMemoryPublishInput as I, type Limitations as L, type PrepareOptions as P, type RequestControls as R, type SessionResponse as S, type TierInfo as T, type UploadManifestFile as U, type ActionResolve as a, ApiKeysResource as b, type CreateUploadSessionRequest as c, type CreateUploadSessionResponse as d, CursorPage as e, type DropAction as f, type DropDeploymentResponse as g, type DropOptions as h, type DropResponse as i, DropsResource as j, type DropthisClientOptions as k, type DropthisErrorResponse as l, type DropthisResult as m, type ListDeploymentsParams as n, type ListDeploymentsResponse as o, type ListPage as p, type PreparedPublishRequest as q, type PreparedUploadFile as r, type PublishFileInput as s, type PublishInput as t, type PublishOptions as u, type RequestOptions as v, Transport as w, type UploadSessionFileResponse as x, type UploadSessionResponse as y, type UploadTarget as z };