@adxensor/publisher-sdk 1.0.0

package/src/core/tracker.ts

@@ -0,0 +1,81 @@
+import { hasFired, markFired } from './session.js';
+import { getDevice } from './device.js';
+import type { AdXensorApi } from './api.js';
+
+/**
+ * Normalise navigator.language (e.g. "fr-FR", "en-US") to a 2-char
+ * ISO 639-1 code ("fr", "en").  Country is resolved server-side from IP.
+ */
+function getLang(): string {
+  return (navigator.language ?? 'fr').split('-')[0].toLowerCase();
+}
+
+export class Tracker {
+  constructor(
+    private readonly api: AdXensorApi,
+    private readonly siteId: string,
+    private readonly sessionId: string,
+  ) {}
+
+  // ─── Base context — attached to every event ────────────────────────────────
+  private base() {
+    return {
+      siteId:      this.siteId,
+      url:         location.href,
+      device:      getDevice(),
+      sessionId:   this.sessionId,
+      language:    getLang(),      // "fr" | "en" | "pt" | …
+      screenWidth: screen.width,   // for device analytics breakdowns
+      ts:          Date.now(),
+    };
+  }
+
+  // ─── Pageview: once per page load ─────────────────────────────────────────
+  pageview(): void {
+    this.api.sendEvent('pageview', {
+      ...this.base(),
+      referrer: document.referrer,
+    });
+  }
+
+  // ─── Impression: once per adId × session ──────────────────────────────────
+  impression(adId: string, slotId: string, impressionToken: string): void {
+    const key = `imp:${adId}:${this.sessionId}`;
+    if (hasFired(key)) return;
+    markFired(key);
+    this.api.sendEvent('impression', {
+      ...this.base(),
+      adId,
+      slotId,
+      impressionToken,
+    });
+  }
+
+  // ─── Click: deduplicated within 500 ms window per ad ─────────────────────
+  click(adId: string, slotId: string, clickToken: string): void {
+    const tsKey = `clk_ts:${adId}`;
+    try {
+      const last = parseInt(sessionStorage.getItem(tsKey) || '0', 10);
+      if (Date.now() - last < 500) return; // double-click guard
+      sessionStorage.setItem(tsKey, String(Date.now()));
+    } catch { /* ignore */ }
+    this.api.sendEvent('click', {
+      ...this.base(),
+      adId,
+      slotId,
+      clickToken,
+    });
+  }
+
+  // ─── View: once per adId × session (50% visible for ≥1 s) ────────────────
+  view(adId: string, slotId: string): void {
+    const key = `view:${adId}:${this.sessionId}`;
+    if (hasFired(key)) return;
+    markFired(key);
+    this.api.sendEvent('view', {
+      ...this.base(),
+      adId,
+      slotId,
+    });
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,112 @@
+// ─── Ad formats ───────────────────────────────────────────────────────────────
+export type AdFormat =
+  | '728x90'   // leaderboard
+  | '970x90'   // super leaderboard
+  | '970x250'  // billboard
+  | '300x250'  // medium rectangle
+  | '300x600'  // half page
+  | '160x600'  // wide skyscraper
+  | '320x50'   // mobile banner
+  | '320x100'  // large mobile banner
+  | '468x60'   // full banner
+  | 'auto'
+  | (string & {}); // allow arbitrary "WxH" strings without losing union hints
+
+/** @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';
+
+// ─── SDK configuration ────────────────────────────────────────────────────────
+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;
+}
+
+// ─── Per-slot overrides ───────────────────────────────────────────────────────
+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;
+}
+
+// ─── Ad serve request ─────────────────────────────────────────────────────────
+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;
+}
+
+// ─── Event payloads ───────────────────────────────────────────────────────────
+/**
+ * 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;
+}

package/src/embed.ts

@@ -0,0 +1,96 @@
+/**
+ * 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>
+ */
+
+import { AdXensor } from './core/AdXensor.js';
+import type { SlotOptions } from './core/types.js';
+
+type QueueEntry = [keyof AdXensor, ...unknown[]] | Record<string, unknown>;
+
+// Expose constructor for advanced users
+(window as any).AdXensor = AdXensor;
+
+function bootstrap(): void {
+  const script =
+    (document.currentScript as HTMLScriptElement | null) ??
+    document.querySelector<HTMLScriptElement>('script[data-ad-client]');
+
+  if (!script) {
+    console.error('[AdXensor] Cannot find script tag with data-ad-client');
+    return;
+  }
+
+  const siteId = script.dataset.adClient;
+  if (!siteId) {
+    console.error('[AdXensor] data-ad-client is required');
+    return;
+  }
+
+  const adx = AdXensor.getInstance({
+    siteId,
+    apiKey:   script.dataset.apiKey,
+    apiUrl:   script.dataset.apiUrl,
+    debug:    script.dataset.debug !== undefined,
+    lazyLoad: script.dataset.lazyLoad !== 'false', // lazy by default
+  });
+
+  // Drain pre-load queue
+  const queue: QueueEntry[] = Array.isArray((window as any).adxensor)
+    ? (window as any).adxensor
+    : [];
+
+  for (const entry of queue) {
+    if (Array.isArray(entry)) {
+      const [method, ...args] = entry;
+      if (method === 'push') adx.push(args[0] as SlotOptions ?? {});
+    } else {
+      // plain push({}) call
+      adx.push(entry as SlotOptions);
+    }
+  }
+
+  // Replace the array with a live proxy so future .push() calls work
+  (window as any).adxensor = {
+    push(options: SlotOptions = {}) {
+      adx.push(options);
+    },
+  };
+
+  adx.init();
+
+  if (script.dataset.debug !== undefined) (window as any)._adx = adx;
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', bootstrap);
+} else {
+  bootstrap();
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+// ─── Main class (primary entrypoint) ──────────────────────────────────────────
+export { AdXensor }    from './core/AdXensor.js';
+
+// ─── Lower-level building blocks (advanced / custom integrations) ─────────────
+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';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+export type {
+  AdXensorConfig,
+  SlotOptions,
+  SlotState,
+  AdFormat,
+  AdSize,           // deprecated alias for AdFormat — kept for backwards compat
+  DeviceType,
+  AdResponse,
+  ServeRequest,
+  AdEventPayload,
+  PageviewPayload,
+} from './core/types.js';