@adviverse/react 1.0.0

package/README.md

@@ -0,0 +1,55 @@
+# @adviverse/react
+
+React components for [Adviverse](https://adviverse.com) ad slots. One import — no `dangerouslySetInnerHTML`, no `document.currentScript` workarounds, no manual script loading.
+
+```bash
+npm i @adviverse/react
+```
+
+## Quick start
+
+```tsx
+import { AdSlot } from '@adviverse/react';
+
+export function Sidebar() {
+  return <AdSlot tag="tk_80f77ad8d23bdbd927" sizes="300x600" style={{ width: 300, height: 600 }} />;
+}
+```
+
+Size the slot with `style`/`className` (or pass `sizes`) — the ad matches the box. That's the whole integration. The SDK loads once, lazily; slots tear down on unmount.
+
+## Next.js (App Router)
+
+Refill slots on client-side navigation with `<AdRefresh>`:
+
+```tsx
+'use client';
+import { usePathname } from 'next/navigation';
+import { AdRefresh } from '@adviverse/react';
+
+// render once in app/layout.tsx
+export function Ads() { return <AdRefresh routeKey={usePathname()} />; }
+```
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `<AdSlot tag sizes? style? />` | A single ad slot. `sizes`: `"300x250"`, a list `"160x600,300x600"`, or `"fluid"`. |
+| `<AdRefresh routeKey />` | Refill slots when `routeKey` changes (SPA route change). Idempotent. |
+| `<AdScript endpoint? />` | Load the SDK once, explicitly (optional — `AdSlot` loads it lazily). |
+| `loadSdk(endpoint?)` | Promise that resolves when the SDK is ready. |
+
+## Content Security Policy
+
+If you run a CSP, allow the Adviverse hosts:
+
+```
+script-src  https://serve.adviverse.com
+img-src     https://cdn.adviverse.com https://serve.adviverse.com data:
+connect-src https://serve.adviverse.com
+```
+
+## Debugging
+
+Add `?adviverse_debug=1` to the URL (or set `window.ADVIVERSE_DEBUG = true`) to console-log each request, the resolved size, and any no-fill reason. Use the reserved tag `tk_test` to render a labeled test ad that always fills — verify your integration before a campaign is live.

package/dist/index.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+var DEFAULT_ENDPOINT = "https://serve.adviverse.com";
+var loadPromise = null;
+function loadSdk(endpoint) {
+  if (typeof window === "undefined" || typeof document === "undefined") return Promise.resolve();
+  if (window.adviverse && window.adviverse.render) return Promise.resolve();
+  if (loadPromise) return loadPromise;
+  const base = (endpoint || window.ADVIVERSE_ENDPOINT || DEFAULT_ENDPOINT).replace(/\/$/, "");
+  loadPromise = new Promise((resolve, reject) => {
+    const existing = document.querySelector("script[data-adviverse-sdk]");
+    if (existing) {
+      if (window.adviverse && window.adviverse.render) return resolve();
+      existing.addEventListener("load", () => resolve());
+      existing.addEventListener("error", () => reject(new Error("adviverse sdk failed to load")));
+      return;
+    }
+    const s = document.createElement("script");
+    s.async = true;
+    s.src = base + "/sdk.js";
+    s.crossOrigin = "anonymous";
+    s.setAttribute("data-adviverse-sdk", "1");
+    s.onload = () => resolve();
+    s.onerror = () => reject(new Error("adviverse sdk failed to load"));
+    document.head.appendChild(s);
+  });
+  return loadPromise;
+}
+function AdSlot({ tag, sizes, endpoint, ...rest }) {
+  const ref = react.useRef(null);
+  react.useEffect(() => {
+    let dead = false;
+    const el = ref.current;
+    loadSdk(endpoint).then(() => {
+      if (dead || !el) return;
+      window.adviverse?.render?.(el, { tag, sizes });
+    }).catch(() => {
+    });
+    return () => {
+      dead = true;
+      if (el) window.adviverse?.destroy?.(el);
+    };
+  }, [tag, sizes, endpoint]);
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { ref, "data-tag": tag, "data-sizes": sizes, ...rest });
+}
+function AdScript({ endpoint }) {
+  react.useEffect(() => {
+    loadSdk(endpoint).catch(() => {
+    });
+  }, [endpoint]);
+  return null;
+}
+function AdRefresh({ routeKey }) {
+  react.useEffect(() => {
+    window.adviverse?.refresh?.();
+  }, [routeKey]);
+  return null;
+}
+
+exports.AdRefresh = AdRefresh;
+exports.AdScript = AdScript;
+exports.AdSlot = AdSlot;
+exports.loadSdk = loadSdk;

