@dropthis/cli 0.20.0 → 0.22.0

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

@@ -185,11 +185,13 @@ The `drops.publish()` and `drops.updateContent()` methods accept:
 - **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? }`
+- **Source URL** -- `{ kind: "source_url", sourceUrl: "https://example.com/page" }` (the server fetches it; an HTML page becomes a site, any other file becomes a single-file drop with a `rawUrl`)
+- **File bundle** -- `{ kind: "files", files: [{ path, content? | contentBase64? | bytes? | sourceUrl?, contentType? }], entry? }`. Give each file its bytes inline (`content`/`contentBase64`/`bytes`) **or** a `sourceUrl` for the server to fetch — never both on one file. Mix them freely in one bundle.
 
 Drop **settings** (title, visibility, password, noindex, expiresAt, metadata) go in the second `options` argument, not in the input object.
 
+> **A `source_url` to a non-HTML file now becomes a single-file drop.** Point a top-level source URL (`new URL(...)` or `{ kind: "source_url" }`) at an image, PDF, or text file and you get a single-file `file_viewer` drop with `rawUrl` set — the same as publishing those bytes directly. Previously a source URL only worked for HTML pages.
+
 All inputs are uploaded through staged presigned URLs — one signed PUT per file, up to 5 files in parallel. The SDK handles this transparently.
 
 ### Explicit input examples
@@ -220,6 +222,22 @@ await dropthis.drops.publish(
   },
   { title: "My Site" },
 );
+
+// Publish by reference: inline your HTML, let the server fetch the images.
+// Each `sourceUrl` file is fetched server-side (no bytes pass through your
+// process) and lands at its path in the bundle — one self-contained drop.
+await dropthis.drops.publish({
+  kind: "files",
+  files: [
+    {
+      path: "index.html",
+      content: '<h1>Gallery</h1><img src="hero.png"><img src="logo.svg">',
+    },
+    { path: "hero.png", sourceUrl: "https://cdn.example.com/hero.png" },
+    { path: "logo.svg", sourceUrl: "https://cdn.example.com/logo.svg" },
+  ],
+  entry: "index.html",
+});
 ```
 
 ## Prepare (validate without sending)

package/node_modules/@dropthis/node/dist/{drops-C92Gkuqx.d.cts → drops-DNwOp7g_.d.cts}

