@adxensor/publisher-sdk 1.0.0

package/dist/npm/types/core/tracker.d.ts

@@ -0,0 +1,12 @@
+import type { AdXensorApi } from './api.js';
+export declare class Tracker {
+    private readonly api;
+    private readonly siteId;
+    private readonly sessionId;
+    constructor(api: AdXensorApi, siteId: string, sessionId: string);
+    private base;
+    pageview(): void;
+    impression(adId: string, slotId: string, impressionToken: string): void;
+    click(adId: string, slotId: string, clickToken: string): void;
+    view(adId: string, slotId: string): void;
+}

package/dist/npm/types/core/types.d.ts

@@ -0,0 +1,87 @@
+export type AdFormat = '728x90' | '970x90' | '970x250' | '300x250' | '300x600' | '160x600' | '320x50' | '320x100' | '468x60' | 'auto' | (string & {});
+/** @deprecated Use AdFormat */
+export type AdSize = AdFormat;
+export type DeviceType = 'mobile' | 'tablet' | 'desktop';
+/** State machine written on the <ins> element via data-adx-state */
+export type SlotState = 'loading' | 'filled' | 'empty' | 'error';
+export interface AdXensorConfig {
+    /** Publisher site ID — required */
+    siteId: string;
+    /** Optional API key for authenticated publishers */
+    apiKey?: string;
+    /** Override the default API base URL */
+    apiUrl?: string;
+    /** Log debug info to console (default: false) */
+    debug?: boolean;
+    /** Lazy-load ads when they approach the viewport (default: true) */
+    lazyLoad?: boolean;
+}
+export interface SlotOptions {
+    /** Named slot identifier (overrides data-ad-slot attribute) */
+    slotId?: string;
+    /** Ad format / size (overrides data-ad-format attribute) */
+    format?: AdFormat;
+    /** Override lazy loading for this slot only */
+    lazy?: boolean;
+}
+export interface ServeRequest {
+    siteId: string;
+    slotId: string;
+    size: string;
+    device: DeviceType;
+    url: string;
+    referrer: string;
+    /**
+     * BCP-47 tag from navigator.language, normalised to 2-char ISO 639-1.
+     * e.g. "fr", "en", "es" — used for language targeting by ads_core.
+     */
+    language: string;
+    screenWidth: number;
+    sessionId: string;
+}
+export interface AdResponse {
+    adId: string;
+    campaignId: string;
+    type: 'image' | 'html';
+    imageUrl?: string;
+    htmlContent?: string;
+    /**
+     * Full click URL returned by ads_core (e.g. https://ads.adxensor.com/v1/click/TOKEN).
+     * Use this directly as the <a> href — ads_core handles the redirect internally.
+     */
+    clickHref: string;
+    width: number;
+    height: number;
+    altText: string;
+    /** Event ID used for POST /v1/events/impression */
+    impressionToken: string;
+    /** Event ID used for POST /v1/events/click */
+    clickToken: string;
+}
+/**
+ * Base fields sent with EVERY event (impression, click, view, pageview).
+ * Country is resolved server-side from IP (geoip-lite) and NOT sent by the SDK.
+ */
+interface BaseEventPayload {
+    siteId: string;
+    sessionId: string;
+    url: string;
+    device: DeviceType;
+    /**
+     * Normalised 2-char ISO 639-1 language code from navigator.language.
+     * e.g. "fr", "en", "es", "pt"
+     */
+    language: string;
+    screenWidth: number;
+    ts: number;
+}
+export interface PageviewPayload extends BaseEventPayload {
+    referrer: string;
+}
+export interface AdEventPayload extends BaseEventPayload {
+    adId: string;
+    slotId: string;
+    impressionToken?: string;
+    clickToken?: string;
+}
+export {};

package/dist/npm/types/embed.d.ts

