@adzenai/core

Shared types and utilities for the Adzen SDK. Used as a foundation by @adzenai/ai, @adzenai/static, and other channel packages.

Install

npm install @adzenai/core

Quick Start

import {
  type AdzenPlacement,
  type AdzenDecision,
  type TrackingInfo,
  observeViewability,
  registerErrorSink,
  safeRun,
  uuidv4,
  ensureTid,
} from "@adzenai/core";

Exports

Types

| Type | Description | | --- | --- | | AdzenPlacement | Ad placement data (headline, CTA, destination URL, creative, tracking URLs) | | AdzenDecision | API response wrapper ("serve" or "no_match" with optional placement) | | TrackingInfo | Render/view/click tracking URLs | | AdzenBaseConfig | Shared config interface (apiKey, endpointUrl, timeoutMs) |

Static-channel types are also exported: DecisionRequest, Decision, Creative, SlotSpec, BannerCreative, NativeCreative, and more.

Error Handling

| Export | Description | | --- | --- | | registerErrorSink(fn) | Register a callback for all SDK errors | | reportError(error) | Report an error to registered sinks | | safeRun(fn) | Execute synchronous code with automatic error reporting | | safeRunAsync(fn) | Execute async code with automatic error reporting |

Session

| Export | Description | | --- | --- | | uuidv4() | Generate a random UUID v4 | | readTid() | Read the persistent tracking ID from localStorage | | ensureTid() | Read or create a persistent tracking ID |

Viewability

| Export | Description | | --- | --- | | observeViewability(options) | Track element visibility using IntersectionObserver with a time threshold |

import { observeViewability } from "@adzenai/core";

const cleanup = observeViewability({
  element: adCardRef.current,
  thresholdMs: 1000,
  onViewed: () => fireImpression(),
});

License

MIT