@contentcredits/sdk 2.11.0 → 2.13.0

package/dist/types/index.d.ts

@@ -74,6 +74,29 @@ export interface CommentsResponse {
     comments: Comment[];
 }
 export type EnsureThreadResponse = CommentThread;
+export type PaywallSlotItemVariant = 'primary' | 'secondary' | 'outline';
+export interface PaywallSlotItem {
+    type: 'heading' | 'subheading' | 'text' | 'button' | 'divider';
+    /** Text content — used by heading, subheading, text, button, and divider (for the label) */
+    content?: string;
+    /** Button style variant. Default: 'primary' */
+    variant?: PaywallSlotItemVariant;
+    /** Click handler for button items */
+    onClick?: () => void;
+}
+/**
+ * Loosely-typed ReactDOM adapter — matches both React 18 (`createRoot`) and
+ * React 16/17 (`render`) without pulling React into the SDK's own bundle.
+ */
+export interface ReactDOMAdapter {
+    /** React 18+ */
+    createRoot?(container: Element): {
+        render(node: unknown): void;
+        unmount(): void;
+    };
+    /** React 16/17 */
+    render?(node: unknown, container: Element, callback?: () => void): void;
+}
 export interface SDKConfig {
     /** Publisher API key from the Content Credits admin panel */
     apiKey: string;
@@ -89,8 +112,43 @@ export interface SDKConfig {
     extensionId?: string;
     /** Visual theme options */
     theme?: SDKTheme;
-    /** Custom HTML template string for the paywall overlay */
-    paywallTemplate?: string;
+    /**
+     * Paywall display mode.
+     * - `'inline'` — panel sits below the teaser content in the page flow (original behaviour)
+     * - `'overlay'` — full-width panel that renders below the gated content (default)
+     *
+     * Default: `'overlay'`
+     */
+    paywallMode?: 'inline' | 'overlay';
+    /**
+     * Your ReactDOM instance. Required when `paywallTopSlot` is a React element.
+     * Supports React 18 (`createRoot`) and React 16/17 (`render`).
+     *
+     * @example
+     * import ReactDOM from 'react-dom/client'; // React 18
+     * ContentCredits.init({ reactDOM, paywallTopSlot: <DonationWidget /> });
+     */
+    reactDOM?: ReactDOMAdapter;
+    /**
+     * Content to render in the top section of the paywall panel, above the SDK's
+     * own unlock UI.
+     *
+     * Accepts:
+     * - A React element (JSX) — requires `reactDOM` to also be set
+     * - A structured `PaywallSlotItem[]` array — SDK renders & styles the items
+     * - A plain `HTMLElement` — appended directly into the slot container
+     * - A factory `(container: HTMLElement) => void` — called with the slot DOM node
+     *
+     * @example React widget
+     * paywallTopSlot: <DonationWidget />   // also set reactDOM
+     *
+     * @example Structured items
+     * paywallTopSlot: [
+     *   { type: 'heading', content: 'Donate to access this story.' },
+     *   { type: 'button',  content: 'See Donation Options', variant: 'primary', onClick: openDonate },
+     * ]
+     */
+    paywallTopSlot?: PaywallSlotItem[] | HTMLElement | ((container: HTMLElement) => void) | Record<string, unknown>;
     /** Called when the user is granted access to the article */
     onAccessGranted?: () => void;
     /**
@@ -174,13 +232,15 @@ export interface SDKTheme {
     /** Font family for all SDK UI elements */
     fontFamily?: string;
 }
-export interface ResolvedConfig extends Required<Omit<SDKConfig, 'paywallTemplate' | 'onAccessGranted' | 'onStateChange' | 'onReady' | 'onLoginRequired' | 'onPurchaseRequired' | 'onInsufficientCredits' | 'onPurchased' | 'onUserLogin' | 'onUserLogout' | 'onError' | 'theme'>> {
+export interface ResolvedConfig extends Required<Omit<SDKConfig, 'paywallTopSlot' | 'reactDOM' | 'onAccessGranted' | 'onStateChange' | 'onReady' | 'onLoginRequired' | 'onPurchaseRequired' | 'onInsufficientCredits' | 'onPurchased' | 'onUserLogin' | 'onUserLogout' | 'onError' | 'theme'>> {
     articleUrl: string;
     hostName: string;
     pageTitle: string;
     apiBaseUrl: string;
     accountsUrl: string;
-    paywallTemplate?: string;
+    paywallMode: 'inline' | 'overlay';
+    paywallTopSlot?: SDKConfig['paywallTopSlot'];
+    reactDOM?: ReactDOMAdapter;
     onAccessGranted?: () => void;
     onStateChange?: (state: SDKState) => void;
     onReady?: (state: SDKState) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentcredits/sdk",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "Content Credits JS SDK — drop-in paywall and comments for any website",
   "author": "Content Credits",
   "license": "Apache-2.0",