@contentcredits/sdk 2.12.0 → 2.14.0

package/README.md

@@ -13,9 +13,10 @@ Drop-in paywall and threaded comment system for any website. Add credit-based ar
 ## What it does
 
 - **Paywall** — hides premium content behind a credit gate using a CSS selector. Reveals it instantly when the reader pays. No server-side content splitting needed.
+- **Customisable top slot** — inject your own content (React widget, donation banner, structured items) above the SDK's unlock button.
 - **Comments** — threaded comment panel with likes, edit, delete, and sorting. Rendered in a Shadow DOM so it never conflicts with your CSS.
 - **Auth** — popup-based login on desktop, redirect flow on mobile. Tokens stored in memory (never cookies).
-- **Extension support** — detects the Content Credits Chrome extension for a one-click experience.
+- **Extension support** — detects the Content Credits Chrome extension for a one-click experience, with automatic fallback if the extension service worker is unresponsive.
 
 ---
 
@@ -28,7 +29,7 @@ npm install @contentcredits/sdk
 Or via CDN (no build step):
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@contentcredits/sdk@2.0.0/dist/content-credits.umd.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@contentcredits/sdk@2.12.0/dist/content-credits.umd.min.js"></script>
 ```
 
 ---
@@ -44,7 +45,7 @@ Or via CDN (no build step):
 </div>
 
 <!-- Load and initialise the SDK -->
-<script src="https://cdn.jsdelivr.net/npm/@contentcredits/sdk@2.0.0/dist/content-credits.umd.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@contentcredits/sdk@2.12.0/dist/content-credits.umd.min.js"></script>
 <script>
   ContentCreditsSDK.ContentCredits.init({
     apiKey: 'pub_YOUR_API_KEY',
@@ -59,7 +60,7 @@ Or via CDN (no build step):
 
 ```html
 <script
-  src="https://cdn.jsdelivr.net/npm/@contentcredits/sdk@2.0.0/dist/content-credits.umd.min.js"
+  src="https://cdn.jsdelivr.net/npm/@contentcredits/sdk@2.12.0/dist/content-credits.umd.min.js"
   data-api-key="pub_YOUR_API_KEY"
   data-content-selector="#premium-content"
   data-teaser-paragraphs="2"
