@dropthis/cli 0.16.0 → 0.18.0

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

@@ -16,10 +16,14 @@ import { Dropthis } from "@dropthis/node";
 const dropthis = new Dropthis({ apiKey: "sk_..." });
 const { data, error } = await dropthis.drops.publish("<h1>Hello</h1>");
 
-console.log(data.url); // https://abc123.dropthis.app
+console.log(data.url); // https://abc123.dropthis.app — branded human view (always badged)
 console.log(data.id);  // drop_… — keep this; it's how you update or delete later
 ```
 
+> **Sharing with an agent? Use `data.rawUrl`.** The canonical `url` always renders a
+> branded human view; `rawUrl` is the drop's exact bytes (single-file drops only — `null`
+> otherwise). See [Canonical URL vs raw bytes](#canonical-url-vs-raw-bytes-rawurl).
+
 > **Keep the `drop_…` id.** `publish()` never takes an id — every call creates a NEW drop.
 > To change something already published, pass the id from the publish response to
 > `drops.updateContent()` (the files at the URL) or `drops.updateSettings()` (title,
@@ -74,11 +78,14 @@ await dropthis.drops.updateSettings("drop_abc123", { title: "New title" });
 
 ### Resolve a URL back to its drop
 
-Lost the `drop_…` id? Resolve the drop's URL (or bare slug) back to the drop. The slug is
-parsed client-side from the first hostname label of a dropthis hostname
-(`<slug>.dropthis.app`, or `<slug>.` + your configured `baseUrl` host), then matched against
-your own drops via `GET /drops?slug=`. Custom-domain URLs are not resolvable yet — they are
-rejected client-side with an `invalid_drop_url` error, without hitting the API.
+Lost the `drop_…` id? Resolve any public locator — a drop URL, a custom-domain URL, or a bare
+vanity/shared slug — back to the drop. The target is sent to the server (`POST /drops/resolve`),
+which owner-scopes and decomposes it; you get the full drop back, or `null` when nothing of yours
+matches. Passing a `drop_…` id round-trips to an owner-scoped lookup.
+
+> Persist the drop_… id. URLs, raw_url, and slugs are locators, not identifiers — a vanity slug is
+> renameable and the pool host rotates, so a stored URL can drift; the id never moves. Treat
+> drop_… as an opaque case-sensitive string.
 
 ```typescript
 const { data } = await dropthis.drops.resolve("https://my-report.dropthis.app/");
