@contentcredits/sdk 2.12.0 → 2.13.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

@@ -676,7 +676,9 @@ function getPaywallStyles(primaryColor, fontFamily) {
 
     /* ── Overlay paywall panel — full-width white panel below gated content ── */
     .cc-paywall-overlay {
-      width: 100%;
+      /* Break out of any max-width container to span the full viewport */
+      width: 100vw;
+      margin-left: calc(50% - 50vw);
       background: #fff;
       font-family: ${fontFamily};
     }
@@ -3207,7 +3209,7 @@ class ContentCredits {
     }
     /** SDK version string. */
     static get version() {
-        return "2.3.0";
+        return "2.13.0";
     }
 }
 // ── Auto-init from script data attributes (CDN usage) ────────────────────────