@@ -0,0 +1,32 @@
+/**
+ * CDN entry point — loaded via <script> tag (IIFE bundle).
+ *
+ * ── Minimal snippet (auto-fill all <ins class="adxensor"> on load) ───────────
+ *
+ *   <script async
+ *     src="https://cdn.adxensor.com/tag.js"
+ *     data-ad-client="pub-XXXXXXXX">
+ *   </script>
+ *
+ *   <ins class="adxensor"
+ *        style="display:block"
+ *        data-ad-slot="header-banner"
+ *        data-ad-format="728x90">
+ *   </ins>
+ *
+ * ── AdSense-style push (fill one slot at a time) ─────────────────────────────
+ *
+ *   <ins class="adxensor" style="display:block"
+ *        data-ad-slot="sidebar" data-ad-format="300x250"></ins>
+ *   <script>
+ *     (window.adxensor = window.adxensor || []).push({});
+ *   </script>
+ *
+ * ── Pre-load queue (before script is ready) ──────────────────────────────────
+ *
+ *   <script>
+ *     window.adxensor = window.adxensor || [];
+ *     window.adxensor.push({});
+ *   </script>
+ */
+export {};

package/dist/npm/types/index.d.ts

@@ -0,0 +1,9 @@
+export { AdXensor } from './core/AdXensor.js';
+export { AdXensorApi } from './core/api.js';
+export { Tracker } from './core/tracker.js';
+export { AdSlot } from './core/AdSlot.js';
+export { renderAd } from './core/renderer.js';
+export { getDevice, resolveSize } from './core/device.js';
+export { getSessionId, hasFired, markFired } from './core/session.js';
+export type { AdXensorConfig, SlotOptions, SlotState, AdFormat, AdSize, // deprecated alias for AdFormat — kept for backwards compat
+DeviceType, AdResponse, ServeRequest, AdEventPayload, PageviewPayload, } from './core/types.js';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@adxensor/publisher-sdk",
+  "version": "1.0.0",
+  "description": "AdXensor publisher SDK — CDN tag and npm package for ad serving, impression, click, and view tracking",
+  "license": "UNLICENSED",
+  "private": false,
+  "type": "module",
+  "main": "./dist/npm/cjs/index.cjs",
+  "module": "./dist/npm/esm/index.js",
+  "types": "./dist/npm/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/npm/esm/index.js",
+      "require": "./dist/npm/cjs/index.cjs",
+      "types": "./dist/npm/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "scripts": {
+    "build": "npm run build:cdn && npm run build:npm",
+    "build:cdn": "node scripts/build-cdn.mjs",
+    "build:npm": "node scripts/build-npm.mjs",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "esbuild": "^0.21.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/core/AdSlot.ts

