clefbase 1.3.4 → 1.3.6

package/dist/hosting/index.js

@@ -42,6 +42,7 @@ exports.ClefbaseHosting = exports.SiteReference = void 0;
  * const site = hosting.site("my-site-id");
  * const result = await site.deployFiles({ "index.html": htmlBuffer, "app.js": jsBuffer });
  * console.log(`Live at ${result.url}`);
+ * console.log(`Preview at ${result.previewUrl}`);
  */
 class SiteReference {
     constructor(hosting, siteId) {
@@ -74,13 +75,29 @@ class SiteReference {
      *   message: "v1.2.0",
      *   onProgress: (done, total) => console.log(`${done}/${total}`),
      * });
+     * console.log(`Live at ${result.url}`);
      */
     async deployFiles(files, opts) {
         return this.hosting._deployFiles(this.siteId, files, opts);
     }
-    /** The public URL for this site. */
+    /** Check the DNS status of this site's preview + custom domains. */
+    async getDnsStatus() {
+        return this.hosting._getDnsStatus(this.siteId);
+    }
+    /** Re-provision the preview DNS record (e.g. if it was accidentally deleted). */
+    async reprovisionDns() {
+        return this.hosting._reprovisionDns(this.siteId);
+    }
+    /** The preview URL for this site ({slug}.preview.cleforyx.com). */
+    get previewUrl() {
+        return this.hosting._previewUrl(this.siteId);
+    }
+    /**
+     * The public URL — custom domain if configured, else preview subdomain.
+     * Requires the site metadata; use `(await site.get())?.customDomain` to check.
+     */
     get url() {
-        return this.hosting._siteUrl(this.siteId);
+        return this.previewUrl; // SDK doesn't cache site; use DeployResult.url for canonical
     }
 }
 exports.SiteReference = SiteReference;
@@ -90,7 +107,12 @@ exports.SiteReference = SiteReference;
  *
  * @example
  * const hosting = getHosting(app);
+ *
+ * // Create a site — automatically provisions {name}.preview.cleforyx.com
  * const site = await hosting.createSite("my-app");
+ * console.log(site.previewUrl); // https://my-app.preview.cleforyx.com
+ *
+ * // Deploy files
  * const result = await hosting.site(site.id).deployFiles(files);
  * console.log(result.url);
  */