@@ -114,6 +121,36 @@ const old = await dropthis.drops.getContent("drop_abc123", {
 });
 ```
 
+### Canonical URL vs raw bytes (`rawUrl`)
+
+Every drop has two faces. The canonical `data.url` **always serves a branded human
+view** — that is how the dropthis badge is guaranteed without sniffing who's asking.
+For a single non-HTML file (`renderMode: "file_viewer"`) that view is a branded
+preview (image inline, text/markdown/JSON/CSV/code as escaped source, opaque binary as
+a download); for a multi-file bundle with no HTML entry it's a branded index. An HTML
+drop (`renderMode: "user_html"`) renders the page itself.
+
+When you need the underlying file's **exact bytes** (e.g. one agent handing an artifact
+to another), use `data.rawUrl` — the drop's bytes at their natural path under the mount.
+It's populated **only for single-file (`file_viewer`) drops** and is `null` for
+`user_html` and collections (the page is itself the artifact / per-file natural paths
+come from the manifest). Hand `url` to humans and `rawUrl` to agents.
+
+```typescript
+const { data } = await dropthis.drops.publish("./notes.md");
+
+console.log(data.url);    // https://abc123.dropthis.app/        ← branded preview (badge)
+console.log(data.rawUrl); // https://abc123.dropthis.app/notes.md ← exact bytes for agents
+console.log(data.renderMode); // "file_viewer"
+
+// An HTML site or a multi-file collection has no single raw file:
+// data.rawUrl === null  (use drops.getContent() to pull bytes by path)
+```
+
+To stream bytes through the SDK regardless of drop kind (and owner-only, so it works even
+on password-protected drops), use [`drops.getContent()`](#read-back-what-a-drop-is-serving) —
+that's the programmatic byte-fetch path; `rawUrl` is the public, shareable one.
+
 ### Safe concurrent edits with ifRevision
 
 Every drop response carries a `revision`. Pass it back as `ifRevision` on
@@ -246,7 +283,8 @@ const dropthis = new Dropthis("sk_...");
 await dropthis.drops.list({ limit: 20 });
 await dropthis.drops.list({ domain: "reports.example.com" }); // only drops mounted on a custom domain
 await dropthis.drops.get("drop_abc123");
-await dropthis.drops.resolve("https://my-report.dropthis.app/"); // URL/slug → drop (or null)
+await dropthis.drops.resolve("https://my-report.dropthis.app/"); // any locator → drop (or null)
+await dropthis.drops.resolve("drop_abc123"); // a bare id round-trips too
 await dropthis.drops.getContent("drop_abc123");                  // manifest of served files
 await dropthis.drops.getContent("drop_abc123", { path: "index.html" }); // one file's bytes
 await dropthis.drops.updateSettings("drop_abc123", { title: "Updated" });

package/node_modules/@dropthis/node/dist/{drops-BtAGkA9A.d.cts → drops-DmTdQTnd.d.cts}

@@ -85,6 +85,17 @@ type DropResponse = {
     limitations: Limitations;
     /** Hostname of the custom domain this drop is mounted on; null for shared-pool drops. */
     domain: string | null;
+    /**
+     * Direct URL to the drop's raw bytes — the agent byte-fetch path. The canonical
+     * `url` always serves a branded human view (so the badge is guaranteed); `rawUrl`
+     * serves the underlying file's exact bytes at its natural path under the mount
+     * (ADR 0061). Populated only for single-file (`renderMode: "file_viewer"`) drops
+     * (= canonical URL + the entry filename); `null` for `user_html` drops (the page
+     * IS the artifact) and collections (per-file natural paths come from the manifest —
+     * see {@link DeploymentContentManifest}). Hand `url` to humans and `rawUrl` to agents.
+     * To stream bytes through the SDK regardless of drop kind, use `drops.getContent()`.
+     */
+    rawUrl: string | null;
 };
 type DropDeploymentResponse = {
     id: string;
@@ -617,14 +628,7 @@ declare class CursorPage<T> implements ListPage<T> {
 declare class DropsResource<TInput = PublishInput> {
     private readonly transport;
     private readonly resolveInput;
-    private parentHosts?;
     constructor(transport: Transport, resolveInput: PublishInputResolver<TInput>);
-    /**
-     * Hostnames the SDK can attribute to dropthis for slug parsing: the canonical
-     * viewer domain plus the configured baseUrl's host (covers staging/self-hosted
-     * setups where drops are served under the API's own domain).
-     */
-    private allowedParentHosts;
     /**
      * Publish content to a NEW permanent public URL; returns the created drop (with its `drop_…` id).
      * Use to publish / share / post / put online / make public a report, dashboard, site, or file.
@@ -634,6 +638,12 @@ declare class DropsResource<TInput = PublishInput> {
      *
      * Mount target: `options.domain` accepts a connected custom hostname, or `SHARED_POOL`
      * (`"shared"`) to publish to the shared pool even when the account has a default domain.
+     *
+     * Two URLs come back on the response: `url` is the canonical, **always-branded** human
+     * view (badge guaranteed, no client detection); `rawUrl` is the drop's exact bytes at
+     * their natural path — hand it to other agents. `rawUrl` is populated only for single
+     * non-HTML files (`renderMode: "file_viewer"`) and is `null` for HTML drops and
+     * collections. To stream bytes through the SDK for any drop kind, use {@link getContent}.
      */
     publish(input: TInput, options?: PublishOptions): Promise<DropthisResult<DropResponse>>;
     /**
@@ -653,15 +663,17 @@ declare class DropsResource<TInput = PublishInput> {
     /** Fetch one drop by its `drop_…` id (not the slug/URL). GET /drops/{id}. */
     get(dropId: string): Promise<DropthisResult<DropResponse>>;
     /**
-     * Resolve a drop URL (or bare slug) back to the drop — the way to recover a lost
-     * `drop_…` id. The slug is parsed client-side from the first hostname label of a
-     * dropthis-attributable hostname (`https://<slug>.dropthis.app/…`, or `<slug>.` +
-     * the configured baseUrl's host), then matched owner-scoped via GET /drops?slug=.
-     * Returns the drop, or `data: null` when no drop of yours has that slug.
-     * Custom-domain URLs are rejected client-side with `invalid_drop_url` — they are
-     * not resolvable yet.
+     * Resolve a public locator (a drop URL, a custom-domain URL, or a bare vanity/shared
+     * slug) back to the drop — the way to recover a lost `drop_…` id. Sends the raw target
+     * to the server (POST /drops/resolve), which owner-scopes and decomposes it. Returns the
+     * full drop, or `data: null` when nothing of yours matches. A `drop_…` id passed as the
+     * target round-trips to an owner-scoped id lookup (null instead of 404).
+     *
+     * Persist the drop_… id. URLs, raw_url, and slugs are locators, not identifiers — a vanity
+     * slug is renameable and the pool host rotates, so a stored URL can drift; the id never
+     * moves. Treat drop_… as an opaque case-sensitive string.
      */