@@ -102,7 +102,6 @@ type DropDeploymentResponse = {
     dropId: string;
     revision: number;
     status: string;
-    storagePrefix: string;
     entry: string | null;
     contentType: string;
     renderMode: string;
@@ -204,11 +203,33 @@ type ListDropsParams = {
     /** Only drops mounted on this custom domain hostname (e.g. "reports.example.com"). */
     domain?: string;
 };
+/**
+ * One file in an upload manifest. A discriminated union:
+ *
+ * - **client-put** — the SDK pushes the bytes through a signed PUT. Requires
+ *   `contentType` and `sizeBytes`; an optional `checksumSha256` locks the
+ *   transfer integrity.
+ * - **remote** — the server fetches the bytes itself from `sourceUrl` during
+ *   `POST /uploads/{id}/ingest`. No bytes leave this process, so `sizeBytes`,
+ *   `contentType`, and `checksumSha256` are all optional (the server infers
+ *   them on fetch). Carries NO signed PUT target.
+ *
+ * `sourceUrl` is the discriminant: present ⇒ remote, absent ⇒ client-put. The
+ * camelCase `sourceUrl` becomes the wire field `source_url` via the transport's
+ * snake_case conversion (exactly like `contentType` → `content_type`).
+ */
 type UploadManifestFile = {
     path: string;
     contentType: string;
     sizeBytes: number;
     checksumSha256?: string | null;
+    sourceUrl?: never;
+} | {
+    path: string;
+    sourceUrl: string;
+    contentType?: string;
+    sizeBytes?: number;
+    checksumSha256?: string | null;
 };
 type CreateUploadSessionRequest = {
     schemaVersion?: 1;
@@ -315,13 +336,61 @@ type PublishOptions = DropOptions & PrepareOptions & RequestControls;
 type UpdateContentOptions = PrepareOptions & RequestControls & {
     /** Entry file for multi-file bundles (default: index.html). */
     entry?: string;
+    /**
+     * How the supplied files combine with what the drop already serves
+     * (partial-by-default, ADR 0065):
+     *
+     * - `"patch"` (default): the supplied files upsert by path and every
+     *   unmentioned file is carried forward, so editing one file never drops the
+     *   rest. Use `deletePaths` to remove files.
+     * - `"replace"`: the supplied files become the drop's entire content set —
+     *   a full swap. Anything not supplied is gone. `deletePaths` is invalid here.
+     *
+     * Omit to default to `"patch"`.
+     */
+    mode?: "patch" | "replace";
+    /**
+     * Paths to remove from the drop's content (patch-mode only). Each path must
+     * exist or the server rejects the update (loud, never a silent no-op). Invalid
+     * with `mode: "replace"`. Wire field: `delete_paths`.
+     */
+    deletePaths?: string[];
 };
+/**
+ * One file in a multi-file `{ kind: "files" }` bundle. Supply the bytes inline
+ * exactly one way — `content` (UTF-8 text), `contentBase64`, or `bytes` — OR set
+ * `sourceUrl` to a public http(s) URL and let the server fetch that file for you
+ * server-side (no bytes pass through your process). A single entry may NOT carry
+ * both inline bytes and `sourceUrl`. Mix freely within one bundle: e.g. inline
+ * `content` for `index.html` plus a `sourceUrl` for each image referenced by it,
+ * yielding one self-contained drop.
+ */
 type PublishFileInput = {
     path: string;
     contentType?: string;
     content?: string;
     contentBase64?: string;
     bytes?: Uint8Array;
+    /**
+     * Public http(s) URL the server fetches this file's bytes from during publish
+     * (publish by reference). Mutually exclusive with `content`/`contentBase64`/`bytes`.
+     */
+    sourceUrl?: string;
+    /**
+     * Declared byte size of the remote file (optional hint for `sourceUrl` files).
+     * When provided, the server uses this for upfront quota admission before fetching,
+     * so a large file is rejected immediately rather than after the server downloads it.
+     * Ignored for inline files (size is computed from the bytes).
+     */
+    sizeBytes?: number;
+    /**
+     * Expected SHA-256 hex digest of the remote file (optional hint for `sourceUrl` files).
+     * When provided, the server verifies the fetched content matches this checksum and
+     * rejects the publish if it does not, giving you integrity verification without
+     * downloading the bytes yourself.
+     * Ignored for inline files (checksum is computed by the SDK/server from actual bytes).
+     */
+    checksumSha256?: string;
 };
 type PublishInput = string | string[] | URL | Uint8Array | {
     kind: "content";
@@ -485,17 +554,32 @@ declare class Transport {
 }
 
 /**
- * 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.
+ * A file ready to be staged for upload. Two shapes:
+ *
+ * - **client-put** — the SDK pushes the bytes. 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.
+ * - **remote** (`sourceUrl` set, no `getBody`) — the server fetches the bytes from
+ *   `sourceUrl` during `POST /uploads/{id}/ingest`. No bytes leave this process, so
+ *   it has no `getBody`, no `sizeBytes`, and consumes no signed PUT target.
  */
 type PreparedUploadFile = {
     path: string;
     contentType: string;
     sizeBytes: number;
     checksumSha256?: string;
+    sourceUrl?: never;
     getBody(): Promise<Uint8Array | Blob | ReadableStream>;
+} | {
+    path: string;
+    sourceUrl: string;
+    contentType?: string;
+    /** Optional hint: declared byte size for upfront quota admission (server-side). */
+    sizeBytes?: number;
+    /** Optional hint: expected SHA-256 hex digest for server-side integrity check. */
+    checksumSha256?: string;
+    getBody?: never;
 };
 /**
  * Resolves a publish input into a {@link PreparedPublishRequest}. Two implementations exist:

package/node_modules/@dropthis/node/dist/{drops-C92Gkuqx.d.ts → drops-DNwOp7g_.d.ts}

@@ -102,7 +102,6 @@ type DropDeploymentResponse = {
     dropId: string;
     revision: number;
     status: string;
-    storagePrefix: string;
     entry: string | null;
     contentType: string;
     renderMode: string;
@@ -204,11 +203,33 @@ type ListDropsParams = {
     /** Only drops mounted on this custom domain hostname (e.g. "reports.example.com"). */
     domain?: string;
 };
+/**
+ * One file in an upload manifest. A discriminated union:
+ *
+ * - **client-put** — the SDK pushes the bytes through a signed PUT. Requires
+ *   `contentType` and `sizeBytes`; an optional `checksumSha256` locks the
+ *   transfer integrity.
+ * - **remote** — the server fetches the bytes itself from `sourceUrl` during
+ *   `POST /uploads/{id}/ingest`. No bytes leave this process, so `sizeBytes`,
+ *   `contentType`, and `checksumSha256` are all optional (the server infers
+ *   them on fetch). Carries NO signed PUT target.
+ *
+ * `sourceUrl` is the discriminant: present ⇒ remote, absent ⇒ client-put. The
+ * camelCase `sourceUrl` becomes the wire field `source_url` via the transport's
+ * snake_case conversion (exactly like `contentType` → `content_type`).
+ */
 type UploadManifestFile = {
     path: string;
     contentType: string;
     sizeBytes: number;
     checksumSha256?: string | null;
+    sourceUrl?: never;
+} | {
+    path: string;
+    sourceUrl: string;
+    contentType?: string;
+    sizeBytes?: number;
+    checksumSha256?: string | null;
 };
 type CreateUploadSessionRequest = {
     schemaVersion?: 1;
@@ -315,13 +336,61 @@ type PublishOptions = DropOptions & PrepareOptions & RequestControls;
 type UpdateContentOptions = PrepareOptions & RequestControls & {
     /** Entry file for multi-file bundles (default: index.html). */
     entry?: string;
+    /**
+     * How the supplied files combine with what the drop already serves
+     * (partial-by-default, ADR 0065):
+     *
+     * - `"patch"` (default): the supplied files upsert by path and every
+     *   unmentioned file is carried forward, so editing one file never drops the
+     *   rest. Use `deletePaths` to remove files.
+     * - `"replace"`: the supplied files become the drop's entire content set —
+     *   a full swap. Anything not supplied is gone. `deletePaths` is invalid here.
+     *
+     * Omit to default to `"patch"`.
+     */
+    mode?: "patch" | "replace";
+    /**
+     * Paths to remove from the drop's content (patch-mode only). Each path must
+     * exist or the server rejects the update (loud, never a silent no-op). Invalid
+     * with `mode: "replace"`. Wire field: `delete_paths`.
+     */
+    deletePaths?: string[];
 };
+/**
+ * One file in a multi-file `{ kind: "files" }` bundle. Supply the bytes inline
+ * exactly one way — `content` (UTF-8 text), `contentBase64`, or `bytes` — OR set
+ * `sourceUrl` to a public http(s) URL and let the server fetch that file for you
+ * server-side (no bytes pass through your process). A single entry may NOT carry
+ * both inline bytes and `sourceUrl`. Mix freely within one bundle: e.g. inline
+ * `content` for `index.html` plus a `sourceUrl` for each image referenced by it,
+ * yielding one self-contained drop.
+ */
 type PublishFileInput = {
     path: string;
     contentType?: string;
     content?: string;
     contentBase64?: string;
     bytes?: Uint8Array;
+    /**
+     * Public http(s) URL the server fetches this file's bytes from during publish
+     * (publish by reference). Mutually exclusive with `content`/`contentBase64`/`bytes`.
+     */
+    sourceUrl?: string;
+    /**
+     * Declared byte size of the remote file (optional hint for `sourceUrl` files).
+     * When provided, the server uses this for upfront quota admission before fetching,
+     * so a large file is rejected immediately rather than after the server downloads it.
+     * Ignored for inline files (size is computed from the bytes).
+     */
+    sizeBytes?: number;
+    /**
+     * Expected SHA-256 hex digest of the remote file (optional hint for `sourceUrl` files).
+     * When provided, the server verifies the fetched content matches this checksum and
+     * rejects the publish if it does not, giving you integrity verification without
+     * downloading the bytes yourself.
+     * Ignored for inline files (checksum is computed by the SDK/server from actual bytes).
+     */
+    checksumSha256?: string;
 };
 type PublishInput = string | string[] | URL | Uint8Array | {
     kind: "content";
@@ -485,17 +554,32 @@ declare class Transport {
 }
 
 /**
- * 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.
+ * A file ready to be staged for upload. Two shapes:
+ *
+ * - **client-put** — the SDK pushes the bytes. 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.
+ * - **remote** (`sourceUrl` set, no `getBody`) — the server fetches the bytes from
+ *   `sourceUrl` during `POST /uploads/{id}/ingest`. No bytes leave this process, so
+ *   it has no `getBody`, no `sizeBytes`, and consumes no signed PUT target.
  */
 type PreparedUploadFile = {
     path: string;
     contentType: string;
     sizeBytes: number;
     checksumSha256?: string;
+    sourceUrl?: never;
     getBody(): Promise<Uint8Array | Blob | ReadableStream>;
+} | {
+    path: string;
+    sourceUrl: string;
+    contentType?: string;
+    /** Optional hint: declared byte size for upfront quota admission (server-side). */
+    sizeBytes?: number;
+    /** Optional hint: expected SHA-256 hex digest for server-side integrity check. */
+    checksumSha256?: string;
+    getBody?: never;
 };
 /**
  * Resolves a publish input into a {@link PreparedPublishRequest}. Two implementations exist:

package/node_modules/@dropthis/node/dist/edge.cjs

@@ -220,18 +220,34 @@ function updateContentOptions(options) {
   if (options.idempotencyKey !== void 0)
     out.idempotencyKey = options.idempotencyKey;
   if (options.ifRevision !== void 0) out.ifRevision = options.ifRevision;
+  if (options.mode !== void 0) out.mode = options.mode;
+  if (options.deletePaths !== void 0) out.deletePaths = options.deletePaths;
   return out;
 }
 function buildStagedRequest(files, options, entry) {
   assertNonEmptyBundle(files.map((f) => f.path));
   const normalizedPaths = files.map((f) => normalizeManifestPath(f.path));
   assertNoDuplicatePaths(normalizedPaths);
-  const manifestFiles = files.map((file) => ({
-    path: normalizeManifestPath(file.path),
-    contentType: file.contentType,
-    sizeBytes: file.sizeBytes,
-    ...file.checksumSha256 ? { checksumSha256: file.checksumSha256 } : {}
-  }));
+  const manifestFiles = files.map(
+    (file) => file.sourceUrl !== void 0 ? (
+      // Remote entry: the server fetches the bytes on /ingest. Emit sourceUrl
+      // plus optional metadata hints (contentType, sizeBytes, checksumSha256)
+      // when the caller declared them. The transport snake_cases all camelCase
+      // keys to source_url / content_type / size_bytes / checksum_sha256.
+      {
+        path: normalizeManifestPath(file.path),
+        sourceUrl: file.sourceUrl,
+        ...file.contentType ? { contentType: file.contentType } : {},
+        ...file.sizeBytes !== void 0 ? { sizeBytes: file.sizeBytes } : {},
+        ...file.checksumSha256 ? { checksumSha256: file.checksumSha256 } : {}
+      }
+    ) : {
+      path: normalizeManifestPath(file.path),
+      contentType: file.contentType,
+      sizeBytes: file.sizeBytes,
+      ...file.checksumSha256 ? { checksumSha256: file.checksumSha256 } : {}
+    }
+  );
   const resolvedEntry = entry ?? options.entry;
   if (resolvedEntry !== void 0) assertValidManifestPath(resolvedEntry);
   const manifest = {
@@ -277,9 +293,48 @@ function fileBytes(file) {
     "missing_file_bytes",
     `File "${file.path}" is missing content bytes.`,
     file.path,
-    "Provide one of content, contentBase64, or bytes."
+    "Provide one of content, contentBase64, or bytes, or set sourceUrl."
   );
 }
+function hasInlineBytes(file) {
+  return file.content !== void 0 || file.contentBase64 !== void 0 || file.bytes !== void 0;
+}
+function prepareBundleFile(file) {
+  assertValidManifestPath(file.path);
+  if (file.sourceUrl !== void 0) {
+    if (hasInlineBytes(file)) {
+      throw new PublishInputError(
+        "conflicting_file_source",
+        `File "${file.path}" sets both inline content and sourceUrl; pick one.`,
+        file.path,
+        "Drop sourceUrl to upload bytes, or drop content/contentBase64/bytes to fetch by reference."
+      );
+    }
+    if (!isHttpUrl(file.sourceUrl)) {
+      throw new PublishInputError(
+        "invalid_source_url",
+        `File "${file.path}" sourceUrl must be an http(s) URL.`,
+        file.path,
+        "Fetch the bytes first and pass them inline, or use an http(s) URL."
+      );
+    }
+    return {
+      path: file.path,
+      sourceUrl: file.sourceUrl,
+      ...file.contentType ? { contentType: file.contentType } : {},
+      ...file.sizeBytes !== void 0 ? { sizeBytes: file.sizeBytes } : {},
+      ...file.checksumSha256 ? { checksumSha256: file.checksumSha256 } : {}
+    };
+  }
+  const bytes = fileBytes(file);
+  const contentType = file.contentType ?? detectBytesContentType(bytes);
+  return {
+    path: file.path,
+    contentType,
+    sizeBytes: bytes.byteLength,
+    getBody: async () => bytes
+  };
+}
 function singleStagedFile(path, contentType, bytes, options) {
   return buildStagedRequest(
     [
@@ -322,20 +377,17 @@ async function resolveInMemory(input, options = {}) {
   if (input.kind === "source_url") {
     return buildSourceRequest(input.sourceUrl, options);
   }
-  const files = input.files.map((file) => {
-    assertValidManifestPath(file.path);
-    const bytes = fileBytes(file);
-    const contentType = file.contentType ?? detectBytesContentType(bytes);
-    return {
-      path: file.path,
-      contentType,
-      sizeBytes: bytes.byteLength,
-      getBody: async () => bytes
-    };
-  });
+  const files = input.files.map(prepareBundleFile);
   return buildStagedRequest(files, options, input.entry);
 }
+function partialUpdateBody(options) {
+  return {
+    ...options.mode !== void 0 ? { mode: options.mode } : {},
+    ...options.deletePaths !== void 0 ? { deletePaths: options.deletePaths } : {}
+  };
+}
 var UPLOAD_CONCURRENCY = 5;
+var INGEST_TIMEOUT_MS = 12e4;
 function errorResult(result) {
   if (!result.error) throw new Error("Expected an error result");
   return { data: null, error: result.error, headers: result.headers };
@@ -391,6 +443,7 @@ async function publishStaged(transport, prepared, finalPath, options = {}) {
   if (createResult.error) return errorResult(createResult);
   const jobs = [];
   for (const file of prepared.files) {
+    if (file.sourceUrl !== void 0) continue;
     const target = createResult.data.files.find((f) => f.path === file.path);
     if (!target) {
       return createErrorResult(
@@ -410,6 +463,18 @@ async function publishStaged(transport, prepared, finalPath, options = {}) {
   }
   const uploadFailure = await uploadStagedFiles(transport, jobs);
   if (uploadFailure) return uploadFailure;
+  const hasRemote = prepared.files.some((f) => f.sourceUrl !== void 0);
+  if (hasRemote) {
+    const ingestResult = await transport.request(
+      "POST",
+      `/uploads/${encodeURIComponent(createResult.data.uploadId)}/ingest`,
+      {
+        idempotencyKey: `${baseKey}:ingest-upload`,
+        timeoutMs: INGEST_TIMEOUT_MS
+      }
+    );
+    if (ingestResult.error) return errorResult(ingestResult);
+  }
   const completeResult = await transport.request(
     "POST",
     `/uploads/${encodeURIComponent(createResult.data.uploadId)}/complete`,
@@ -422,7 +487,8 @@ async function publishStaged(transport, prepared, finalPath, options = {}) {
     body: {
       uploadId: createResult.data.uploadId,
       ...Object.keys(prepared.options).length > 0 ? { options: prepared.options } : {},
-      ...prepared.metadata ? { metadata: prepared.metadata } : {}
+      ...prepared.metadata ? { metadata: prepared.metadata } : {},
+      ...partialUpdateBody(options)
     },
     idempotencyKey: `${baseKey}:publish`
   };
@@ -436,7 +502,8 @@ async function publishSource(transport, prepared, finalPath, options = {}) {
     body: {
       sourceUrl: prepared.sourceUrl,
       ...Object.keys(prepared.options).length > 0 ? { options: prepared.options } : {},
-      ...prepared.metadata ? { metadata: prepared.metadata } : {}
+      ...prepared.metadata ? { metadata: prepared.metadata } : {},
+      ...partialUpdateBody(options)
     },
     idempotencyKey: `${baseKey}:publish`,
     ...options.ifRevision !== void 0 ? { ifRevision: options.ifRevision } : {}
@@ -804,7 +871,7 @@ function toSnakeCase(value) {
 
 // src/transport.ts
 var DEFAULT_BASE_URL = "https://api.dropthis.app";
-var SDK_VERSION = "0.18.0";
+var SDK_VERSION = "0.20.0";
 var Transport = class {
   apiKey;
   baseUrl;