package/dist/index.d.cts

@@ -0,0 +1,71 @@
+import * as react from 'react';
+import { HTMLAttributes, CSSProperties } from 'react';
+
+/**
+ * @adviverse/react — drop-in React components for Adviverse ad slots.
+ *
+ *   import { AdSlot } from '@adviverse/react';
+ *   <AdSlot tag="tk_…" sizes="300x250" style={{ width: 300, height: 250 }} />
+ *
+ * No dangerouslySetInnerHTML, no document.currentScript workarounds, no manual
+ * script loading. The SDK is loaded once (lazily), each slot fills the box you
+ * size, and slots are torn down on unmount.
+ */
+type AdviverseGlobal = {
+    render?: (el: HTMLElement, opts: {
+        tag: string;
+        sizes?: string;
+    }) => Promise<unknown>;
+    destroy?: (el: HTMLElement) => void;
+    refresh?: (root?: HTMLElement | Document) => Promise<{
+        filled: string[];
+        nofill: string[];
+        skipped: string[];
+    }>;
+    ready?: (cb: () => void) => void;
+    version?: string;
+};
+declare global {
+    interface Window {
+        adviverse?: AdviverseGlobal;
+        ADVIVERSE_ENDPOINT?: string;
+        ADVIVERSE_DEBUG?: boolean;
+    }
+}
+/** Load the Adviverse SDK once (idempotent). Resolves when it's ready. */
+declare function loadSdk(endpoint?: string): Promise<void>;
+interface AdSlotProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** Placement tag key, e.g. "tk_80f77ad8d23bdbd927". */
+    tag: string;
+    /**
+     * Explicit size(s): "300x250", a comma list "160x600,300x600", or "fluid"
+     * (fill the container width, server picks the height). Omit to size from the
+     * element's own CSS box.
+     */
+    sizes?: string;
+    /** Size the box here (or via className) — the ad matches it. */
+    style?: CSSProperties;
+    endpoint?: string;
+}
+/**
+ * A single ad slot. Size it with `style`/`className` (or pass `sizes`); the SDK
+ * fills the box and tears down on unmount.
+ */
+declare function AdSlot({ tag, sizes, endpoint, ...rest }: AdSlotProps): react.JSX.Element;
+/**
+ * Loads the SDK once, explicitly (optional — <AdSlot> loads it lazily too). Handy
+ * in a root layout if you prefer the loader mounted up front.
+ */
+declare function AdScript({ endpoint }: {
+    endpoint?: string;
+}): null;
+/**
+ * Refill ad slots after a client-side route change (SPA). Pass a value that
+ * changes per route — e.g. Next.js App Router: `<AdRefresh routeKey={usePathname()} />`.
+ * Idempotent: already-filled slots are skipped and the popunder never re-arms.
+ */
+declare function AdRefresh({ routeKey }: {
+    routeKey?: string | number;
+}): null;
+
+export { AdRefresh, AdScript, AdSlot, type AdSlotProps, loadSdk };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import * as react from 'react';
+import { HTMLAttributes, CSSProperties } from 'react';
+
+/**
+ * @adviverse/react — drop-in React components for Adviverse ad slots.
+ *
+ *   import { AdSlot } from '@adviverse/react';
+ *   <AdSlot tag="tk_…" sizes="300x250" style={{ width: 300, height: 250 }} />
+ *
+ * No dangerouslySetInnerHTML, no document.currentScript workarounds, no manual
+ * script loading. The SDK is loaded once (lazily), each slot fills the box you
+ * size, and slots are torn down on unmount.
+ */
+type AdviverseGlobal = {
+    render?: (el: HTMLElement, opts: {
+        tag: string;
+        sizes?: string;
+    }) => Promise<unknown>;
+    destroy?: (el: HTMLElement) => void;
+    refresh?: (root?: HTMLElement | Document) => Promise<{
+        filled: string[];
+        nofill: string[];
+        skipped: string[];
+    }>;
+    ready?: (cb: () => void) => void;
+    version?: string;
+};
+declare global {
+    interface Window {
+        adviverse?: AdviverseGlobal;
+        ADVIVERSE_ENDPOINT?: string;
+        ADVIVERSE_DEBUG?: boolean;
+    }
+}
+/** Load the Adviverse SDK once (idempotent). Resolves when it's ready. */
+declare function loadSdk(endpoint?: string): Promise<void>;
+interface AdSlotProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** Placement tag key, e.g. "tk_80f77ad8d23bdbd927". */
+    tag: string;
+    /**
+     * Explicit size(s): "300x250", a comma list "160x600,300x600", or "fluid"
+     * (fill the container width, server picks the height). Omit to size from the
+     * element's own CSS box.
+     */
+    sizes?: string;
+    /** Size the box here (or via className) — the ad matches it. */
+    style?: CSSProperties;
+    endpoint?: string;
+}
+/**
+ * A single ad slot. Size it with `style`/`className` (or pass `sizes`); the SDK
+ * fills the box and tears down on unmount.
+ */
+declare function AdSlot({ tag, sizes, endpoint, ...rest }: AdSlotProps): react.JSX.Element;
+/**
+ * Loads the SDK once, explicitly (optional — <AdSlot> loads it lazily too). Handy
+ * in a root layout if you prefer the loader mounted up front.
+ */
+declare function AdScript({ endpoint }: {
+    endpoint?: string;
+}): null;
+/**
+ * Refill ad slots after a client-side route change (SPA). Pass a value that
+ * changes per route — e.g. Next.js App Router: `<AdRefresh routeKey={usePathname()} />`.
+ * Idempotent: already-filled slots are skipped and the popunder never re-arms.
+ */
+declare function AdRefresh({ routeKey }: {
+    routeKey?: string | number;
+}): null;
+
+export { AdRefresh, AdScript, AdSlot, type AdSlotProps, loadSdk };