-    resolve(urlOrSlug: string): Promise<DropthisResult<DropResponse | null>>;
+    resolve(target: string): Promise<DropthisResult<DropResponse | null>>;
     /**
      * Read back what a drop is serving (owner-only; works regardless of any viewer
      * password). By default returns the JSON manifest of the CURRENT deployment's files;

package/node_modules/@dropthis/node/dist/{drops-BtAGkA9A.d.ts → drops-DmTdQTnd.d.ts}

@@ -85,6 +85,17 @@ type DropResponse = {
     limitations: Limitations;
     /** Hostname of the custom domain this drop is mounted on; null for shared-pool drops. */
     domain: string | null;
+    /**
+     * Direct URL to the drop's raw bytes — the agent byte-fetch path. The canonical
+     * `url` always serves a branded human view (so the badge is guaranteed); `rawUrl`
+     * serves the underlying file's exact bytes at its natural path under the mount
+     * (ADR 0061). Populated only for single-file (`renderMode: "file_viewer"`) drops
+     * (= canonical URL + the entry filename); `null` for `user_html` drops (the page
+     * IS the artifact) and collections (per-file natural paths come from the manifest —
+     * see {@link DeploymentContentManifest}). Hand `url` to humans and `rawUrl` to agents.
+     * To stream bytes through the SDK regardless of drop kind, use `drops.getContent()`.
+     */
+    rawUrl: string | null;
 };
 type DropDeploymentResponse = {
     id: string;
@@ -617,14 +628,7 @@ declare class CursorPage<T> implements ListPage<T> {
 declare class DropsResource<TInput = PublishInput> {
     private readonly transport;
     private readonly resolveInput;
-    private parentHosts?;
     constructor(transport: Transport, resolveInput: PublishInputResolver<TInput>);
-    /**
-     * Hostnames the SDK can attribute to dropthis for slug parsing: the canonical
-     * viewer domain plus the configured baseUrl's host (covers staging/self-hosted
-     * setups where drops are served under the API's own domain).
-     */
-    private allowedParentHosts;
     /**
      * Publish content to a NEW permanent public URL; returns the created drop (with its `drop_…` id).
      * Use to publish / share / post / put online / make public a report, dashboard, site, or file.
@@ -634,6 +638,12 @@ declare class DropsResource<TInput = PublishInput> {
      *
      * Mount target: `options.domain` accepts a connected custom hostname, or `SHARED_POOL`
      * (`"shared"`) to publish to the shared pool even when the account has a default domain.
+     *
+     * Two URLs come back on the response: `url` is the canonical, **always-branded** human
+     * view (badge guaranteed, no client detection); `rawUrl` is the drop's exact bytes at
+     * their natural path — hand it to other agents. `rawUrl` is populated only for single
+     * non-HTML files (`renderMode: "file_viewer"`) and is `null` for HTML drops and
+     * collections. To stream bytes through the SDK for any drop kind, use {@link getContent}.
      */
     publish(input: TInput, options?: PublishOptions): Promise<DropthisResult<DropResponse>>;
     /**
@@ -653,15 +663,17 @@ declare class DropsResource<TInput = PublishInput> {
     /** Fetch one drop by its `drop_…` id (not the slug/URL). GET /drops/{id}. */
     get(dropId: string): Promise<DropthisResult<DropResponse>>;
     /**
-     * Resolve a drop URL (or bare slug) back to the drop — the way to recover a lost
-     * `drop_…` id. The slug is parsed client-side from the first hostname label of a
-     * dropthis-attributable hostname (`https://<slug>.dropthis.app/…`, or `<slug>.` +
-     * the configured baseUrl's host), then matched owner-scoped via GET /drops?slug=.
-     * Returns the drop, or `data: null` when no drop of yours has that slug.
-     * Custom-domain URLs are rejected client-side with `invalid_drop_url` — they are
-     * not resolvable yet.
+     * Resolve a public locator (a drop URL, a custom-domain URL, or a bare vanity/shared
+     * slug) back to the drop — the way to recover a lost `drop_…` id. Sends the raw target
+     * to the server (POST /drops/resolve), which owner-scopes and decomposes it. Returns the
+     * full drop, or `data: null` when nothing of yours matches. A `drop_…` id passed as the
+     * target round-trips to an owner-scoped id lookup (null instead of 404).
+     *
+     * Persist the drop_… id. URLs, raw_url, and slugs are locators, not identifiers — a vanity
+     * slug is renameable and the pool host rotates, so a stored URL can drift; the id never
+     * moves. Treat drop_… as an opaque case-sensitive string.
      */
-    resolve(urlOrSlug: string): Promise<DropthisResult<DropResponse | null>>;
+    resolve(target: string): Promise<DropthisResult<DropResponse | null>>;
     /**
      * Read back what a drop is serving (owner-only; works regardless of any viewer
      * password). By default returns the JSON manifest of the CURRENT deployment's files;

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

@@ -604,23 +604,6 @@ var DropsResource = class {
   }
   transport;
   resolveInput;
-  parentHosts;
-  /**
-   * Hostnames the SDK can attribute to dropthis for slug parsing: the canonical
-   * viewer domain plus the configured baseUrl's host (covers staging/self-hosted
-   * setups where drops are served under the API's own domain).
-   */
-  allowedParentHosts() {
-    if (!this.parentHosts) {
-      const hosts = /* @__PURE__ */ new Set([CANONICAL_VIEWER_HOST]);
-      try {
-        hosts.add(new URL(this.transport.baseUrl).hostname.replace(/\.$/, ""));
-      } catch {
-      }
-      this.parentHosts = hosts;
-    }
-    return this.parentHosts;
-  }
   /**
    * Publish content to a NEW permanent public URL; returns the created drop (with its `drop_…` id).
    * Use to publish / share / post / put online / make public a report, dashboard, site, or file.
@@ -630,6 +613,12 @@ var DropsResource = class {
    *
    * Mount target: `options.domain` accepts a connected custom hostname, or `SHARED_POOL`
    * (`"shared"`) to publish to the shared pool even when the account has a default domain.
+   *
+   * Two URLs come back on the response: `url` is the canonical, **always-branded** human
+   * view (badge guaranteed, no client detection); `rawUrl` is the drop's exact bytes at
+   * their natural path — hand it to other agents. `rawUrl` is populated only for single
+   * non-HTML files (`renderMode: "file_viewer"`) and is `null` for HTML drops and
+   * collections. To stream bytes through the SDK for any drop kind, use {@link getContent}.
    */
   async publish(input, options = {}) {
     let prepared;
@@ -684,31 +673,25 @@ var DropsResource = class {
     );
   }
   /**
-   * Resolve a drop URL (or bare slug) back to the drop — the way to recover a lost
-   * `drop_…` id. The slug is parsed client-side from the first hostname label of a
-   * dropthis-attributable hostname (`https://<slug>.dropthis.app/…`, or `<slug>.` +
-   * the configured baseUrl's host), then matched owner-scoped via GET /drops?slug=.
-   * Returns the drop, or `data: null` when no drop of yours has that slug.
-   * Custom-domain URLs are rejected client-side with `invalid_drop_url` — they are
-   * not resolvable yet.
+   * Resolve a public locator (a drop URL, a custom-domain URL, or a bare vanity/shared
+   * slug) back to the drop — the way to recover a lost `drop_…` id. Sends the raw target
+   * to the server (POST /drops/resolve), which owner-scopes and decomposes it. Returns the
+   * full drop, or `data: null` when nothing of yours matches. A `drop_…` id passed as the
+   * target round-trips to an owner-scoped id lookup (null instead of 404).
+   *
+   * Persist the drop_… id. URLs, raw_url, and slugs are locators, not identifiers — a vanity
+   * slug is renameable and the pool host rotates, so a stored URL can drift; the id never
+   * moves. Treat drop_… as an opaque case-sensitive string.
    */
-  async resolve(urlOrSlug) {
-    const slug = parseSlug(urlOrSlug, this.allowedParentHosts());
-    if (slug === null) {
-      return createErrorResult(
-        "invalid_drop_url",
-        `Could not resolve a drop slug from "${urlOrSlug}". Pass a canonical drop URL like https://<slug>.dropthis.app/ or the bare slug \u2014 custom-domain URLs cannot be resolved yet.`,
-        null
-      );
-    }
-    const result = await this.transport.request("GET", "/drops", { params: { slug } });
+  async resolve(target) {
+    const result = await this.transport.request(
+      "POST",
+      "/drops/resolve",
+      { body: { target } }
+    );
     if (result.error)
       return { data: null, error: result.error, headers: result.headers };
-    return {
-      data: result.data.drops[0] ?? null,
-      error: null,
-      headers: result.headers
-    };
+    return { data: result.data.data, error: null, headers: result.headers };
   }
   async getContent(dropId, options = {}) {
     const base = options.deploymentId !== void 0 ? `/drops/${encodeURIComponent(dropId)}/deployments/${encodeURIComponent(options.deploymentId)}/content` : `/drops/${encodeURIComponent(dropId)}/content`;
@@ -767,25 +750,6 @@ var DropsResource = class {
     );
   }
 };
-var CANONICAL_VIEWER_HOST = "dropthis.app";
-function parseSlug(input, allowedParents) {
-  const value = input.trim();
-  if (!value) return null;
-  if (!/[./]/.test(value)) return value;
-  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `https://${value}`;
-  let hostname;
-  try {
-    hostname = new URL(withScheme).hostname;
-  } catch {
-    return null;
-  }
-  hostname = hostname.replace(/\.$/, "");
-  const dot = hostname.indexOf(".");
-  if (dot <= 0) return null;
-  const slug = hostname.slice(0, dot);
-  const parent = hostname.slice(dot + 1);
-  return allowedParents.has(parent) ? slug : null;
-}
 var SETTINGS = [
   "title",
   "visibility",
@@ -840,7 +804,7 @@ function toSnakeCase(value) {
 
 // src/transport.ts
 var DEFAULT_BASE_URL = "https://api.dropthis.app";
-var SDK_VERSION = "0.15.0";
+var SDK_VERSION = "0.17.0";
 var Transport = class {
   apiKey;
   baseUrl;