@@ -104,24 +126,45 @@ class ClefbaseHosting {
     async listSites() {
         return this.http.get(`/databases/${this.dbId}/sites`);
     }
-    /** Create a new hosted site. */
+    /**
+     * Create a new hosted site.
+     *
+     * Site names must be globally unique across the platform.
+     * A CNAME record will be automatically provisioned on Cloudflare:
+     *   {slug}.preview.cleforyx.com → cleforyx.com
+     *
+     * Throws a 409 ConflictError if the name is already taken.
+     */
     async createSite(name, description) {
         return this.http.post(`/databases/${this.dbId}/sites`, { name, description });
     }
-    /** Update site metadata. */
+    /** Update site metadata. Handles DNS rename if name changes. */
     async updateSite(siteId, patch) {
         return this.http.patch(`/databases/${this.dbId}/sites/${siteId}`, patch);
     }
-    /** Delete a site and all its deploys permanently. */
-    async deleteSite(siteId) {
-        await this.http.delete(`/databases/${this.dbId}/sites/${siteId}`);
+    /**
+     * Begin site deletion flow.
+     *
+     * Pass `confirm: false` (or omit) to get a confirmation prompt with DNS info.
+     * Pass `confirm: true` to actually delete. Include `deleteDns: true` to also
+     * remove the Cloudflare DNS record.
+     */
+    async deleteSite(siteId, opts) {
+        const params = new URLSearchParams();
+        if (opts?.confirm)
+            params.set("confirm", "true");
+        if (opts?.deleteDns)
+            params.set("deleteDns", "true");
+        const qs = params.toString() ? `?${params}` : "";
+        return this.http.delete(`/databases/${this.dbId}/sites/${siteId}${qs}`);
     }
     /** Return a SiteReference for a specific site ID. */
     site(siteId) {
         return new SiteReference(this, siteId);
     }
     // ─── Internals ─────────────────────────────────────────────────────────────
-    _siteUrl(siteId) {
+    _previewUrl(siteId) {
+        // Falls back to server URL path if site metadata isn't cached
         return `${this.serverUrl.replace(/\/+$/, "")}/hosted/${this.dbId}/${siteId}`;
     }
     async _getSite(siteId) {
@@ -148,28 +191,35 @@ class ClefbaseHosting {
     async _listDeploys(siteId) {
         return this.http.get(`/databases/${this.dbId}/sites/${siteId}/deploys`);
     }
+    async _getDnsStatus(siteId) {
+        return this.http.get(`/databases/${this.dbId}/sites/${siteId}/dns`);
+    }
+    async _reprovisionDns(siteId) {
+        return this.http.post(`/databases/${this.dbId}/sites/${siteId}/dns/provision`, {});
+    }
     async _deployFiles(siteId, files, opts = {}) {
         const { entrypoint = "index.html", deployedBy, message, batchSize = 20, onProgress } = opts;
         // 1. Create pending deploy
         const pending = await this.http.post(`/databases/${this.dbId}/sites/${siteId}/deploys`, { deployedBy, entrypoint });
+        // 2. Get site for canonical URL
+        const siteData = await this._getSite(siteId).catch(() => null);
         const filePaths = Object.keys(files);
         const fileBuffers = Object.values(files);
         const errors = [];
         let uploaded = 0;
-        // 2. Detect whether we have native FormData (Node 18+) or need form-data pkg
+        // 3. Detect whether we have native FormData (Node 18+) or need form-data pkg
         const hasNativeFormData = typeof FormData !== "undefined";
         let FormDataLegacy;
         if (!hasNativeFormData) {
             const mod = await Promise.resolve().then(() => __importStar(require("form-data")));
             FormDataLegacy = mod.default;
         }
-        // 3. Upload in batches
+        // 4. Upload in batches
         for (let i = 0; i < filePaths.length; i += batchSize) {
             const batchPaths = filePaths.slice(i, i + batchSize);
             const batchBuffers = fileBuffers.slice(i, i + batchSize);
             try {
                 if (hasNativeFormData) {
-                    // Node 18+ native FormData: Buffers must be wrapped in Blob/File
                     const form = new FormData();
                     for (let j = 0; j < batchPaths.length; j++) {
                         const filename = batchPaths[j].split("/").pop() ?? batchPaths[j];
@@ -182,7 +232,6 @@ class ClefbaseHosting {
                     await this.http.request(`/databases/${this.dbId}/deploys/${pending.id}/files/batch`, { method: "POST", body: form, isFormData: true });
                 }
                 else {
-                    // Older Node: form-data package accepts Buffers natively
                     const form = new FormDataLegacy();
                     for (let j = 0; j < batchPaths.length; j++) {
                         form.append("files[]", batchBuffers[j], {
@@ -200,13 +249,17 @@ class ClefbaseHosting {
             }
             onProgress?.(Math.min(i + batchSize, filePaths.length), filePaths.length);
         }
-        // 4. Finalize → go live
+        // 5. Finalize → go live
         const live = await this.http.post(`/databases/${this.dbId}/deploys/${pending.id}/finalize`, { message: message ?? "Deployed via clefbase SDK" });
+        const canonicalUrl = siteData?.customDomain
+            ? `https://${siteData.customDomain}`
+            : siteData?.previewUrl ?? this._previewUrl(siteId);
         return {
             deploy: live,
             filesUploaded: uploaded,
             errors,
-            url: this._siteUrl(siteId),
+            url: canonicalUrl,
+            previewUrl: siteData?.previewUrl ?? this._previewUrl(siteId),
         };
     }
 }

package/dist/hosting/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hosting/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hosting/index.ts"],"names":[],"mappings":"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"}

package/dist/react/StorageImage.d.ts

@@ -2,75 +2,24 @@ import React, { type ImgHTMLAttributes } from "react";
 import type { ClefbaseStorage } from "../storage";
 export type StorageImageStatus = "loading" | "loaded" | "error";
 export interface StorageImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src"> {
-    /**
-     * The ClefbaseStorage instance returned by `getStorage(app)`.
-     */
     storage: ClefbaseStorage;
-    /**
-     * Path inside the default bucket, e.g. `"avatars/user-123.jpg"`.
-     * Mutually exclusive with `bucket` + `path`.
-     */
+    /** Path inside the default bucket, e.g. "avatars/user-123.jpg". */
     src?: string;
-    /**
-     * Named bucket to read from. Pair with `path`.
-     */
+    /** Named bucket to read from. Pair with `path`. */
     bucket?: string;
-    /**
-     * File path inside `bucket`.
-     */
+    /** File path inside `bucket`. */
     path?: string;
-    /**
-     * Shown while the download URL is being resolved.
-     * Accepts a URL string or any React node.
-     */
+    /** Shown while the download URL is being resolved. */
     placeholder?: React.ReactNode | string;
-    /**
-     * Shown when the URL cannot be resolved or the image fails to load.
-     * Accepts a URL string or any React node.
-     */
+    /** Shown when the URL cannot be resolved or the image fails to load. */
     fallback?: React.ReactNode | string;
-    /**
-     * Called with the resolved download URL once ready.
-     */
     onResolve?: (url: string) => void;
-    /**
-     * Called if URL resolution or image loading fails.
-     */
     onError?: (err: unknown) => void;
-    /**
-     * Called whenever the loading status changes.
-     */
     onStatusChange?: (status: StorageImageStatus) => void;
 }
 /**
- * A drop-in replacement for `<img>` that resolves Clefbase storage paths to
- * authenticated download URLs automatically.
- *
- * @example — default bucket
- * ```tsx
- * const storage = getStorage(app);
- *
- * <StorageImage
- *   storage={storage}
- *   src="avatars/user-123.jpg"
- *   alt="User avatar"
- *   width={64}
- *   height={64}
- *   style={{ borderRadius: "50%" }}
- * />
- * ```
- *
- * @example — named bucket
- * ```tsx
- * <StorageImage
- *   storage={storage}
- *   bucket="media"
- *   path="products/shoe.webp"
- *   alt="Product photo"
- *   placeholder={<Spinner />}
- *   fallback={<img src="/no-image.svg" alt="Not found" />}
- * />
- * ```
+ * Drop-in <img> replacement that resolves Clefbase storage paths to
+ * authenticated download URLs via /storage/resolve.
  */
 export declare const StorageImage: React.ForwardRefExoticComponent<StorageImageProps & React.RefAttributes<HTMLImageElement>>;
 export default StorageImage;

package/dist/react/StorageImage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageImage.d.ts","sourceRoot":"","sources":["../../src/react/StorageImage.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAKZ,KAAK,iBAAiB,EACvB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE,MAAM,WAAW,iBACf,SAAQ,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,EAAE,KAAK,CAAC;IACxD;;OAEG;IACH,OAAO,EAAE,eAAe,CAAC;IAEzB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC;IAEpC;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAElC;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IAEjC;;OAEG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACvD;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,YAAY,4FAuKxB,CAAC;AAIF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"StorageImage.d.ts","sourceRoot":"","sources":["../../src/react/StorageImage.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAKZ,KAAK,iBAAiB,EACvB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE,MAAM,WAAW,iBACf,SAAQ,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,EAAE,KAAK,CAAC;IACxD,OAAO,EAAE,eAAe,CAAC;IACzB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC;IACvC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC;IACpC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACvD;AAID;;;GAGG;AACH,eAAO,MAAM,YAAY,4FAoIxB,CAAC;AAGF,eAAe,YAAY,CAAC"}

package/dist/react/StorageImage.js

@@ -5,70 +5,20 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 // ─── StorageImage ─────────────────────────────────────────────────────────────
 /**
- * A drop-in replacement for `<img>` that resolves Clefbase storage paths to
- * authenticated download URLs automatically.
- *
- * @example — default bucket
- * ```tsx
- * const storage = getStorage(app);
- *
- * <StorageImage
- *   storage={storage}
- *   src="avatars/user-123.jpg"
- *   alt="User avatar"
- *   width={64}
- *   height={64}
- *   style={{ borderRadius: "50%" }}
- * />
- * ```
- *
- * @example — named bucket
- * ```tsx
- * <StorageImage
- *   storage={storage}
- *   bucket="media"
- *   path="products/shoe.webp"
- *   alt="Product photo"
- *   placeholder={<Spinner />}
- *   fallback={<img src="/no-image.svg" alt="Not found" />}
- * />
- * ```
+ * Drop-in <img> replacement that resolves Clefbase storage paths to
+ * authenticated download URLs via /storage/resolve.
  */
 exports.StorageImage = (0, react_1.forwardRef)(function StorageImage({ storage, src, bucket, path, placeholder, fallback, onResolve, onError, onStatusChange, alt = "", ...imgProps }, ref) {
-    // Resolve the URL synchronously where possible (_directUrl is pure/sync)
-    // to avoid an async waterfall that exhausts the browser's per-host
-    // connection pool (typically 6 connections) when many cards mount at once.
-    const getDirectUrl = () => {
-        try {
-            if (bucket && path)
-                return storage._directUrl(bucket, path);
-            if (src)
-                return storage._directUrl(storage["_defaultBucket"] ?? "default", src);
-            return null;
-        }
-        catch {
-            return null;
-        }
-    };
-    const initialUrl = getDirectUrl();
-    const [resolvedUrl, setResolvedUrl] = (0, react_1.useState)(initialUrl);
-    const [status, setStatus] = (0, react_1.useState)(initialUrl ? "loaded" : "loading");
-    // Keep a ref to the latest callbacks so the effect closure stays stable.
+    const [resolvedUrl, setResolvedUrl] = (0, react_1.useState)(null);
+    const [status, setStatus] = (0, react_1.useState)("loading");
     const onResolveRef = (0, react_1.useRef)(onResolve);
     const onErrorRef = (0, react_1.useRef)(onError);
     const onStatusRef = (0, react_1.useRef)(onStatusChange);
     onResolveRef.current = onResolve;
     onErrorRef.current = onError;
     onStatusRef.current = onStatusChange;
-    // Determine the key that uniquely identifies the requested file.
     const fileKey = bucket && path ? `${bucket}::${path}` : src ?? null;
     (0, react_1.useEffect)(() => {
-        // If we already resolved synchronously, notify callers and skip the
-        // async effect entirely — no extra network round-trip needed.
-        if (initialUrl) {
-            onResolveRef.current?.(initialUrl);
-            return;
-        }
         if (!fileKey)
             return;
         let cancelled = false;
@@ -78,9 +28,7 @@ exports.StorageImage = (0, react_1.forwardRef)(function StorageImage({ storage,
             try {
                 let url;
                 if (bucket && path) {
-                    url = storage.bucket(bucket).ref(path).getDownloadURL
-                        ? await storage.bucket(bucket).ref(path).getDownloadURL()
-                        : storage._directUrl(bucket, path);
+                    url = await storage.bucket(bucket).ref(path).getDownloadURL();
                 }
                 else if (src) {
                     url = await storage.ref(src).getDownloadURL();
@@ -90,9 +38,11 @@ exports.StorageImage = (0, react_1.forwardRef)(function StorageImage({ storage,
                 }
                 if (cancelled)
                     return;
+                if (!url)
+                    throw new Error("StorageImage: empty download URL returned.");
                 setResolvedUrl(url);
                 onResolveRef.current?.(url);
-                // status moves to "loaded" in the <img> onLoad handler below
+                // status → "loaded" fires in the <img> onLoad handler
             }
             catch (err) {
                 if (cancelled)
@@ -103,9 +53,7 @@ exports.StorageImage = (0, react_1.forwardRef)(function StorageImage({ storage,
             }
         };
         resolve();
-        return () => {
-            cancelled = true;
-        };
+        return () => { cancelled = true; };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [fileKey]);
     // ── Render helpers ────────────────────────────────────────────────────────
@@ -118,18 +66,17 @@ exports.StorageImage = (0, react_1.forwardRef)(function StorageImage({ storage,
         onStatusRef.current?.("error");
         onErrorRef.current?.(e);
     };
-    // Show placeholder while resolving URL
+    // Placeholder while resolving
     if (status === "loading" && !resolvedUrl) {
         if (placeholder === undefined) {
-            // Invisible img keeps layout stable
             return ((0, jsx_runtime_1.jsx)("img", { ...imgProps, ref: ref, src: "", alt: alt, style: { ...imgProps.style, visibility: "hidden" } }));
         }
         if (typeof placeholder === "string") {
-            return ((0, jsx_runtime_1.jsx)("img", { ...imgProps, ref: ref, src: placeholder, alt: alt }));
+            return (0, jsx_runtime_1.jsx)("img", { ...imgProps, ref: ref, src: placeholder, alt: alt });
         }
         return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: placeholder });
     }
-    // Show fallback on error
+    // Fallback on error
     if (status === "error" || !resolvedUrl) {
         if (fallback === undefined) {
             return ((0, jsx_runtime_1.jsx)("img", { ...imgProps, ref: ref, src: "", alt: alt, style: { ...imgProps.style, visibility: "hidden" } }));
@@ -139,10 +86,6 @@ exports.StorageImage = (0, react_1.forwardRef)(function StorageImage({ storage,
         }
         return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: fallback });
     }
-    // Resolved — render the real image.
-    // `loading="lazy"` defers off-screen fetches so the browser never
-    // saturates its per-host connection pool (typically 6) when many
-    // cards render simultaneously. Callers may override with loading="eager".
     return ((0, jsx_runtime_1.jsx)("img", { loading: "lazy", ...imgProps, ref: ref, src: resolvedUrl, alt: alt, onLoad: handleLoad, onError: handleImgError }));
 });
 exports.StorageImage.displayName = "StorageImage";

package/dist/react/StorageImage.js.map

@@ -1 +1 @@
-{"version":3,"file":"StorageImage.js","sourceRoot":"","sources":["../../src/react/StorageImage.tsx"],"names":[],"mappings":";;;;AAAA,iCAMe;AA0Df,iFAAiF;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACU,QAAA,YAAY,GAAG,IAAA,kBAAU,EACpC,SAAS,YAAY,CACnB,EACE,OAAO,EACP,GAAG,EACH,MAAM,EACN,IAAI,EACJ,WAAW,EACX,QAAQ,EACR,SAAS,EACT,OAAO,EACP,cAAc,EACd,GAAG,GAAG,EAAE,EACR,GAAG,QAAQ,EACZ,EACD,GAAG;IAEH,yEAAyE;IACzE,mEAAmE;IACnE,2EAA2E;IAC3E,MAAM,YAAY,GAAG,GAAkB,EAAE;QACvC,IAAI,CAAC;YACH,IAAI,MAAM,IAAI,IAAI;gBAAE,OAAO,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YAC5D,IAAI,GAAG;gBAAa,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,SAAS,EAAE,GAAG,CAAC,CAAC;YAC3F,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,UAAU,GAAG,YAAY,EAAE,CAAC;IAElC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,IAAA,gBAAQ,EAAgB,UAAU,CAAC,CAAC;IAC1E,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,IAAA,gBAAQ,EAClC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAClC,CAAC;IAEF,yEAAyE;IACzE,MAAM,YAAY,GAAG,IAAA,cAAM,EAAC,SAAS,CAAC,CAAC;IACvC,MAAM,UAAU,GAAK,IAAA,cAAM,EAAC,OAAO,CAAC,CAAC;IACrC,MAAM,WAAW,GAAI,IAAA,cAAM,EAAC,cAAc,CAAC,CAAC;IAC5C,YAAY,CAAC,OAAO,GAAI,SAAS,CAAC;IAClC,UAAU,CAAC,OAAO,GAAM,OAAO,CAAC;IAChC,WAAW,CAAC,OAAO,GAAK,cAAc,CAAC;IAEvC,iEAAiE;IACjE,MAAM,OAAO,GAAG,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC;IAEpE,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,oEAAoE;QACpE,8DAA8D;QAC9D,IAAI,UAAU,EAAE,CAAC;YACf,YAAY,CAAC,OAAO,EAAE,CAAC,UAAU,CAAC,CAAC;YACnC,OAAO;QACT,CAAC;QAED,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,IAAI,SAAS,GAAG,KAAK,CAAC;QAEtB,SAAS,CAAC,SAAS,CAAC,CAAC;QACrB,WAAW,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;QAEjC,MAAM,OAAO,GAAG,KAAK,IAAI,EAAE;YACzB,IAAI,CAAC;gBACH,IAAI,GAAW,CAAC;gBAEhB,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;oBACnB,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,cAAc;wBACnD,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE;wBACzD,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBACvC,CAAC;qBAAM,IAAI,GAAG,EAAE,CAAC;oBACf,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,cAAc,EAAE,CAAC;gBAChD,CAAC;qBAAM,CAAC;oBACN,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;gBACnF,CAAC;gBAED,IAAI,SAAS;oBAAE,OAAO;gBACtB,cAAc,CAAC,GAAG,CAAC,CAAC;gBACpB,YAAY,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;gBAC5B,6DAA6D;YAC/D,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,SAAS;oBAAE,OAAO;gBACtB,SAAS,CAAC,OAAO,CAAC,CAAC;gBACnB,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;gBAC/B,UAAU,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC,CAAC;QAEF,OAAO,EAAE,CAAC;QAEV,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC;QACF,uDAAuD;IACzD,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAEd,6EAA6E;IAE7E,MAAM,UAAU,GAAG,GAAG,EAAE;QACtB,SAAS,CAAC,QAAQ,CAAC,CAAC;QACpB,WAAW,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC,CAAC;IAEF,MAAM,cAAc,GAAG,CAAC,CAAyC,EAAE,EAAE;QACnE,SAAS,CAAC,OAAO,CAAC,CAAC;QACnB,WAAW,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;QAC/B,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC,CAAC;IAEF,uCAAuC;IACvC,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,WAAW,EAAE,CAAC;QACzC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;YAC9B,oCAAoC;YACpC,OAAO,CACL,mCACM,QAAQ,EACZ,GAAG,EAAE,GAAG,EACR,GAAG,EAAC,EAAE,EACN,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,GAClD,CACH,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;YACpC,OAAO,CACL,mCAAS,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,GAAI,CAC5D,CAAC;QACJ,CAAC;QACD,OAAO,2DAAG,WAAW,GAAI,CAAC;IAC5B,CAAC;IAED,yBAAyB;IACzB,IAAI,MAAM,KAAK,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,CACL,mCACM,QAAQ,EACZ,GAAG,EAAE,GAAG,EACR,GAAG,EAAC,EAAE,EACN,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,EAAE,GAAG,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,GAClD,CACH,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjC,OAAO,mCAAS,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,GAAI,CAAC;QAClE,CAAC;QACD,OAAO,2DAAG,QAAQ,GAAI,CAAC;IACzB,CAAC;IAED,oCAAoC;IACpC,kEAAkE;IAClE,iEAAiE;IACjE,0EAA0E;IAC1E,OAAO,CACL,gCACE,OAAO,EAAC,MAAM,KACV,QAAQ,EACZ,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,WAAW,EAChB,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,cAAc,GACvB,CACH,CAAC;AACJ,CAAC,CACF,CAAC;AAEF,oBAAY,CAAC,WAAW,GAAG,cAAc,CAAC;AAE1C,kBAAe,oBAAY,CAAC"}
+{"version":3,"file":"StorageImage.js","sourceRoot":"","sources":["../../src/react/StorageImage.tsx"],"names":[],"mappings":"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"}

package/dist/storage/index.d.ts

@@ -22,6 +22,10 @@ export declare class StorageReference {
         contentType?: string;
         metadata?: Record<string, unknown>;
     }): Promise<StorageFile>;
+    /**
+     * Returns the authenticated download URL for this file.
+     * Always resolves via /storage/resolve to get the real bucketId + fileId.
+     */
     getDownloadURL(): Promise<string>;
     getMetadata(): Promise<StorageFile>;
     delete(): Promise<void>;
@@ -40,18 +44,32 @@ export declare class ClefbaseStorage {
     private readonly http;
     private readonly projectId;
     private readonly auth;
-    /** @internal exposed so StorageImage can build URLs synchronously */
+    /** @internal used by StorageImage — kept for compat but now returns empty string (no /path route exists) */
     _defaultBucket: string;
     /** In-memory cache: bucket name → UUID */
     private _bucketIdCache;
+    /** In-memory cache: "bucket::filePath" → download URL */
+    private _urlCache;
     constructor(http: HttpClient, projectId: string, auth?: Auth | null);
     private authHeaders;
     setDefaultBucket(name: string): this;
     bucket(name: string): BucketReference;
     ref(filePath: string): StorageReference;
     _resolveBucketId(bucketName: string): Promise<string>;
-    /** Synchronous direct URL — used by StorageImage to avoid a waterfall. */
-    _directUrl(bucket: string, filePath: string): string;
+    /**
+     * Resolves a storage path to an authenticated download URL via
+     * GET /storage/resolve?projectId=xxx&path=bucketName/folder/file.jpg
+     *
+     * The server returns { downloadUrl, id, bucketId, ... } — we use downloadUrl directly.
+     * Results are cached so repeated calls (e.g. many cards) only hit the server once per path.
+     */
+    _getDownloadURL(bucket: string, filePath: string): Promise<string>;
+    /**
+     * @deprecated No /path route exists on the server.
+     * Kept so StorageImage's synchronous fast-path gracefully returns ""
+     * (which makes StorageImage fall through to the async resolve path).
+     */
+    _directUrl(_bucket: string, _filePath: string): string;
     _resolve(bucket: string, filePath: string): Promise<StorageFile>;
     _upload(bucket: string, filePath: string, data: Buffer | Blob | File, opts?: {
         contentType?: string;

package/dist/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"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"}

package/dist/storage/index.js

@@ -44,8 +44,12 @@ class StorageReference {
     async upload(data, opts) {
         return this.storage._upload(this.bucket, this.filePath, data, opts);
     }
+    /**
+     * Returns the authenticated download URL for this file.
+     * Always resolves via /storage/resolve to get the real bucketId + fileId.
+     */
     async getDownloadURL() {
-        return this.storage._directUrl(this.bucket, this.filePath);
+        return this.storage._getDownloadURL(this.bucket, this.filePath);
     }
     async getMetadata() {
         return this.storage._resolve(this.bucket, this.filePath);
@@ -75,10 +79,12 @@ class ClefbaseStorage {
         this.http = http;
         this.projectId = projectId;
         this.auth = auth;
-        /** @internal exposed so StorageImage can build URLs synchronously */
+        /** @internal used by StorageImage — kept for compat but now returns empty string (no /path route exists) */
         this._defaultBucket = "default";
         /** In-memory cache: bucket name → UUID */
         this._bucketIdCache = new Map();
+        /** In-memory cache: "bucket::filePath" → download URL */
+        this._urlCache = new Map();
     }
     authHeaders() {
         return this.auth?.getAuthHeaders() ?? {};
@@ -94,10 +100,6 @@ class ClefbaseStorage {
         return new StorageReference(this, this._defaultBucket, filePath.replace(/^\/+/, ""));
     }
     // ─── Bucket UUID resolution ───────────────────────────────────────────────
-    //
-    // The external storage router identifies buckets by UUID, not by name.
-    // dbId comes from the API key (set by dbApiKeyMiddleware), so we just call
-    // GET /buckets (no projectId needed — the key carries that context).
     async _resolveBucketId(bucketName) {
         const cached = this._bucketIdCache.get(bucketName);
         if (cached)
@@ -111,19 +113,43 @@ class ClefbaseStorage {
             throw new Error(`Storage bucket "${bucketName}" not found`);
         return id;
     }
-    // ─── Internal methods called by StorageReference ──────────────────────────
-    /** Synchronous direct URL — used by StorageImage to avoid a waterfall. */
-    _directUrl(bucket, filePath) {
+    // ─── Download URL ─────────────────────────────────────────────────────────
+    /**
+     * Resolves a storage path to an authenticated download URL via
+     * GET /storage/resolve?projectId=xxx&path=bucketName/folder/file.jpg
+     *
+     * The server returns { downloadUrl, id, bucketId, ... } — we use downloadUrl directly.
+     * Results are cached so repeated calls (e.g. many cards) only hit the server once per path.
+     */
+    async _getDownloadURL(bucket, filePath) {
         const cleanFile = filePath.replace(/^\/+/, "");
-        const base = this.http.getBaseUrl();
-        return `${base}/path/${cleanFile}?projectId=${encodeURIComponent(this.projectId)}&inline=true`;
+        // The resolve endpoint expects the full path including bucket name
+        const fullPath = `${bucket}/${cleanFile}`;
+        const cacheKey = fullPath;
+        const cached = this._urlCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const meta = await this._resolve(bucket, cleanFile);
+        const url = meta.downloadUrl ?? "";
+        if (url)
+            this._urlCache.set(cacheKey, url);
+        return url;
+    }
+    /**
+     * @deprecated No /path route exists on the server.
+     * Kept so StorageImage's synchronous fast-path gracefully returns ""
+     * (which makes StorageImage fall through to the async resolve path).
+     */
+    _directUrl(_bucket, _filePath) {
+        return "";
     }
     async _resolve(bucket, filePath) {
         const cleanFile = filePath.replace(/^\/+/, "");
-        return this.http.get(`/resolve?projectId=${encodeURIComponent(this.projectId)}&path=${cleanFile}`);
+        // The resolve endpoint matches by fullPath = "bucketName/folder/file.jpg"
+        const fullPath = `${bucket}/${cleanFile}`;
+        return this.http.get(`/resolve?projectId=${encodeURIComponent(this.projectId)}&path=${encodeURIComponent(fullPath)}`);
     }
     async _upload(bucket, filePath, data, opts) {
-        // Resolve bucket name → UUID before building the URL
         const bucketId = await this._resolveBucketId(bucket);
         let FormDataImpl;
         if (typeof FormData !== "undefined") {
@@ -148,6 +174,9 @@ class ClefbaseStorage {
             form.append("folder", folder);
         if (opts?.metadata)
             form.append("metadata", JSON.stringify(opts.metadata));
+        // Bust the URL cache for this path so a fresh URL is fetched after upload
+        const cacheKey = `${bucket}/${cleanPath}`;
+        this._urlCache.delete(cacheKey);
         return this.http.request(`/buckets/${bucketId}/files`, {
             method: "POST",
             body: form,
@@ -158,6 +187,7 @@ class ClefbaseStorage {
     async _delete(bucket, filePath) {
         const bucketId = await this._resolveBucketId(bucket);
         const meta = await this._resolve(bucket, filePath);
+        this._urlCache.delete(`${bucket}/${filePath.replace(/^\/+/, "")}`);
         await this.http.delete(`/buckets/${bucketId}/files/${meta.id}`, this.authHeaders());
     }
     async _list(bucket, prefix, opts) {