package/dist/index.js

@@ -0,0 +1,61 @@
+import { useRef, useEffect } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+var DEFAULT_ENDPOINT = "https://serve.adviverse.com";
+var loadPromise = null;
+function loadSdk(endpoint) {
+  if (typeof window === "undefined" || typeof document === "undefined") return Promise.resolve();
+  if (window.adviverse && window.adviverse.render) return Promise.resolve();
+  if (loadPromise) return loadPromise;
+  const base = (endpoint || window.ADVIVERSE_ENDPOINT || DEFAULT_ENDPOINT).replace(/\/$/, "");
+  loadPromise = new Promise((resolve, reject) => {
+    const existing = document.querySelector("script[data-adviverse-sdk]");
+    if (existing) {
+      if (window.adviverse && window.adviverse.render) return resolve();
+      existing.addEventListener("load", () => resolve());
+      existing.addEventListener("error", () => reject(new Error("adviverse sdk failed to load")));
+      return;
+    }
+    const s = document.createElement("script");
+    s.async = true;
+    s.src = base + "/sdk.js";
+    s.crossOrigin = "anonymous";
+    s.setAttribute("data-adviverse-sdk", "1");
+    s.onload = () => resolve();
+    s.onerror = () => reject(new Error("adviverse sdk failed to load"));
+    document.head.appendChild(s);
+  });
+  return loadPromise;
+}
+function AdSlot({ tag, sizes, endpoint, ...rest }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    let dead = false;
+    const el = ref.current;
+    loadSdk(endpoint).then(() => {
+      if (dead || !el) return;
+      window.adviverse?.render?.(el, { tag, sizes });
+    }).catch(() => {
+    });
+    return () => {
+      dead = true;
+      if (el) window.adviverse?.destroy?.(el);
+    };
+  }, [tag, sizes, endpoint]);
+  return /* @__PURE__ */ jsx("div", { ref, "data-tag": tag, "data-sizes": sizes, ...rest });
+}
+function AdScript({ endpoint }) {
+  useEffect(() => {
+    loadSdk(endpoint).catch(() => {
+    });
+  }, [endpoint]);
+  return null;
+}
+function AdRefresh({ routeKey }) {
+  useEffect(() => {
+    window.adviverse?.refresh?.();
+  }, [routeKey]);
+  return null;
+}
+
+export { AdRefresh, AdScript, AdSlot, loadSdk };

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@adviverse/react",
+  "version": "1.0.0",
+  "description": "React components for Adviverse ad slots — <AdSlot />, <AdScript />, <AdRefresh />. One import, no dangerouslySetInnerHTML, no currentScript workarounds.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup"
+  },
+  "keywords": ["adviverse", "ads", "react", "nextjs", "adslot"],
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "react": "^18.3.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2"
+  }
+}