@contentcredits/sdk 2.0.2 → 2.0.3

package/README.md

@@ -171,6 +171,14 @@ export function PremiumGate({ apiKey, children }) {
 
 ---
 
+## Examples
+
+| Example | Description |
+|---------|-------------|
+| [`examples/nextjs-blog`](./examples/nextjs-blog) | Next.js 14 (App Router) blog with free and premium articles — the fastest way to see the SDK in a real project |
+
+---
+
 ## Links
 
 - [Full documentation](https://docs.contentcredits.com)

package/dist/auth/session.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Attempt a silent token refresh using the stored refresh token.
+ *
+ * Uses a raw fetch (not the SDK API client) to avoid:
+ *   1. Circular dependency: client → session → client
+ *   2. Triggering the client's own 401 → tryRefreshSession loop
+ *
+ * Returns true if a new access token was obtained and stored.
+ *
+ * On network error the refresh token is NOT cleared — it may still be
+ * valid once connectivity returns.  On 401/403 the token is cleared
+ * because the server has explicitly rejected it (expired / revoked).
+ */
+export declare function tryRefreshSession(apiBaseUrl: string): Promise<boolean>;

package/dist/auth/storage.d.ts

@@ -4,3 +4,17 @@ export declare const tokenStorage: {
     clear(): void;
     has(): boolean;
 };
+/**
+ * Refresh token storage — localStorage only.
+ *
+ * Stored on the publisher's domain (first-party storage) so it is never
+ * subject to third-party cookie / storage blocking in any browser.
+ * Refresh tokens are opaque strings issued by the backend and rotated
+ * on every use.
+ */
+export declare const refreshTokenStorage: {
+    set(token: string): void;
+    get(): string | null;
+    clear(): void;
+    has(): boolean;
+};

package/dist/content-credits.cjs.js

@@ -164,15 +164,22 @@ function getUserIdFromToken(token) {
 }
 
 const SESSION_KEY = 'cc_sdk_token';
+const REFRESH_KEY = 'cc_rt';
 /**
- * Two-layer token storage:
- *  1. In-memory (primary) — invisible to other scripts, survives page navigations
- *     within the same JS context but gone on hard reload.
- *  2. sessionStorage (secondary) — survives soft reloads, cleared when the tab
- *     closes, never shared across tabs.
+ * Three-layer auth storage:
  *
- * We intentionally never use document.cookie (no HttpOnly = XSS risk) or
- * localStorage (persists indefinitely across sessions).
+ *  ACCESS TOKEN (short-lived JWT, ~15 min)
+ *  ┌─ Layer 1: in-memory  — invisible to other scripts; cleared on page close
+ *  └─ Layer 2: sessionStorage — survives soft reloads; cleared when tab closes
+ *
+ *  REFRESH TOKEN (long-lived opaque token, ~30 days)
+ *  └─ Layer 3: localStorage — survives browser close; used to silently
+ *     re-authenticate on the next visit without showing a popup
+ *
+ * We intentionally never write to document.cookie (no HttpOnly = XSS risk).
+ * The refresh token in localStorage is the accepted industry trade-off:
+ * it persists across sessions at the cost of XSS accessibility, mitigated
+ * by short-lived access tokens and server-side refresh token rotation.
  */
 let memoryToken = null;
 const tokenStorage = {
@@ -224,6 +231,95 @@ const tokenStorage = {
         return this.get() !== null;
     },
 };
+/**
+ * Refresh token storage — localStorage only.
+ *
+ * Stored on the publisher's domain (first-party storage) so it is never
+ * subject to third-party cookie / storage blocking in any browser.
+ * Refresh tokens are opaque strings issued by the backend and rotated
+ * on every use.
+ */
+const refreshTokenStorage = {
+    set(token) {
+        try {
+            localStorage.setItem(REFRESH_KEY, token);
+        }
+        catch (_a) {
+            // localStorage unavailable (private mode with strict settings) — degrade
+            // to session-only auth gracefully
+        }
+    },
+    get() {
+        try {
+            return localStorage.getItem(REFRESH_KEY);
+        }
+        catch (_a) {
+            return null;
+        }
+    },
+    clear() {
+        try {
+            localStorage.removeItem(REFRESH_KEY);
+        }
+        catch (_a) {
+            // ignore
+        }
+    },
+    has() {
+        return this.get() !== null;
+    },
+};
+
+/**
+ * Attempt a silent token refresh using the stored refresh token.
+ *
+ * Uses a raw fetch (not the SDK API client) to avoid:
+ *   1. Circular dependency: client → session → client
+ *   2. Triggering the client's own 401 → tryRefreshSession loop
+ *
+ * Returns true if a new access token was obtained and stored.
+ *
+ * On network error the refresh token is NOT cleared — it may still be
+ * valid once connectivity returns.  On 401/403 the token is cleared
+ * because the server has explicitly rejected it (expired / revoked).
+ */
+async function tryRefreshSession(apiBaseUrl) {
+    const rt = refreshTokenStorage.get();
+    if (!rt)
+        return false;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 8000);
+    try {
+        const resp = await fetch(`${apiBaseUrl}/auth/refresh`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ refreshToken: rt }),
+            credentials: 'omit',
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!resp.ok) {
+            // Server rejected the token — it has expired or been revoked.
+            // Clear it so we don't retry on every page load.
+            refreshTokenStorage.clear();
+            return false;
+        }
+        const data = (await resp.json());
+        if (!(data === null || data === void 0 ? void 0 : data.accessToken) || !(data === null || data === void 0 ? void 0 : data.refreshToken)) {
+            refreshTokenStorage.clear();
+            return false;
+        }
+        // Store new access token and rotate the refresh token
+        tokenStorage.set(data.accessToken);
+        refreshTokenStorage.set(data.refreshToken);
+        return true;
+    }
+    catch (_a) {
+        // Network error or timeout — don't clear the refresh token
+        clearTimeout(timeoutId);
+        return false;
+    }
+}
 
 const REQUEST_TIMEOUT_MS = 12000;
 const MAX_RETRIES = 3;