@@ -0,0 +1,169 @@
+import type { AdXensorApi } from './api.js';
+import type { Tracker } from './tracker.js';
+import type { SlotOptions } from './types.js';
+import { getDevice, resolveSize } from './device.js';
+import { renderAd } from './renderer.js';
+
+const VIEW_THRESHOLD = 0.5;  // 50% visible
+const VIEW_DURATION  = 1000; // 1 second held in view = fires view event
+
+export class AdSlot {
+  private readonly slotId: string;
+  private observer:  IntersectionObserver | null = null;
+  private viewTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private readonly el:        HTMLElement,
+    private readonly api:       AdXensorApi,
+    private readonly tracker:   Tracker,
+    private readonly siteId:    string,
+    private readonly sessionId: string,
+    private readonly options:   SlotOptions = {},
+  ) {
+    // AdSense-style: data-ad-slot. Falls back to element id or a random id.
+    this.slotId =
+      options.slotId ??
+      el.dataset.adSlot ??                                   // data-ad-slot="banner-top"
+      (el.id || `adx-${Math.random().toString(36).slice(2, 9)}`);
+  }
+
+  // ─── Load entry point ─────────────────────────────────────────────────────
+
+  load(lazy = true): void {
+    if (this.el.dataset.adxState) return; // idempotent — already in-flight or done
+
+    if (lazy && typeof IntersectionObserver !== 'undefined') {
+      this.watchForEntry();
+    } else {
+      void this.fetch();
+    }
+  }
+
+  // ─── Lazy entry: wait until element is near the viewport ─────────────────
+
+  private watchForEntry(): void {
+    const io = new IntersectionObserver(
+      (entries) => {
+        if (entries[0]?.isIntersecting) {
+          io.disconnect();
+          void this.fetch();
+        }
+      },
+      { rootMargin: '200px', threshold: 0 },
+    );
+    io.observe(this.el);
+  }
+
+  // ─── Fetch ad from API ────────────────────────────────────────────────────
+
+  private async fetch(): Promise<void> {
+    if (this.el.dataset.adxState) return; // double-check after async gap
+    this.setState('loading');
+
+    try {
+      // AdSense-style: data-ad-format. Falls back to options.format then 'auto'.
+      const size = resolveSize(
+        this.options.format ?? this.el.dataset.adFormat ?? 'auto',
+        this.el,
+      );
+      const [w, h] = size.split('x').map(Number);
+
+      // Reserve exact dimensions to prevent layout shift (CLS)
+      if (w && h) {
+        this.el.style.width     = `${w}px`;
+        this.el.style.maxWidth  = '100%';
+        this.el.style.minHeight = `${h}px`;
+      }
+
+      const ad = await this.api.serveAd({
+        siteId:      this.siteId,
+        slotId:      this.slotId,
+        size,
+        device:      getDevice(),
+        url:         location.href,
+        referrer:    document.referrer,
+        // Normalise "fr-FR" → "fr"; server resolves country from IP separately
+        language:    (navigator.language ?? 'fr').split('-')[0].toLowerCase(),
+        screenWidth: screen.width,
+        sessionId:   this.sessionId,
+      });
+
+      if (!ad) {
+        this.setState('empty');
+        this.el.style.display = 'none';
+        return;
+      }
+
+      // ads_core provides the full click URL directly (handles redirect internally)
+      renderAd(this.el, ad, ad.clickHref);
+      this.setState('filled');
+
+      // Click tracking — passive: true because we never call preventDefault
+      this.el.addEventListener('click', (e) => {
+        if ((e.target as HTMLElement).closest('[data-adx-click]')) {
+          this.tracker.click(ad.adId, this.slotId, ad.clickToken);
+        }
+      }, { passive: true });
+
+      // Impression fires immediately after render (once per adId × session)
+      this.tracker.impression(ad.adId, this.slotId, ad.impressionToken);
+
+      // View fires after ≥50% visible for ≥1s (IAB standard)
+      this.watchVisibility(ad.adId, this.slotId);
+
+    } catch {
+      this.setState('error');
+      this.el.style.display = 'none';
+    }
+  }
+
+  // ─── Viewability (IAB MRC standard) ──────────────────────────────────────
+
+  private watchVisibility(adId: string, slotId: string): void {
+    if (typeof IntersectionObserver === 'undefined') {
+      this.tracker.view(adId, slotId); // fallback: fire immediately
+      return;
+    }
+
+    this.observer = new IntersectionObserver(
+      ([entry]) => {
+        if (!entry) return;
+
+        if (entry.intersectionRatio >= VIEW_THRESHOLD) {
+          if (this.viewTimer === null) {
+            this.viewTimer = setTimeout(() => {
+              this.tracker.view(adId, slotId);
+              this.disconnect(); // stop observing once view is counted
+            }, VIEW_DURATION);
+          }
+        } else {
+          // Left viewport before 1s — reset timer
+          if (this.viewTimer !== null) {
+            clearTimeout(this.viewTimer);
+            this.viewTimer = null;
+          }
+        }
+      },
+      { threshold: [VIEW_THRESHOLD] },
+    );
+
+    this.observer.observe(this.el);
+  }
+
+  // ─── State machine ────────────────────────────────────────────────────────
+
+  private setState(state: 'loading' | 'filled' | 'empty' | 'error'): void {
+    this.el.dataset.adxState = state;
+  }
+
+  // ─── Cleanup ──────────────────────────────────────────────────────────────
+
+  disconnect(): void {
+    this.observer?.disconnect();
+    this.observer = null;
+    if (this.viewTimer !== null) {
+      clearTimeout(this.viewTimer);
+      this.viewTimer = null;
+    }
+  }
+}

