@nexushub/client 0.7.7 → 0.7.9

package/dist/index.cjs

@@ -936,7 +936,7 @@ var ContentEngine = class {
     });
     this.requestBatcher = new RequestBatcher(20, 50);
     this.circuitBreaker = new CircuitBreaker();
-    this.defaultRevalidate = config.revalidateTime || false;
+    this.defaultRevalidate = config.revalidateTime ?? false;
     this.cacheStrategy = config.cacheStrategy || "memory";
     if (!this.isServer) {
       window.addEventListener("beforeunload", this.cleanup.bind(this));
@@ -1140,9 +1140,16 @@ var ContentEngine = class {
       await this.rateLimiter.checkLimit();
       const url = `${this.config.apiUrl}/content/${this.config.projectId}/globals`;
       const params = include.length > 0 ? `?include=${include.join(",")}` : "";
+      const fetchTags = [
+        CacheTags.project(this.config.projectId),
+        CacheTags.global,
+        ...options.tags || []
+      ];
       const res = await this.fetchWithTimeout(`${url}${params}`, {
         method: "GET",
-        headers: this.getHeaders()
+        headers: this.getHeaders(),
+        tags: fetchTags,
+        revalidate
       });
       if (!res.ok) {
         throw new Error(`API Error ${res.status}: ${res.statusText}`);
@@ -1183,9 +1190,20 @@ var ContentEngine = class {
         params.append("include", options.include.join(","));
       }
       const url = `${this.config.apiUrl}/content/${this.config.projectId}/collection/${collectionId}/${itemId}?${params}`;
+      const fetchTags = [
+        CacheTags.project(this.config.projectId),
+        CacheTags.collection(collectionId),
+        `item_${itemId}`,
+        ...options.tags || []
+      ];
       const res = await this.fetchWithTimeout(url, {
         method: "GET",
-        headers: this.getHeaders()
+        headers: this.getHeaders(),
+        tags: fetchTags,
+        // ?? not || — see the constructor comment on defaultRevalidate for
+        // why: an explicit `revalidate: 0` on this call must not be
+        // discarded in favor of the engine's default.
+        revalidate: options.revalidate ?? this.defaultRevalidate
       });
       if (!res.ok) {
         throw new Error(`API Error ${res.status}: ${res.statusText}`);
@@ -1193,13 +1211,8 @@ var ContentEngine = class {
       const json = await res.json();
       const data = json.data || json;
       this.writeCache(cacheKey, data, {
-        revalidate: options.revalidate || this.defaultRevalidate,
-        tags: [
-          CacheTags.project(this.config.projectId),
-          CacheTags.collection(collectionId),
-          `item_${itemId}`,
-          ...options.tags || []
-        ]
+        revalidate: options.revalidate ?? this.defaultRevalidate,
+        tags: fetchTags
       });
       return data;
     });
@@ -1242,19 +1255,49 @@ var ContentEngine = class {
   }
   /**
    * Robust Real-time Subscriptions (SSE) with Auto-Reconnect
+   *
+   * ⚠️ SCOPE — READ BEFORE RELYING ON THIS FOR "instant" UPDATES:
+   * This connects from the BROWSER TAB it's called in, and on message it
+   * only clears THIS SDK INSTANCE's in-memory `memoryCache` (via
+   * invalidateCache below) in THAT browser tab's JS heap. In a typical
+   * Next.js deployment — and Cloudflare specifically, which is stateless
+   * per-request at the edge — that is a different process/isolate than the
+   * one that will render the NEXT server request for this content. So:
+   *   - ✅ Useful for: a client component that reads from `nexus.content`
+   *     directly in the browser and re-renders in place without a page
+   *     navigation (e.g. a live-updating dashboard widget).
+   *   - ❌ NOT sufficient for: "user A edits content in the CMS, user B's
+   *     already-loaded page updates" via a server-rendered page. That
+   *     requires the backend's /api/revalidate webhook (see
+   *     content.service.ts `pingNextRevalidateWebhook`) to have actually
+   *     cleared the *server's* Data Cache, so the NEXT navigation or
+   *     server request picks up fresh data. This SSE channel does not
+   *     replace that — it's a complementary, browser-local optimization.
+   * If your symptom was "stale content after editing," fix the webhook
+   * wiring first; treat this method as an enhancement layered on top.
    */
   subscribeToUpdates(callback) {
     if (this.isServer || typeof EventSource === "undefined") {
-      console.warn("[NexusHub] EventSource not supported in this environment");
+      if (this.config.debug) {
+        console.warn(
+          "[NexusHub] subscribeToUpdates() called in a non-browser environment (server render or SSR pass) \u2014 this is expected and safely skipped; EventSource only makes sense client-side."
+        );
+      }
       return () => {
       };
     }
+    if (!this.config.apiKey) {
+      console.warn(
+        "[NexusHub] subscribeToUpdates(): no apiKey configured, the SSE connection will likely be rejected by the backend. Set NEXT_PUBLIC_NEXUS_KEY."
+      );
+    }
     let eventSource = null;
     let retryCount = 0;
     let isClosed = false;
+    const MAX_RETRY_DELAY_MS = 3e4;
     const connect = () => {
       if (isClosed) return;
-      const url = `${this.config.apiUrl}/content/${this.config.projectId}/updates?key=${this.config.apiKey}`;
+      const url = `${this.config.apiUrl}/content/${this.config.projectId}/updates?key=${this.config.apiKey ?? ""}`;
       eventSource = new EventSource(url);
       eventSource.onopen = () => {
         retryCount = 0;
@@ -1262,27 +1305,40 @@ var ContentEngine = class {
           console.log("[NexusHub] \u{1F7E2} Real-time stream connected");
       };
       eventSource.onmessage = (event) => {
+        let data;
         try {
-          const data = JSON.parse(event.data);
-          if (data.type === "content.updated" && data.slug) {
-            this.invalidateCache([CacheTags.content(data.slug)]);
-          }
-          if (data.type === "collection.updated") {
-            this.invalidateCache([CacheTags.collection(data.collectionId)]);
-          }
-          callback(data);
+          data = JSON.parse(event.data);
         } catch (e) {
           console.error("[NexusHub] SSE Parse Error", e);
+          return;
+        }
+        if (!data || typeof data.type !== "string") {
+          return;
+        }
+        if (data.type === "content.updated" && data.slug) {
+          this.invalidateCache([CacheTags.content(data.slug)]);
+        }
+        if (data.type === "collection.updated" && data.collectionId) {
+          this.invalidateCache([CacheTags.collection(data.collectionId)]);
         }
+        if (data.type === "schema.updated") {
+          this.clearCache();
+        }
+        callback(data);
       };
       eventSource.onerror = () => {
         eventSource?.close();
         if (isClosed) return;
-        const timeout = Math.min(1e3 * Math.pow(2, retryCount), 1e4);
-        retryCount++;
-        console.warn(
-          `[NexusHub] \u{1F534} Stream disconnected. Reconnecting in ${timeout}ms...`
+        const timeout = Math.min(
+          1e3 * Math.pow(2, retryCount),
+          MAX_RETRY_DELAY_MS
         );
+        retryCount++;
+        if (this.config.debug) {
+          console.warn(
+            `[NexusHub] \u{1F534} Stream disconnected. Reconnecting in ${timeout}ms...`
+          );
+        }
         setTimeout(connect, timeout);
       };
     };
@@ -1293,9 +1349,6 @@ var ContentEngine = class {
     };
   }
   // --- CACHE MANAGEMENT ---
-  /**
-   * Check all caches in order of speed
-   */
   async checkCaches(key, forceRefresh, includeMetadata) {
     if (forceRefresh) return null;
     if (this.cacheStrategy === "memory") {
@@ -1352,9 +1405,6 @@ var ContentEngine = class {
       this.browserCache.set(key, data, numericRevalidate * 1e3);
     }
   }
-  /**
-   * Invalidate cache by tags
-   */
   invalidateCache(tags) {
     this.memoryCache.invalidateByTags(tags);
     if (this.config.debug) {
@@ -1363,9 +1413,6 @@ var ContentEngine = class {
       );
     }
   }
-  /**
-   * Clear all caches
-   */
   clearCache() {
     this.memoryCache.clear();
     if (this.browserCache) {
@@ -1375,9 +1422,6 @@ var ContentEngine = class {
       console.log("[NexusHub] \u{1F9F9} Cleared all caches");
     }
   }
-  /**
-   * Get cache statistics
-   */
   getCacheStats() {
     const stats = {
       memory: this.memoryCache.getStats(),
@@ -1391,14 +1435,16 @@ var ContentEngine = class {
   // --- REQUEST METHODS ---
   async fetchPage(slug, cacheKey, tags, revalidate, forceRefresh) {
     const url = `${this.config.apiUrl}/content/${this.config.projectId}/page/${slug}`;
-    if (this.config.debug) {
-      console.log(`[NexusHub] \u{1F310} Fetching: ${url}`);
-    }
     const expiresAt = revalidate === false ? Infinity : Date.now() + revalidate * 1e3;
+    const fetchTags = [
+      CacheTags.project(this.config.projectId),
+      CacheTags.content(slug),
+      ...tags
+    ];
     const res = await this.fetchWithTimeout(url, {
       method: "GET",
       headers: this.getHeaders(),
-      tags,
+      tags: fetchTags,
       revalidate
     });
     if (!res.ok) {
@@ -1417,29 +1463,27 @@ var ContentEngine = class {
         timestamp: Date.now(),
         etag: etag || void 0,
         expiresAt,
-        tags: [...tags, CacheTags.content(slug)]
+        tags: fetchTags
       }
     };
     this.writeCache(cacheKey, cacheEntry.data, {
       revalidate,
-      tags: [
-        CacheTags.project(this.config.projectId),
-        CacheTags.content(slug),
-        ...tags
-      ]
+      tags: fetchTags
     });
     return cacheEntry;
   }
   async fetchCollection(collectionId, query, cacheKey, tags, revalidate) {
     const params = buildQueryString(query);
     const url = `${this.config.apiUrl}/content/${this.config.projectId}/collection/${collectionId}?${params}`;
-    if (this.config.debug) {
-      console.log(`[NexusHub] \u{1F310} Fetching Collection: ${url}`);
-    }
+    const fetchTags = [
+      CacheTags.project(this.config.projectId),
+      CacheTags.collection(collectionId),
+      ...tags
+    ];
     const res = await this.fetchWithTimeout(url, {
       method: "GET",
       headers: this.getHeaders(),
-      tags,
+      tags: fetchTags,
       revalidate
     });
     if (!res.ok) {
@@ -1454,16 +1498,12 @@ var ContentEngine = class {
         timestamp: Date.now(),
         etag: etag || void 0,
         expiresAt,
-        tags: [...tags, CacheTags.collection(collectionId)]
+        tags: fetchTags
       }
     };
     this.writeCache(cacheKey, cacheEntry.data, {
       revalidate,
-      tags: [
-        CacheTags.project(this.config.projectId),
-        CacheTags.collection(collectionId),
-        ...tags
-      ]
+      tags: fetchTags
     });
     return cacheEntry;
   }
@@ -1523,8 +1563,11 @@ var ContentEngine = class {
     const controller = new AbortController();
     const id = setTimeout(() => controller.abort(), timeout);
     const nextConfig = this.isServer ? {
-      cache: "force-cache",
-      next: { tags, revalidate: revalidate === false ? false : revalidate }
+      cache: revalidate === 0 ? "no-store" : "force-cache",
+      next: {
+        tags,
+        revalidate: revalidate === false ? false : revalidate
+      }
     } : {};
     try {
       const response = await fetch(url, {
@@ -2547,13 +2590,20 @@ function getSelector(el, depth = 0) {
 }
 
 // src/client.ts
+var DEFAULT_REVALIDATE_SECONDS = 60;
 var NexusClient = class {
   constructor(config) {
     const fullConfig = getFullConfig(config);
     this.config = {
       debug: config?.debug ?? false,
       cacheStrategy: config?.cacheStrategy ?? "memory",
-      revalidateTime: config?.revalidateTime ?? false,
+      // Only fall through to the safe default when revalidateTime is
+      // genuinely *unset* (undefined). An explicit `false` from the caller
+      // is a deliberate "never revalidate" choice and must be respected,
+      // not silently upgraded — `??` (not `||`) is required here so that
+      // `0` (revalidate on every request) also passes through untouched
+      // instead of being treated as falsy.
+      revalidateTime: config?.revalidateTime ?? DEFAULT_REVALIDATE_SECONDS,
       timeout: config?.timeout ?? 1e4,
       retries: config?.retries ?? 3,
       ...fullConfig

package/dist/index.d.cts

@@ -119,6 +119,7 @@ declare class ContentEngine {
         include?: string[];
         revalidate?: number | false;
         forceRefresh?: boolean;
+        tags?: string[];
     }): Promise<T>;
     /**
      * Get a single item from a collection (Uses Request Batching)
@@ -146,24 +147,32 @@ declare class ContentEngine {
     prefetch(urls: string[]): Promise<void>;
     /**
      * Robust Real-time Subscriptions (SSE) with Auto-Reconnect
+     *
+     * ⚠️ SCOPE — READ BEFORE RELYING ON THIS FOR "instant" UPDATES:
+     * This connects from the BROWSER TAB it's called in, and on message it
+     * only clears THIS SDK INSTANCE's in-memory `memoryCache` (via
+     * invalidateCache below) in THAT browser tab's JS heap. In a typical
+     * Next.js deployment — and Cloudflare specifically, which is stateless
+     * per-request at the edge — that is a different process/isolate than the
+     * one that will render the NEXT server request for this content. So:
+     *   - ✅ Useful for: a client component that reads from `nexus.content`
+     *     directly in the browser and re-renders in place without a page
+     *     navigation (e.g. a live-updating dashboard widget).
+     *   - ❌ NOT sufficient for: "user A edits content in the CMS, user B's
+     *     already-loaded page updates" via a server-rendered page. That
+     *     requires the backend's /api/revalidate webhook (see
+     *     content.service.ts `pingNextRevalidateWebhook`) to have actually
+     *     cleared the *server's* Data Cache, so the NEXT navigation or
+     *     server request picks up fresh data. This SSE channel does not
+     *     replace that — it's a complementary, browser-local optimization.
+     * If your symptom was "stale content after editing," fix the webhook
+     * wiring first; treat this method as an enhancement layered on top.
      */
     subscribeToUpdates(callback: (data: any) => void): () => void;
-    /**
-     * Check all caches in order of speed
-     */
     private checkCaches;
     private writeCache;
-    /**
-     * Invalidate cache by tags
-     */
     invalidateCache(tags: string[]): void;
-    /**
-     * Clear all caches
-     */
     clearCache(): void;
-    /**
-     * Get cache statistics
-     */
     getCacheStats(): {
         memory: {
             size: number;

package/dist/index.d.ts

@@ -119,6 +119,7 @@ declare class ContentEngine {
         include?: string[];
         revalidate?: number | false;
         forceRefresh?: boolean;
+        tags?: string[];
     }): Promise<T>;
     /**
      * Get a single item from a collection (Uses Request Batching)
@@ -146,24 +147,32 @@ declare class ContentEngine {
     prefetch(urls: string[]): Promise<void>;
     /**
      * Robust Real-time Subscriptions (SSE) with Auto-Reconnect
+     *
+     * ⚠️ SCOPE — READ BEFORE RELYING ON THIS FOR "instant" UPDATES:
+     * This connects from the BROWSER TAB it's called in, and on message it
+     * only clears THIS SDK INSTANCE's in-memory `memoryCache` (via
+     * invalidateCache below) in THAT browser tab's JS heap. In a typical
+     * Next.js deployment — and Cloudflare specifically, which is stateless
+     * per-request at the edge — that is a different process/isolate than the
+     * one that will render the NEXT server request for this content. So:
+     *   - ✅ Useful for: a client component that reads from `nexus.content`
+     *     directly in the browser and re-renders in place without a page
+     *     navigation (e.g. a live-updating dashboard widget).
+     *   - ❌ NOT sufficient for: "user A edits content in the CMS, user B's
+     *     already-loaded page updates" via a server-rendered page. That
+     *     requires the backend's /api/revalidate webhook (see
+     *     content.service.ts `pingNextRevalidateWebhook`) to have actually
+     *     cleared the *server's* Data Cache, so the NEXT navigation or
+     *     server request picks up fresh data. This SSE channel does not
+     *     replace that — it's a complementary, browser-local optimization.
+     * If your symptom was "stale content after editing," fix the webhook
+     * wiring first; treat this method as an enhancement layered on top.
      */
     subscribeToUpdates(callback: (data: any) => void): () => void;
-    /**
-     * Check all caches in order of speed
-     */
     private checkCaches;
     private writeCache;
-    /**
-     * Invalidate cache by tags
-     */
     invalidateCache(tags: string[]): void;
-    /**
-     * Clear all caches
-     */
     clearCache(): void;
-    /**
-     * Get cache statistics
-     */
     getCacheStats(): {
         memory: {
             size: number;