@@ -240,7 +336,8 @@ function shouldRetry(status) {
     return status >= 500 || status === 429;
 }
 function createApiClient(baseUrl, emitter) {
-    async function request(method, path, body, attempt = 0) {
+    async function request(method, path, body, attempt = 0, authRetried = false // true after one silent-refresh attempt, prevents loops
+    ) {
         const url = `${baseUrl}${path}`;
         const serialisedBody = body ? JSON.stringify(body) : undefined;
         const key = requestKey(method, url, serialisedBody);
@@ -268,7 +365,18 @@ function createApiClient(baseUrl, emitter) {
             var _a;
             clearTimeout(timeoutId);
             if (response.status === 401) {
+                // Try a silent refresh once before giving up.
+                // authRetried guard prevents an infinite loop if the refresh
+                // endpoint itself returns 401.
+                if (!authRetried) {
+                    const refreshed = await tryRefreshSession(baseUrl);
+                    if (refreshed) {
+                        inFlight.delete(key);
+                        return request(method, path, body, attempt, true);
+                    }
+                }
                 tokenStorage.clear();
+                refreshTokenStorage.clear();
                 emitter.emit('auth:logout', {});
                 throw new ApiError(401, 'Unauthorized — session expired');
             }
@@ -494,16 +602,29 @@ function getPaywallStyles(primaryColor, fontFamily) {
       pointer-events: none;
     }
 
+    /* Full-viewport backdrop — centers the overlay and blocks background clicks */
+    .cc-paywall-backdrop {
+      position: fixed;
+      inset: 0;
+      background: rgba(0, 0, 0, 0.45);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 20px;
+      pointer-events: all;
+    }
+
     .cc-paywall-overlay {
       background: #fff;
       border: 1px solid #e5e7eb;
       border-radius: 12px;
       padding: 32px 24px;
+      width: 100%;
       max-width: 480px;
-      margin: 24px auto;
       text-align: center;
       font-family: ${fontFamily};
-      box-shadow: 0 4px 24px rgba(0,0,0,0.08);
+      box-shadow: 0 8px 40px rgba(0,0,0,0.18);
+      pointer-events: all;
     }
 
     .cc-paywall-overlay h2 {
@@ -1049,9 +1170,14 @@ function createPaywallRenderer(config) {
         const { root: shadowRoot } = createShadowHost(HOST_ID);
         root = shadowRoot;
         injectStyles(root, getPaywallStyles(config.theme.primaryColor, config.theme.fontFamily));
+        // Backdrop: fixed full-viewport flex container — centers the overlay and
+        // blocks interaction with the page behind it (pointer-events: all in CSS).
+        const backdrop = el('div');
+        backdrop.className = 'cc-paywall-backdrop';
+        root.appendChild(backdrop);
         overlay = el('div');
         overlay.className = 'cc-paywall-overlay';
-        root.appendChild(overlay);
+        backdrop.appendChild(overlay);
     }
     function render(state, callbacks, meta) {
         var _a, _b, _c;
@@ -1323,7 +1449,7 @@ function scrubTokenFromUrl() {
     try {
         const url = new URL(window.location.href);
         let changed = false;
-        ['token', 'cc_token'].forEach(param => {
+        ['token', 'cc_token', 'refresh_token', 'cc_refresh_token'].forEach(param => {
             if (url.searchParams.has(param)) {
                 url.searchParams.delete(param);
                 changed = true;
@@ -1343,17 +1469,22 @@ function scrubTokenFromUrl() {
  * Always scrubs the token from the URL after reading it.
  */
 function consumeTokenFromUrl() {
-    var _a;
+    var _a, _b;
     try {
         const url = new URL(window.location.href);
         const token = (_a = url.searchParams.get('token')) !== null && _a !== void 0 ? _a : url.searchParams.get('cc_token');
+        const refreshToken = (_b = url.searchParams.get('refresh_token')) !== null && _b !== void 0 ? _b : url.searchParams.get('cc_refresh_token');
+        // Scrub ALL auth params before doing anything else
         scrubTokenFromUrl();
+        if (refreshToken) {
+            refreshTokenStorage.set(refreshToken);
+        }
         if (token) {
             tokenStorage.set(token);
             return token;
         }
     }
-    catch (_b) {
+    catch (_c) {
         // ignore
     }
     return null;
@@ -1381,7 +1512,7 @@ function openAuthPopup(authUrl) {
         const MAX_WAIT_MS = 5 * 60 * 1000; // 5 minutes
         let elapsed = 0;
         const timer = setInterval(() => {
-            var _a;
+            var _a, _b;
             elapsed += POLL_MS;
             if (!popup || popup.closed) {
                 clearInterval(timer);
@@ -1393,7 +1524,7 @@ function openAuthPopup(authUrl) {
                 try {
                     popup.close();
                 }
-                catch ( /* ignore */_b) { /* ignore */ }
+                catch ( /* ignore */_c) { /* ignore */ }
                 resolve(null);
                 return;
             }
@@ -1403,18 +1534,22 @@ function openAuthPopup(authUrl) {
                 if (popupUrl.includes('/auth/callback') || popupUrl.includes('cc_token=') || popupUrl.includes('token=')) {
                     const params = new URLSearchParams(popup.location.search);
                     const token = (_a = params.get('token')) !== null && _a !== void 0 ? _a : params.get('cc_token');
+                    const refreshToken = (_b = params.get('refresh_token')) !== null && _b !== void 0 ? _b : params.get('cc_refresh_token');
                     if (token) {
                         tokenStorage.set(token);
+                        if (refreshToken) {
+                            refreshTokenStorage.set(refreshToken);
+                        }
                         clearInterval(timer);
                         try {
                             popup.close();
                         }
-                        catch ( /* ignore */_c) { /* ignore */ }
+                        catch ( /* ignore */_d) { /* ignore */ }
                         resolve(token);
                     }
                 }
             }
-            catch (_d) {
+            catch (_e) {
                 // cross-origin error — popup is on accounts domain, not ours yet; keep polling
             }
         }, POLL_MS);
@@ -2485,8 +2620,15 @@ class ContentCredits {
     }
     // ── Internal start ────────────────────────────────────────────────────────
     async _start() {
-        // Handle token that may have arrived in the URL (mobile redirect flow)
+        // 1. Consume any token that arrived in the URL (mobile redirect flow)
         consumeTokenFromUrl();
+        // 2. If no access token in memory/session, attempt a silent refresh.
+        //    This runs on every new browser session (after the browser was closed)
+        //    and silently re-authenticates the user using their stored refresh token
+        //    — no popup, no visible delay, no paywall flash.
+        if (!tokenStorage.has()) {
+            await tryRefreshSession(this.config.apiBaseUrl);
+        }
         this.paywallModule = createPaywall(this.config, this.creditsApi, this.state, this.emitter);
         if (this.config.enableComments) {
             this.commentsModule = createComments(this.config, this.commentsApi, this.emitter);
@@ -2537,7 +2679,7 @@ class ContentCredits {
     }
     /** SDK version string. */
     static get version() {
-        return "2.0.0";
+        return "2.0.3";
     }
 }
 // ── Auto-init from script data attributes (CDN usage) ────────────────────────