@@ -94,13 +95,90 @@ cc.on('paywall:hidden', () => {
 | `teaserParagraphs` | `number` | `2` | Paragraphs to show before the paywall |
 | `enableComments` | `boolean` | `true` | Show the comment widget |
 | `articleUrl` | `string` | `location.href` | Canonical URL of the article |
+| `paywallMode` | `'overlay' \| 'inline'` | `'overlay'` | Paywall layout — overlay sits directly below the teaser; inline is the legacy flow-based panel |
+| `paywallTopSlot` | see below | — | Content rendered above the SDK's unlock button — accepts a React element, structured items, `HTMLElement`, or factory function |
+| `reactDOM` | `ReactDOMAdapter` | — | Your `ReactDOM` instance — required when `paywallTopSlot` is a React element |
 | `theme.primaryColor` | `string` | `'#44C678'` | Brand colour for buttons |
 | `theme.fontFamily` | `string` | system UI | Font for all SDK UI |
+| `headless` | `boolean` | `false` | Disable all built-in DOM/UI — manage everything yourself via state and callbacks |
 | `onAccessGranted` | `() => void` | — | Fires when content is unlocked |
 | `debug` | `boolean` | `false` | Verbose console logging |
 
 ---
 
+## Paywall top slot
+
+The `paywallTopSlot` lets you inject custom content — a donation widget, promo banner, or anything else — above the SDK's own unlock button. The slot sits inside the SDK's Shadow DOM so your styles are isolated from the host page.
+
+### React widget (recommended for React apps)
+
+Pass your ReactDOM instance alongside the JSX element. Works with React 18 (`createRoot`) and React 16/17 (`render`).
+
+```tsx
+import ReactDOM from 'react-dom/client'; // React 18
+import { ContentCredits } from '@contentcredits/sdk';
+import { DonationWidget } from './DonationWidget';
+
+ContentCredits.init({
+  apiKey: 'pub_YOUR_API_KEY',
+  reactDOM,
+  paywallTopSlot: <DonationWidget />,
+});
+```
+
+### Structured items
+
+The SDK renders and styles these consistently inside its Shadow DOM:
+
+```ts
+ContentCredits.init({
+  apiKey: 'pub_YOUR_API_KEY',
+  paywallTopSlot: [
+    { type: 'heading',  content: 'Donate to access this story.' },
+    { type: 'text',     content: 'Donate now for unlimited stories. Cancel anytime.' },
+    { type: 'button',   content: 'See Donation Options', variant: 'primary', onClick: () => openDonateFlow() },
+  ],
+});
+```
+
+Available item types:
+
+| `type` | Description | Extra props |
+|--------|-------------|-------------|
+| `heading` | Large bold heading | `content` |
+| `subheading` | Medium bold text | `content` |
+| `text` | Body copy | `content` |
+| `button` | Styled button | `content`, `variant` (`primary` \| `secondary` \| `outline`), `onClick` |
+| `divider` | Horizontal rule with optional label | `content` |
+
+### HTMLElement
+
+```ts
+const banner = document.createElement('div');
+banner.innerHTML = '<strong>Support independent journalism</strong>';
+
+ContentCredits.init({
+  apiKey: 'pub_YOUR_API_KEY',
+  paywallTopSlot: banner,
+});
+```
+
+### Factory function
+
+Full control — receives the slot container element and mounts whatever you need:
+
+```ts
+ContentCredits.init({
+  apiKey: 'pub_YOUR_API_KEY',
+  paywallTopSlot: (container) => {
+    // vanilla JS, Vue, Svelte — anything goes
+    container.innerHTML = `<p>Support us to keep reading.</p>`;
+  },
+});
+```
+
+---
+
 ## Events
 
 ```ts
@@ -128,39 +206,91 @@ const cc = ContentCredits.init(config);
 
 cc.on(event, handler)    // subscribe — returns unsubscribe fn
 cc.off(event, handler)   // unsubscribe
+cc.subscribe(fn)         // reactive state changes — returns unsubscribe fn
 cc.getState()            // → SDKState snapshot
 cc.checkAccess()         // trigger access check manually
+cc.login()               // open login flow programmatically
+cc.purchase()            // trigger article purchase
+cc.buyMoreCredits()      // open dashboard to top up balance
 cc.openComments()        // open comment panel
 cc.closeComments()       // close comment panel
 cc.isLoggedIn()          // → boolean
+cc.getToken()            // → access token string | null
+cc.logout()              // revoke session and clear local auth state
 cc.destroy()             // tear down SDK, restore hidden content
 
-ContentCredits.version   // → "2.0.0"
+ContentCredits.version   // → "2.12.0"
 ```
 
 ---
 
 ## React / Next.js
 
+### Default UI with a React top slot
+
+The simplest integration — the SDK handles all paywall rendering; you only supply the top section:
+
 ```tsx
-'use client'; // Next.js App Router
+'use client';
 
 import { useEffect } from 'react';
+import ReactDOM from 'react-dom/client';
 import { ContentCredits } from '@contentcredits/sdk';
+import { DonationWidget } from './DonationWidget';
 
-export function PremiumGate({ apiKey, children }) {
+export function PremiumGate({ apiKey }: { apiKey: string }) {
   useEffect(() => {
     const cc = ContentCredits.init({
       apiKey,
       contentSelector: '#premium-content',
+      reactDOM,
+      paywallTopSlot: <DonationWidget />,
+    });
+    return () => cc.destroy();
+  }, [apiKey]);
+
+  return <div id="premium-content">{/* article content */}</div>;
+}
+```
+
+### Headless mode (full custom UI)
+
+Use `headless: true` when you want to build the entire paywall UI yourself in React. The SDK manages auth and access checks but renders no DOM of its own.
+
+```tsx
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { ContentCredits } from '@contentcredits/sdk';
+import type { SDKState } from '@contentcredits/sdk';
+
+export function PremiumGate({ apiKey, children }: { apiKey: string; children: React.ReactNode }) {
+  const ccRef = useRef<ContentCredits | null>(null);
+  const [state, setState] = useState<SDKState | null>(null);
+
+  useEffect(() => {
+    const cc = ContentCredits.init({
+      apiKey,
+      headless: true,
+      onStateChange: setState,
     });
+    ccRef.current = cc;
     return () => cc.destroy();
   }, [apiKey]);
 
-  return <div id="premium-content">{children}</div>;
+  if (state?.hasAccess) return <>{children}</>;
+
+  return (
+    <div>
+      {/* your teaser content */}
+      <button onClick={() => ccRef.current?.purchase()}>Unlock article</button>
+    </div>
+  );
 }
 ```
 
+See [`examples/nextjs-blog`](./examples/nextjs-blog) for a full working Next.js 14 (App Router) implementation.
+
 ---
 
 ## Requirements

package/dist/content-credits.cjs.js

@@ -597,7 +597,7 @@ function createShadowHost(id) {
         host = document.createElement('div');
         host.id = id;
         // The host element itself is invisible; only its shadow children show
-        host.style.cssText = 'position:fixed;top:0;left:0;width:0;height:0;pointer-events:none;z-index:2147483647;';
+        host.style.cssText = 'position:fixed;bottom:0;left:0;width:100%;height:auto;z-index:2147483647;';
         document.body.appendChild(host);
     }
     const existing = host._ccShadow;
@@ -676,34 +676,41 @@ function getPaywallStyles(primaryColor, fontFamily) {
 
     /* ── Overlay paywall panel — full-width white panel below gated content ── */
     .cc-paywall-overlay {
+      /* Fixed to the bottom of the viewport — always visible, full width */
+      position: fixed;
+      bottom: 0;
+      left: 0;
       width: 100%;
       background: #fff;
+      box-shadow: 0 -8px 40px rgba(0,0,0,0.10);
+      border-top: 1px solid #e5e7eb;
       font-family: ${fontFamily};
     }
 
-    /* Gradient that fades the article into the white panel */
+    /* Gradient that fades the article into the panel.
+       Sits above the panel via position:absolute + negative top. */
     .cc-paywall-overlay-gradient {
-      width: 100%;
+      position: absolute;
+      top: -120px;
+      left: 0;
+      right: 0;
       height: 120px;
       background: linear-gradient(to bottom, transparent 0%, #fff 100%);
-      margin-top: -120px;
       pointer-events: none;
-      position: relative;
-      z-index: 1;
     }
 
     /* Top slot — client-supplied content */
     .cc-paywall-overlay-slot {
-      padding: 32px 24px 0;
+      padding: 20px 24px 0;
       display: flex;
       flex-direction: column;
       align-items: center;
-      gap: 12px;
+      gap: 10px;
     }
 
     /* Our SDK's unlock section below the slot */
     .cc-paywall-overlay-body {
-      padding: 20px 24px 32px;
+      padding: 16px 24px 24px;
       display: flex;
       flex-direction: column;
       align-items: center;
@@ -1285,7 +1292,12 @@ function createPaywallRenderer(config) {
         const contentEl = document.querySelector(config.contentSelector);
         if (!contentEl)
             return;
-        const { root: shadowRoot } = createInlineShadowHost(HOST_ID, contentEl);
+        // Overlay mode: fixed to the bottom of the viewport — attach to body so it
+        // is never constrained by the article's max-width container.
+        // Inline mode: inserted after the content element in document flow.
+        const { root: shadowRoot } = config.paywallMode === 'overlay'
+            ? createShadowHost(HOST_ID)
+            : createInlineShadowHost(HOST_ID, contentEl);
         root = shadowRoot;
         injectStyles(root, getPaywallStyles(config.theme.primaryColor, config.theme.fontFamily));
         if (config.paywallMode === 'overlay') {
@@ -1301,23 +1313,25 @@ function createPaywallRenderer(config) {
         shadowRoot.appendChild(body);
     }
     function initOverlay(shadowRoot, contentEl) {
-        var _a, _b;
+        var _a;
         const panel = el('div');
         panel.className = 'cc-paywall-overlay';
-        // Gradient that visually fades the article into the white panel.
-        // We read the computed background of the content element's parent so the
-        // gradient blends correctly on sites with non-white backgrounds.
+        // Gradient that visually fades the article into the panel.
+        // Reads the page background so the gradient colour matches non-white sites.
         const gradient = el('div');
         gradient.className = 'cc-paywall-overlay-gradient';
-        const parentBg = getComputedStyle((_a = contentEl.parentElement) !== null && _a !== void 0 ? _a : contentEl).backgroundColor;
-        if (parentBg && parentBg !== 'rgba(0, 0, 0, 0)' && parentBg !== 'transparent') {
-            gradient.style.background = `linear-gradient(to bottom, transparent 0%, ${parentBg} 100%)`;
+        const pageBg = getComputedStyle(document.body).backgroundColor;
+        if (pageBg && pageBg !== 'rgba(0, 0, 0, 0)' && pageBg !== 'transparent') {
+            gradient.style.background = `linear-gradient(to bottom, transparent 0%, ${pageBg} 100%)`;
         }
         panel.appendChild(gradient);
+        // Add bottom padding to the content element so the fixed panel
+        // doesn't overlap the last readable line of the teaser.
+        contentEl.style.paddingBottom = '200px';
         // Top slot — client content
         const slot = el('div');
         slot.className = 'cc-paywall-overlay-slot';
-        reactRoot = (_b = mountTopSlot(slot, config.paywallTopSlot, config.reactDOM)) !== null && _b !== void 0 ? _b : null;
+        reactRoot = (_a = mountTopSlot(slot, config.paywallTopSlot, config.reactDOM)) !== null && _a !== void 0 ? _a : null;
         panel.appendChild(slot);
         // Only render the "or" divider between slot and body when the slot has content
         if (config.paywallTopSlot) {
@@ -1447,6 +1461,12 @@ function createPaywallRenderer(config) {
         reactRoot === null || reactRoot === void 0 ? void 0 : reactRoot.unmount();
         reactRoot = null;
         removeShadowHost(HOST_ID);
+        // Remove the padding we added to the content element
+        if (config.paywallMode === 'overlay') {
+            const contentEl = document.querySelector(config.contentSelector);
+            if (contentEl)
+                contentEl.style.paddingBottom = '';
+        }
         root = null;
         body = null;
     }
@@ -3207,7 +3227,7 @@ class ContentCredits {
     }
     /** SDK version string. */
     static get version() {
-        return "2.3.0";
+        return "2.14.0";
     }
 }
 // ── Auto-init from script data attributes (CDN usage) ────────────────────────