package/src/core/AdXensor.ts

@@ -0,0 +1,136 @@
+import { AdXensorApi }   from './api.js';
+import { Tracker }       from './tracker.js';
+import { AdSlot }        from './AdSlot.js';
+import { getSessionId }  from './session.js';
+import type { AdXensorConfig, SlotOptions } from './types.js';
+
+/** ads_core public base URL — must include /v1 suffix */
+const DEFAULT_API_URL = 'https://core.adxensor.com/v1';
+
+/** Selector for unfilled <ins class="adxensor"> slots */
+const INS_SELECTOR = 'ins.adxensor:not([data-adx-state])';
+
+export class AdXensor {
+  /** One global instance per page (like AdSense). */
+  private static instance: AdXensor | null = null;
+
+  private readonly api:       AdXensorApi;
+  private readonly tracker:   Tracker;
+  private readonly sessionId: string;
+  private readonly config:    AdXensorConfig;
+  private initialized  = false;
+  private domObserver: MutationObserver | null = null;
+
+  constructor(config: AdXensorConfig) {
+    this.config    = config;
+    this.sessionId = getSessionId();
+    this.api       = new AdXensorApi(
+      config.apiUrl ?? DEFAULT_API_URL,
+      config.apiKey,
+    );
+    this.tracker = new Tracker(this.api, config.siteId, this.sessionId);
+  }
+
+  // ─── Singleton helpers ────────────────────────────────────────────────────
+
+  static getInstance(config: AdXensorConfig): AdXensor {
+    if (!AdXensor.instance) AdXensor.instance = new AdXensor(config);
+    return AdXensor.instance;
+  }
+
+  static reset(): void {
+    AdXensor.instance?.destroy();
+    AdXensor.instance = null;
+  }
+
+  // ─── Public API ───────────────────────────────────────────────────────────
+
+  /**
+   * Idempotent init — safe to call multiple times.
+   * Fires pageview, fills existing slots, watches DOM for new ones.
+   */
+  init(): this {
+    if (this.initialized) return this;
+    this.initialized = true;
+    this.tracker.pageview();
+    this.fillAll();
+    this.watchDom();
+    return this;
+  }
+
+  /** Fill every unfilled <ins class="adxensor"> currently in the DOM. */
+  fillAll(): void {
+    document.querySelectorAll<HTMLElement>(INS_SELECTOR).forEach((el) => this.fill(el));
+  }
+
+  /**
+   * AdSense-style push — fills the next unfilled slot in DOM order.
+   * Use alongside <script>(window.adxensor = window.adxensor || []).push({})</script>
+   */
+  push(options: SlotOptions = {}): void {
+    const el = document.querySelector<HTMLElement>(INS_SELECTOR);
+    if (el) this.fill(el, options);
+  }
+
+  /**
+   * Fill a specific element.
+   * No-op if the element is already loading/filled/empty/error (idempotent).
+   */
+  fill(el: HTMLElement, options: SlotOptions = {}): void {
+    if (el.dataset.adxState) return; // state machine guard
+
+    // Enforce display:block — required like AdSense
+    if (el.style.display === 'none') el.style.display = 'block';
+
+    const slot = new AdSlot(
+      el,
+      this.api,
+      this.tracker,
+      this.config.siteId,
+      this.sessionId,
+      options,
+    );
+
+    const lazy = options.lazy ?? this.config.lazyLoad ?? true;
+    slot.load(lazy);
+  }
+
+  /**
+   * Programmatic slot fill by CSS selector.
+   * Logs a warning in debug mode if the element is not found.
+   */
+  defineSlot(selector: string, options: SlotOptions = {}): void {
+    const el = document.querySelector<HTMLElement>(selector);
+    if (!el) {
+      if (this.config.debug) console.warn(`[AdXensor] defineSlot: "${selector}" not found`);
+      return;
+    }
+    this.fill(el, options);
+  }
+
+  // ─── DOM watcher (SPA support) ────────────────────────────────────────────
+
+  private watchDom(): void {
+    if (typeof MutationObserver === 'undefined') return;
+
+    this.domObserver = new MutationObserver((mutations) => {
+      for (const { addedNodes } of mutations) {
+        addedNodes.forEach((node) => {
+          if (!(node instanceof HTMLElement)) return;
+          if (node.matches('ins.adxensor') && !node.dataset.adxState) {
+            this.fill(node);
+          }
+          node.querySelectorAll<HTMLElement>(INS_SELECTOR).forEach((el) => this.fill(el));
+        });
+      }
+    });
+
+    this.domObserver.observe(document.body, { childList: true, subtree: true });
+  }
+
+  destroy(): void {
+    this.domObserver?.disconnect();
+    this.domObserver = null;
+    this.initialized = false;
+  }
+}

