@contentcredits/sdk 2.0.1 → 2.0.3

package/LICENSE

@@ -0,0 +1,178 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+   You may add Your own license statement for Your modifications and
+   may provide additional grant of rights to use, copy, modify, and
+   distribute those modifications.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Content Credits
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -1,7 +1,7 @@
 # @contentcredits/sdk
 
 [![npm version](https://img.shields.io/npm/v/@contentcredits/sdk)](https://www.npmjs.com/package/@contentcredits/sdk)
-[![license](https://img.shields.io/npm/l/@contentcredits/sdk)](https://github.com/contentcredits/sdk/blob/main/LICENSE)
+[![license](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/contentcredits/sdk/blob/main/LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
 
 Drop-in paywall and threaded comment system for any website. Add credit-based article monetisation in under 5 minutes — no backend changes required.
@@ -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) ────────────────────────