universal-ad-loader 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,281 @@
+// Tipi di UAL (Universal Ad Loader). Scritti a mano: la validazione vera resta lo schema JSON
+// (schema/ual-config.schema.json); un test verifica che gli esempi passino entrambi.
+
+export type Size = [width: number, height: number];
+export type Device = 'desktop' | 'tablet' | 'mobile';
+
+// ---------- configurazione ----------
+
+export interface ConsentConfig {
+  /** `tcf` legge la CMP del sito; `none` = consenso non necessario. */
+  mode?: 'tcf' | 'none';
+  /** Attesa massima della scelta dell'utente (ms). Default 4000. */
+  timeoutMs?: number;
+  /** Attesa massima che la CMP compaia (ms). Default 1500. */
+  cmpWaitMs?: number;
+  /** Per quanto continuare a cercare una CMP che arriva in ritardo (ms). Default 30000. */
+  lateWatchMs?: number;
+  /** Purpose TCF necessarie perché il consenso sia "concesso". Default [1]. */
+  requiredPurposes?: number[];
+  /** ID del tuo ad server nella GVL IAB, se registrato. */
+  vendorId?: number;
+}
+
+export interface LazyConfig {
+  enabled?: boolean;
+  /** Distanza di anticipo, es. "200px". */
+  fetchMargin?: `${number}px` | `${number}%`;
+}
+
+export interface ViewabilityConfig {
+  /** Quota di pixel visibili (0–1). Default 0.5 (MRC). */
+  threshold?: number;
+  /** Durata continua (ms). Default 1000 (MRC). */
+  durationMs?: number;
+}
+
+export type TargetingValue = string | number | boolean | Array<string | number>;
+export type Targeting = Record<string, TargetingValue>;
+
+/** `optional`: attende la CMP. `required`: salta se manca il consenso. `contextual`: non attende la CMP. */
+export type ProviderConsent = 'optional' | 'required' | 'contextual';
+
+interface ProviderBase {
+  consent?: ProviderConsent;
+  /** Timeout del provider (ms); vuoto = `providerTimeoutMs` del sito. */
+  timeoutMs?: number;
+}
+
+export interface JsonProvider extends ProviderBase {
+  adapter: 'json';
+  endpoint: string;
+  headers?: Record<string, string>;
+  withCredentials?: boolean;
+  /** Nome di una funzione globale che adatta la risposta del server al formato UAL. */
+  map?: string;
+}
+
+export interface IframeProvider extends ProviderBase {
+  adapter: 'iframe';
+  /** URL del banner. Variabili: {params.x} {width} {height} {site} {slot} {device} {cb} {page.url} {page.ref} {consent.tcString} */
+  url: string;
+  sandbox?: string;
+}
+
+export interface ReviveProvider extends ProviderBase {
+  adapter: 'revive';
+  server: string;
+  deliveryPath?: string;
+}
+
+export interface ReviveAsyncProvider extends ProviderBase {
+  adapter: 'revive-async';
+  server: string;
+  reviveId: string;
+  deliveryPath?: string;
+  fillTimeoutMs?: number;
+}
+
+export interface GptProvider extends ProviderBase {
+  adapter: 'gpt';
+  /** Template: {network} {site} {slot} {section} {params.x} */
+  adUnitPath: string;
+  network?: string;
+  singleRequest?: boolean;
+  nonPersonalizedWithoutConsent?: boolean;
+  src?: string;
+  fillTimeoutMs?: number;
+}
+
+export interface AdsenseProvider extends ProviderBase {
+  adapter: 'adsense';
+  client: `ca-pub-${number}`;
+  test?: boolean;
+  fillTimeoutMs?: number;
+}
+
+export type Creative = {
+  id?: string;
+  type?: 'image' | 'html';
+  alt?: string;
+  width: number;
+  height: number;
+  clickUrl?: string;
+  /** Più alto = più frequente. */
+  weight?: number;
+  /** Solo in questi slot (vuoto = tutti). */
+  slots?: string[];
+  devices?: Device[];
+  /** Date AAAA-MM-GG (la data "to" è inclusa). */
+  from?: string;
+  to?: string;
+} & ({ src: string; html?: string } | { html: string; src?: string });
+
+export interface HouseProvider extends ProviderBase {
+  adapter: 'house';
+  creatives: [Creative, ...Creative[]];
+}
+
+export type ProviderConfig =
+  | JsonProvider | IframeProvider | ReviveProvider | ReviveAsyncProvider
+  | GptProvider | AdsenseProvider | HouseProvider;
+
+export interface SizeMapping {
+  /** Larghezza minima del viewport (px). Metti sempre una fascia con 0. */
+  minWidth: number;
+  sizes: Size[];
+}
+
+export type ProviderRef<P extends string = string> =
+  | P
+  | { id: P; params?: Record<string, unknown> };
+
+export interface SlotConfig<P extends string = string> {
+  sizes?: Size[];
+  sizeMapping?: SizeMapping[];
+  /** Waterfall: i provider vengono provati in ordine. */
+  providers: [ProviderRef<P>, ...ProviderRef<P>[]];
+  label?: string;
+  minHeight?: number;
+  lazy?: boolean;
+  collapseEmpty?: boolean;
+  refreshSec?: number;
+  maxRefresh?: number;
+  enabled?: boolean;
+  viewability?: ViewabilityConfig;
+}
+
+export interface PageRule {
+  /** Espressione regolare sul percorso della pagina. */
+  match: string;
+  disable?: string[];
+  enable?: string[];
+  targeting?: Targeting;
+  slots?: Record<string, Partial<SlotConfig>>;
+}
+
+/**
+ * `P` = id dei provider definiti, `S` = id ammessi nei waterfall degli slot (di default gli stessi).
+ * `defineConfig` li separa per far segnalare un provider inesistente.
+ */
+export interface UalConfig<P extends string = string, S extends string = P> {
+  /** ID del sito, inviato agli adapter. */
+  site: string;
+  debug?: boolean;
+  consent?: ConsentConfig;
+  lazy?: LazyConfig;
+  viewability?: ViewabilityConfig;
+  collapseEmpty?: boolean;
+  providerTimeoutMs?: number;
+  targeting?: Targeting;
+  providers: Record<P, ProviderConfig>;
+  slots: Record<string, SlotConfig<S>>;
+  pageRules?: PageRule[];
+}
+
+/**
+ * Identità tipizzata: dà completamento e controllo dei tipi, e segnala un provider inesistente
+ * nel waterfall di uno slot.
+ */
+export function defineConfig<const P extends string>(config: UalConfig<P, NoInfer<P>>): UalConfig<P>;
+
+// ---------- istanza ----------
+
+export interface Consent {
+  gdprApplies?: boolean;
+  tcString: string;
+  purposes: Record<string, boolean>;
+  vendorConsents?: Record<string, boolean>;
+  granted: boolean;
+  /** `pending` finché la CMP non risponde; `no-cmp` e `timeout` = consenso non concesso. */
+  source: 'tcf' | 'none' | 'no-cmp' | 'timeout' | 'pending';
+}
+
+export interface SlotInfo {
+  slot: string;
+  id: string;
+  provider?: string;
+  status: string;
+  el: HTMLElement;
+}
+
+export interface UalEventMap {
+  ready: { site: string };
+  consent: Consent;
+  slotRegistered: SlotInfo;
+  slotRequested: { slot: string; id: string; provider: string };
+  slotRendered: SlotInfo & { width?: number; height?: number; meta?: unknown };
+  slotEmpty: SlotInfo;
+  slotViewable: SlotInfo;
+  slotClick: SlotInfo;
+  error: { provider?: string; slot?: string; error: Error };
+}
+
+export interface AdapterSlot {
+  id: string;
+  name: string;
+  /** Contenitore in cui un adapter che rende da solo (`fill`) inserisce l'annuncio. */
+  el: HTMLElement;
+  sizes: Size[];
+  params: Record<string, any>;
+}
+
+export interface AdapterContext {
+  site: string;
+  page: { url: string; path: string; ref: string; title: string };
+  device: Device;
+  viewport: { w: number; h: number };
+  targeting: Targeting;
+  consent: Consent;
+  debug: boolean;
+}
+
+export interface AdResult {
+  type?: 'image' | 'html' | 'url';
+  src?: string;
+  html?: string;
+  url?: string;
+  width: number;
+  height: number;
+  clickUrl?: string;
+  trackers?: { impression?: string[]; viewable?: string[]; click?: string[] };
+  sandbox?: string;
+}
+
+/** Adapter personalizzato: o `request` (UAL rende l'annuncio) o `fill` (rende da solo in `slot.el`). */
+export interface Adapter {
+  init?(providerConfig: any, ctx: AdapterContext): void | Promise<void>;
+  request?(slots: AdapterSlot[], providerConfig: any, ctx: AdapterContext): Promise<Record<string, AdResult | null>>;
+  fill?(slots: AdapterSlot[], providerConfig: any, ctx: AdapterContext): Promise<Record<string, { filled: boolean; width?: number; height?: number; meta?: unknown }>>;
+  destroy?(slot: { id: string; el: HTMLElement }, providerConfig: any): void;
+}
+
+export interface Ual {
+  readonly version: string;
+  /** Avvia UAL con una configurazione (oggetto) o l'URL del JSON. Una sola volta per istanza. */
+  init(source: UalConfig | string): Promise<void>;
+  isInitialized(): boolean;
+  /** Promessa dell'init avviato (null se mai avviato). */
+  whenReady(): Promise<void> | null;
+  on<K extends keyof UalEventMap>(event: K, handler: (data: UalEventMap[K], event: K) => void): () => void;
+  on(event: '*', handler: (data: any, event: string) => void): () => void;
+  off(event: string, handler: (...args: any[]) => void): void;
+  registerAdapter(name: string, adapter: Adapter): void;
+  /** Targeting key-value. Vale anche prima dell'init e dopo pageView(); `null` rimuove la chiave. */
+  setTargeting(targeting: Record<string, TargetingValue | null | undefined>): void;
+  /** Ricarica gli slot indicati (tutti se senza argomenti). */
+  refresh(names?: string[]): void;
+  /** Da chiamare a ogni cambio di pagina lato client: ricalcola regole per pagina e slot. */
+  pageView(): void;
+  getSlots(): SlotInfo[];
+  getConsent(): Consent;
+  debug(on: boolean): void;
+}
+
+export const version: string;
+
+/** Nuova istanza, senza toccare window né document: sicuro da importare sul server. */
+export function createUal(): Ual;
+
+/** Istanza condivisa della pagina. Solo nel browser: sul server lancia un errore esplicito. */
+export function getUal(): Ual;