package/src/core/api.ts

@@ -0,0 +1,80 @@
+import type { ServeRequest, AdResponse, AdEventPayload, PageviewPayload } from './types.js';
+
+/** ads_core /v1/ad response shape */
+interface AdsCoreAdResponse {
+  creative_url:    string;
+  click_url:       string;   // full URL e.g. https://ads.adxensor.com/v1/click/TOKEN
+  impression_url:  string;   // full URL e.g. https://ads.adxensor.com/v1/impression/TOKEN
+  campaign_id:     string;
+  size:            string;   // "300x250"
+}
+
+export class AdXensorApi {
+  constructor(
+    private readonly baseUrl: string,  // e.g. "https://ads.adxensor.com/v1"
+    private readonly apiKey?: string,
+  ) {}
+
+  private headers(): Record<string, string> {
+    const h: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (this.apiKey) h['X-Publisher-Key'] = this.apiKey;
+    return h;
+  }
+
+  // ─── Fetch the best ad for a slot ─────────────────────────────────────────
+  async serveAd(req: ServeRequest): Promise<AdResponse | null> {
+    try {
+      // Map SDK params → ads_core query schema
+      const params = new URLSearchParams({ zone: req.size, site: req.siteId });
+      if (req.url)      params.set('url', req.url);
+      if (req.referrer) params.set('ref', req.referrer);
+
+      const res = await fetch(`${this.baseUrl}/ad?${params.toString()}`, {
+        method:  'GET',
+        headers: this.headers(),
+      });
+
+      // 204 = no ad available for this slot
+      if (res.status === 204 || !res.ok) return null;
+
+      const data = await res.json() as AdsCoreAdResponse;
+
+      // Extract shared event token from either tracking URL
+      const eventId = data.impression_url.split('/').pop() ?? '';
+
+      const [w, h] = (data.size ?? '300x250').split('x').map(Number);
+
+      return {
+        adId:            eventId,
+        campaignId:      data.campaign_id,
+        type:            'image',
+        imageUrl:        data.creative_url,
+        clickHref:       data.click_url,   // full URL — use directly as <a> href
+        width:           w  ?? 300,
+        height:          h  ?? 250,
+        altText:         '',
+        impressionToken: eventId,
+        clickToken:      eventId,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  // ─── Fire-and-forget event (uses sendBeacon when available) ───────────────
+  sendEvent(path: string, payload: AdEventPayload | PageviewPayload): void {
+    const url  = `${this.baseUrl}/events/${path}`;
+    const body = JSON.stringify(payload);
+
+    if (typeof navigator !== 'undefined' && navigator.sendBeacon) {
+      navigator.sendBeacon(url, new Blob([body], { type: 'application/json' }));
+    } else {
+      fetch(url, {
+        method:    'POST',
+        headers:   this.headers(),
+        body,
+        keepalive: true,
+      }).catch(() => { /* silent */ });
+    }
+  }
+}

package/src/core/device.ts

@@ -0,0 +1,31 @@
+import type { DeviceType } from './types.js';
+
+export function getDevice(): DeviceType {
+  if (typeof window === 'undefined') return 'desktop';
+  const w = window.innerWidth;
+  if (w < 768) return 'mobile';
+  if (w < 1024) return 'tablet';
+  return 'desktop';
+}
+
+/**
+ * Resolve 'auto' to a concrete size based on the container width + device.
+ * Falls back to a safe default for each device tier.
+ */
+export function resolveSize(requested: string, container: HTMLElement): string {
+  if (requested !== 'auto') return requested;
+
+  const device = getDevice();
+  const w = container.offsetWidth || window.innerWidth;
+
+  if (device === 'mobile') {
+    return w >= 320 ? '320x50' : '300x250';
+  }
+  if (device === 'tablet') {
+    return w >= 468 ? '468x60' : '300x250';
+  }
+  // desktop
+  if (w >= 728) return '728x90';
+  if (w >= 468) return '468x60';
+  return '300x250';
+}

package/src/core/renderer.ts

@@ -0,0 +1,40 @@
+import type { AdResponse } from './types.js';
+
+/**
+ * Inject the ad creative into `container`.
+ * - type 'html': raw HTML creative (rich media, animated banners)
+ * - type 'image': <a><img></a> wrapped in a click-tracked link
+ *
+ * The caller handles the click event via addEventListener; the rendered
+ * anchor uses href="#" so the tracker can intercept and open the real URL.
+ */
+export function renderAd(container: HTMLElement, ad: AdResponse, clickHref: string): void {
+  container.style.overflow = 'hidden';
+  container.style.display  = 'block';
+  container.style.lineHeight = '0'; // removes bottom gap under <img>
+
+  if (ad.type === 'html' && ad.htmlContent) {
+    container.innerHTML = ad.htmlContent;
+    return;
+  }
+
+  const a = document.createElement('a');
+  a.href   = clickHref;
+  a.target = '_blank';
+  a.rel    = 'noopener noreferrer';
+  a.setAttribute('data-adx-click', '1');
+  a.style.display = 'block';
+
+  const img = document.createElement('img');
+  img.src    = ad.imageUrl ?? '';
+  img.width  = ad.width;
+  img.height = ad.height;
+  img.alt    = ad.altText || '';
+  img.style.display  = 'block';
+  img.style.maxWidth = '100%';
+  img.loading = 'lazy';
+
+  a.appendChild(img);
+  container.innerHTML = '';
+  container.appendChild(a);
+}

package/src/core/session.ts

@@ -0,0 +1,38 @@
+const SESSION_KEY = '_adx_sid';
+const FIRED_KEY   = '_adx_fired';
+
+/** Returns (or creates) a session ID stored in sessionStorage. */
+export function getSessionId(): string {
+  try {
+    let id = sessionStorage.getItem(SESSION_KEY);
+    if (!id) {
+      id = typeof crypto !== 'undefined' && crypto.randomUUID
+        ? crypto.randomUUID()
+        : Math.random().toString(36).slice(2) + Date.now().toString(36);
+      sessionStorage.setItem(SESSION_KEY, id);
+    }
+    return id;
+  } catch {
+    // sessionStorage blocked (iframe sandbox, private mode, etc.)
+    return Math.random().toString(36).slice(2);
+  }
+}
+
+/** Returns true if this event key was already fired this session. */
+export function hasFired(key: string): boolean {
+  try {
+    const map = JSON.parse(sessionStorage.getItem(FIRED_KEY) || '{}') as Record<string, number>;
+    return key in map;
+  } catch {
+    return false;
+  }
+}
+
+/** Mark an event key as fired. */
+export function markFired(key: string): void {
+  try {
+    const map = JSON.parse(sessionStorage.getItem(FIRED_KEY) || '{}') as Record<string, number>;
+    map[key] = Date.now();
+    sessionStorage.setItem(FIRED_KEY, JSON.stringify(map));
+  } catch { /* ignore */ }
+}