vastlint-client 0.4.20

package/dist/tracking.d.ts

@@ -0,0 +1,7 @@
+import type { VastTrackableEvent, VastTrackingPlan, VastTrackingTarget, VastWrapperHop } from "./types.js";
+type TrackingSourceHop = Pick<VastWrapperHop, "index" | "url" | "xml">;
+export declare function createEmptyTrackingPlan(): VastTrackingPlan;
+export declare function buildTrackingPlan(hops: readonly TrackingSourceHop[]): VastTrackingPlan;
+export declare function selectTrackingTargets(plan: VastTrackingPlan, event: VastTrackableEvent, offset?: string): VastTrackingTarget[];
+export declare function expandTrackingUrl(url: string, macros?: Record<string, string | number>): string;
+export {};

package/dist/tracking.js

@@ -0,0 +1,161 @@
+const XML_ENTITIES = {
+    amp: "&",
+    apos: "'",
+    gt: ">",
+    lt: "<",
+    quot: '"',
+};
+const CLICK_TRACKING_TAGS = [
+    "ClickTracking",
+    "CompanionClickTracking",
+    "IconClickTracking",
+    "NonLinearClickTracking",
+];
+const CLICK_THROUGH_TAGS = [
+    "ClickThrough",
+    "CompanionClickThrough",
+    "IconClickThrough",
+    "NonLinearClickThrough",
+];
+const VIEWABILITY_TAGS = [
+    ["Viewable", "viewable"],
+    ["NotViewable", "notViewable"],
+    ["ViewUndetermined", "viewUndetermined"],
+];
+export function createEmptyTrackingPlan() {
+    return {
+        impressions: [],
+        errors: [],
+        clickTrackings: [],
+        clickThroughs: [],
+        events: [],
+    };
+}
+function normalizeWhitespace(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function decodeXmlEntities(value) {
+    return value.replace(/&(#x?[0-9a-fA-F]+|amp|apos|gt|lt|quot);/g, (_match, entity) => {
+        if (entity in XML_ENTITIES) {
+            return XML_ENTITIES[entity];
+        }
+        if (entity.startsWith("#x")) {
+            return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
+        }
+        if (entity.startsWith("#")) {
+            return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
+        }
+        return `&${entity};`;
+    });
+}
+function cleanXmlText(value, collapseWhitespace = false) {
+    const withoutCdata = value.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1");
+    const decoded = decodeXmlEntities(withoutCdata);
+    return collapseWhitespace ? normalizeWhitespace(decoded) : decoded.trim();
+}
+function extractAttribute(rawAttributes, attributeName) {
+    const match = new RegExp(`${attributeName}=("([^"]*)"|'([^']*)')`, "i").exec(rawAttributes);
+    if (!match) {
+        return "";
+    }
+    return cleanXmlText(match[2] ?? match[3] ?? "", false);
+}
+function buildTarget(kind, event, rawValue, hop, offset = null) {
+    const url = cleanXmlText(rawValue, false);
+    if (!url) {
+        return null;
+    }
+    return {
+        kind,
+        event,
+        url,
+        hopIndex: hop.index,
+        sourceUrl: hop.url,
+        offset,
+    };
+}
+function collectTagTargets(xml, tagName, kind, event, hop) {
+    const targets = [];
+    const pattern = new RegExp(`<${tagName}\\b[^>]*>([\\s\\S]*?)<\\/${tagName}>`, "gi");
+    for (const match of xml.matchAll(pattern)) {
+        const target = buildTarget(kind, event, match[1] ?? "", hop);
+        if (target) {
+            targets.push(target);
+        }
+    }
+    return targets;
+}
+function collectTrackingEvents(xml, hop) {
+    const targets = [];
+    const pattern = /<Tracking\b([^>]*)>([\s\S]*?)<\/Tracking>/gi;
+    for (const match of xml.matchAll(pattern)) {
+        const rawAttributes = match[1] ?? "";
+        const event = extractAttribute(rawAttributes, "event");
+        if (!event) {
+            continue;
+        }
+        const offset = extractAttribute(rawAttributes, "offset") || null;
+        const target = buildTarget("event", event, match[2] ?? "", hop, offset);
+        if (target) {
+            targets.push(target);
+        }
+    }
+    return targets;
+}
+export function buildTrackingPlan(hops) {
+    const plan = createEmptyTrackingPlan();
+    for (const hop of hops) {
+        plan.impressions.push(...collectTagTargets(hop.xml, "Impression", "impression", "impression", hop));
+        plan.errors.push(...collectTagTargets(hop.xml, "Error", "error", "error", hop));
+        for (const tagName of CLICK_TRACKING_TAGS) {
+            plan.clickTrackings.push(...collectTagTargets(hop.xml, tagName, "clickTracking", "clickTracking", hop));
+        }
+        for (const tagName of CLICK_THROUGH_TAGS) {
+            plan.clickThroughs.push(...collectTagTargets(hop.xml, tagName, "clickThrough", "clickThrough", hop));
+        }
+        for (const [tagName, eventName] of VIEWABILITY_TAGS) {
+            plan.events.push(...collectTagTargets(hop.xml, tagName, "event", eventName, hop));
+        }
+        plan.events.push(...collectTrackingEvents(hop.xml, hop));
+    }
+    return plan;
+}
+export function selectTrackingTargets(plan, event, offset) {
+    if (event === "impression") {
+        return [...plan.impressions];
+    }
+    if (event === "error") {
+        return [...plan.errors];
+    }
+    if (event === "clickTracking") {
+        return [...plan.clickTrackings];
+    }
+    return plan.events.filter((target) => {
+        if (target.event !== event) {
+            return false;
+        }
+        if (offset === undefined) {
+            return true;
+        }
+        return target.offset === offset;
+    });
+}
+function randomCacheBustingValue() {
+    return Math.floor(Math.random() * 100000000)
+        .toString()
+        .padStart(8, "0");
+}
+export function expandTrackingUrl(url, macros) {
+    const values = {
+        CACHEBUSTING: randomCacheBustingValue(),
+        TIMESTAMP: new Date().toISOString(),
+    };
+    for (const [key, value] of Object.entries(macros ?? {})) {
+        values[key.toUpperCase()] = String(value);
+    }
+    return url.replace(/\[([A-Z0-9_]+)\]|%%([A-Z0-9_]+)%%/gi, (match, bracketName, legacyName) => {
+        const key = String(bracketName ?? legacyName ?? "").toUpperCase();
+        const replacement = values[key];
+        return replacement === undefined ? match : encodeURIComponent(replacement);
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,374 @@
+import type { FixResult, ValidateOptions, ValidationResult } from "vastlint";
+export type VastSessionStatus = "idle" | "loading" | "ready" | "validating" | "resolved" | "fixing" | "error";
+export type VastSessionEventType = "session:created" | "source:loading" | "source:loaded" | "validate:started" | "validate:completed" | "fix:started" | "fix:completed" | "resolve:started" | "resolve:hop" | "resolve:completed" | "track:started" | "track:completed" | "session:error";
+export type VastAdType = "Wrapper" | "InLine" | "Unknown";
+export type VastTrackableEvent = "impression" | "error" | "clickTracking" | "viewable" | "notViewable" | "viewUndetermined" | "creativeView" | "start" | "firstQuartile" | "midpoint" | "thirdQuartile" | "complete" | "mute" | "unmute" | "pause" | "resume" | "rewind" | "skip" | "playerExpand" | "playerCollapse" | "acceptInvitationLinear" | "closeLinear" | "close" | "progress" | "fullscreen" | "exitFullscreen" | (string & {});
+export type VastTrackingEntryKind = "impression" | "error" | "clickTracking" | "clickThrough" | "event";
+export interface VastTrackingTarget {
+    kind: VastTrackingEntryKind;
+    event: VastTrackableEvent | "clickThrough";
+    url: string;
+    hopIndex: number;
+    sourceUrl: string | null;
+    offset: string | null;
+}
+export interface VastTrackingPlan {
+    impressions: VastTrackingTarget[];
+    errors: VastTrackingTarget[];
+    clickTrackings: VastTrackingTarget[];
+    clickThroughs: VastTrackingTarget[];
+    events: VastTrackingTarget[];
+}
+export interface VastTrackingDispatchResult {
+    event: VastTrackableEvent;
+    url: string;
+    resolvedUrl: string;
+    hopIndex: number;
+    sourceUrl: string | null;
+    offset: string | null;
+    ok: boolean;
+    status: number | null;
+    dispatchedAt: string;
+    error: string | null;
+}
+export interface VastTrackingState {
+    plan: VastTrackingPlan;
+    history: VastTrackingDispatchResult[];
+}
+export interface VastTrackOptions {
+    macros?: Record<string, string | number>;
+    offset?: string;
+    dedupe?: boolean;
+}
+export interface VastAdIndexSelector {
+    adIndex: number;
+}
+export interface VastAdIdSelector {
+    adId: string;
+}
+export interface VastAdSequenceSelector {
+    sequence: number;
+}
+export type VastAdSelector = number | VastAdIndexSelector | VastAdIdSelector | VastAdSequenceSelector;
+export interface VastCompanionIndexSelector {
+    companionIndex: number;
+}
+export interface VastCompanionIdSelector {
+    companionId: string;
+}
+export interface VastCompanionAdSlotSelector {
+    adSlotId: string;
+}
+export type VastCompanionSelector = number | VastCompanionIndexSelector | VastCompanionIdSelector | VastCompanionAdSlotSelector;
+export interface VastXmlSource {
+    kind: "xml";
+    xml: string;
+    label?: string;
+}
+export interface VastUrlSource {
+    kind: "url";
+    url: string;
+    request?: RequestInit;
+    label?: string;
+}
+export type VastSessionSource = VastXmlSource | VastUrlSource;
+export interface VastSessionEvent {
+    type: VastSessionEventType;
+    timestamp: string;
+    detail?: Record<string, unknown>;
+}
+export interface VastMediaFile {
+    url: string;
+    mimeType: string;
+    delivery: string;
+    width: string;
+    height: string;
+    bitrate: string;
+}
+export type VastCreativeResourceKind = "static" | "iframe" | "html";
+export interface VastCreativeResource {
+    kind: VastCreativeResourceKind;
+    content: string;
+    creativeType: string | null;
+    xmlEncoded: string | null;
+}
+export interface VastCompanionAd {
+    id: string | null;
+    width: string;
+    height: string;
+    assetWidth: string | null;
+    assetHeight: string | null;
+    expandedWidth: string | null;
+    expandedHeight: string | null;
+    apiFramework: string | null;
+    adSlotId: string | null;
+    pxratio: string | null;
+    renderingMode: string | null;
+    language: string | null;
+    resources: VastCreativeResource[];
+    clickThroughUrl: string | null;
+    clickTrackingUrls: string[];
+    trackingEvents: Record<string, string[]>;
+}
+export interface VastIcon {
+    program: string | null;
+    width: string;
+    height: string;
+    xPosition: string | null;
+    yPosition: string | null;
+    offset: string | null;
+    duration: string | null;
+    apiFramework: string | null;
+    pxratio: string | null;
+    resources: VastCreativeResource[];
+    clickThroughUrl: string | null;
+    clickTrackingUrls: string[];
+    viewTrackingUrls: string[];
+}
+export interface VastUniversalAdId {
+    creativeId: string | null;
+    creativeIndex: number;
+    idRegistry: string | null;
+    idValue: string | null;
+    value: string;
+}
+export interface VastCategory {
+    authority: string | null;
+    value: string;
+}
+export type VastVerificationResourceKind = "javascript" | "executable";
+export interface VastVerificationResource {
+    kind: VastVerificationResourceKind;
+    url: string;
+    apiFramework: string | null;
+    mimeType: string | null;
+    browserOptional: string | null;
+}
+export interface VastAdVerification {
+    vendor: string | null;
+    resources: VastVerificationResource[];
+    verificationParameters: string | null;
+}
+export interface VastAdPodMetadata {
+    adId: string | null;
+    sequence: number | null;
+    adType: string | null;
+    adServingId: string | null;
+    isAdPod: boolean;
+}
+export interface VastMediaSelectionOptions {
+    supportedMimeTypes?: string[];
+    preferredMimeTypes?: string[];
+    preferredDelivery?: string[];
+    targetBitrate?: number;
+    maxBitrate?: number;
+    targetWidth?: number;
+    targetHeight?: number;
+}
+export interface VastMediaSelectionCandidate {
+    mediaFile: VastMediaFile;
+    score: number;
+    reasons: string[];
+}
+export interface VastMediaSelectionResult {
+    selected: VastMediaFile | null;
+    candidates: VastMediaSelectionCandidate[];
+}
+export interface VastWrapperHop {
+    index: number;
+    source: VastSessionSource;
+    url: string | null;
+    xml: string;
+    fetchedAt: string;
+    fetchMs: number;
+    adType: VastAdType;
+    adSystem: string;
+    adTitle: string;
+    duration: string;
+    impressionCount: number;
+    trackingEventCount: number;
+    companionCount: number;
+    mediaFiles: VastMediaFile[];
+    wrapperUri: string | null;
+    validation: ValidationResult | null;
+}
+export interface VastResolutionSummary {
+    hopCount: number;
+    resolved: boolean;
+    chainValid: boolean;
+    totalErrors: number;
+    totalWarnings: number;
+    totalInfos: number;
+    stoppedReason: string | null;
+}
+export interface VastResolvedAd {
+    resolved: boolean;
+    finalHopIndex: number | null;
+    finalUrl: string | null;
+    adType: VastAdType;
+    adSystem: string;
+    adTitle: string;
+    duration: string;
+    skipOffset: string | null;
+    mediaFiles: VastMediaFile[];
+    companions: VastCompanionAd[];
+    icons: VastIcon[];
+    universalAdIds: VastUniversalAdId[];
+    categories: VastCategory[];
+    adVerifications: VastAdVerification[];
+    adPod: VastAdPodMetadata;
+    impressionUrls: string[];
+    errorUrls: string[];
+    clickTrackingUrls: string[];
+    clickThroughUrls: string[];
+    clickThroughUrl: string | null;
+    trackingPlan: VastTrackingPlan;
+    trackingEvents: Record<string, string[]>;
+    companionCount: number;
+    wrapperHopCount: number;
+    stoppedReason: string | null;
+}
+export interface VastSessionSnapshot {
+    status: VastSessionStatus;
+    source: VastSessionSource;
+    xml: string | null;
+    rootXml: string | null;
+    validation: ValidationResult | null;
+    fixed: FixResult | null;
+    wrapperChain: VastWrapperHop[];
+    resolution: VastResolutionSummary | null;
+    tracking: VastTrackingState;
+    resolvedAd: VastResolvedAd | null;
+    resolvedAds: VastResolvedAd[];
+    events: VastSessionEvent[];
+    error: Error | null;
+}
+export interface VastSessionOptions {
+    source: VastSessionSource;
+    validateOptions?: ValidateOptions;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+    maxWrapperDepth?: number;
+}
+export interface VastSession {
+    load(): Promise<VastSessionSnapshot>;
+    validate(): Promise<ValidationResult>;
+    fix(): Promise<FixResult>;
+    resolve(): Promise<VastSessionSnapshot>;
+    getTracking(): VastTrackingState;
+    getAdCompanions(adSelector: VastAdSelector): VastCompanionAd[];
+    getAdTrackingTargets(adSelector: VastAdSelector, event: VastTrackableEvent, options?: Pick<VastTrackOptions, "offset">): VastTrackingTarget[];
+    getCompanionTrackingTargets(adSelector: VastAdSelector, companionSelector: VastCompanionSelector, event: VastTrackableEvent): VastTrackingTarget[];
+    track(event: VastTrackableEvent, options?: VastTrackOptions): Promise<VastTrackingDispatchResult[]>;
+    trackAd(adSelector: VastAdSelector, event: VastTrackableEvent, options?: VastTrackOptions): Promise<VastTrackingDispatchResult[]>;
+    trackCompanion(adSelector: VastAdSelector, companionSelector: VastCompanionSelector, event: VastTrackableEvent, options?: VastTrackOptions): Promise<VastTrackingDispatchResult[]>;
+    getSnapshot(): VastSessionSnapshot;
+    subscribe(listener: (snapshot: VastSessionSnapshot) => void): () => void;
+}
+export type VastPlaybackStatus = "idle" | "ready" | "playing" | "paused" | "ended" | "error";
+export type VastPlaybackViewability = "viewable" | "notViewable" | "viewUndetermined";
+export interface VastPlaybackMilestones {
+    start: boolean;
+    firstQuartile: boolean;
+    midpoint: boolean;
+    thirdQuartile: boolean;
+    complete: boolean;
+}
+export interface VastPlaybackSnapshot {
+    status: VastPlaybackStatus;
+    session: VastSessionSnapshot;
+    resolvedAd: VastResolvedAd | null;
+    mediaSelection: VastMediaSelectionResult;
+    currentTimeSec: number;
+    durationSec: number | null;
+    impressionTracked: boolean;
+    muted: boolean;
+    fullscreen: boolean;
+    skipped: boolean;
+    viewability: VastPlaybackViewability | null;
+    milestones: VastPlaybackMilestones;
+    clickThroughUrl: string | null;
+    error: string | null;
+}
+export interface VastPlaybackControllerOptions {
+    session: VastSession;
+    mediaSelection?: VastMediaSelectionOptions;
+    autoResolve?: boolean;
+}
+export interface VastPlaybackClickResult {
+    clickThroughUrl: string | null;
+    tracking: VastTrackingDispatchResult[];
+    snapshot: VastPlaybackSnapshot;
+}
+export interface VastPlaybackQueueItem {
+    adIndex: number;
+    resolvedAd: VastResolvedAd;
+    mediaSelection: VastMediaSelectionResult;
+    currentTimeSec: number;
+    durationSec: number | null;
+    impressionTracked: boolean;
+    skipped: boolean;
+    milestones: VastPlaybackMilestones;
+    status: VastPlaybackStatus;
+    clickThroughUrl: string | null;
+    error: string | null;
+}
+export interface VastPlaybackQueueSnapshot {
+    status: VastPlaybackStatus;
+    session: VastSessionSnapshot;
+    resolvedAds: VastResolvedAd[];
+    items: VastPlaybackQueueItem[];
+    currentAdIndex: number | null;
+    currentItem: VastPlaybackQueueItem | null;
+    hasNext: boolean;
+    muted: boolean;
+    fullscreen: boolean;
+    viewability: VastPlaybackViewability | null;
+    error: string | null;
+}
+export interface VastPlaybackQueueControllerOptions {
+    session: VastSession;
+    mediaSelection?: VastMediaSelectionOptions;
+    autoResolve?: boolean;
+    fetch?: typeof globalThis.fetch;
+}
+export interface VastPlaybackQueueClickResult {
+    clickThroughUrl: string | null;
+    tracking: VastTrackingDispatchResult[];
+    snapshot: VastPlaybackQueueSnapshot;
+}
+export interface VastPlaybackQueueController {
+    initialize(): Promise<VastPlaybackQueueSnapshot>;
+    start(): Promise<VastPlaybackQueueSnapshot>;
+    pause(): Promise<VastPlaybackQueueSnapshot>;
+    resume(): Promise<VastPlaybackQueueSnapshot>;
+    updateProgress(currentTimeSec: number, durationSec?: number): Promise<VastPlaybackQueueSnapshot>;
+    completeCurrent(): Promise<VastPlaybackQueueSnapshot>;
+    next(): Promise<VastPlaybackQueueSnapshot>;
+    setMuted(muted: boolean): Promise<VastPlaybackQueueSnapshot>;
+    setFullscreen(fullscreen: boolean): Promise<VastPlaybackQueueSnapshot>;
+    setViewability(viewability: VastPlaybackViewability): Promise<VastPlaybackQueueSnapshot>;
+    click(options?: VastTrackOptions): Promise<VastPlaybackQueueClickResult>;
+    skip(): Promise<VastPlaybackQueueSnapshot>;
+    signalError(options?: VastTrackOptions): Promise<VastPlaybackQueueSnapshot>;
+    getSnapshot(): VastPlaybackQueueSnapshot;
+    subscribe(listener: (snapshot: VastPlaybackQueueSnapshot) => void): () => void;
+    dispose(): void;
+}
+export interface VastPlaybackController {
+    initialize(): Promise<VastPlaybackSnapshot>;
+    start(): Promise<VastPlaybackSnapshot>;
+    pause(): Promise<VastPlaybackSnapshot>;
+    resume(): Promise<VastPlaybackSnapshot>;
+    updateProgress(currentTimeSec: number, durationSec?: number): Promise<VastPlaybackSnapshot>;
+    complete(): Promise<VastPlaybackSnapshot>;
+    setMuted(muted: boolean): Promise<VastPlaybackSnapshot>;
+    setFullscreen(fullscreen: boolean): Promise<VastPlaybackSnapshot>;
+    setViewability(viewability: VastPlaybackViewability): Promise<VastPlaybackSnapshot>;
+    click(options?: VastTrackOptions): Promise<VastPlaybackClickResult>;
+    skip(): Promise<VastPlaybackSnapshot>;
+    signalError(options?: VastTrackOptions): Promise<VastPlaybackSnapshot>;
+    getSnapshot(): VastPlaybackSnapshot;
+    subscribe(listener: (snapshot: VastPlaybackSnapshot) => void): () => void;
+    dispose(): void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "vastlint-client",
+  "version": "0.4.20",
+  "description": "Headless VAST session/runtime package built on top of vastlint.",
+  "license": "Apache-2.0",
+  "author": "Alex Sekowski <alex@vastlint.org>",
+  "homepage": "https://vastlint.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aleksUIX/vastlint.git",
+    "directory": "packages/vastlint-client"
+  },
+  "bugs": {
+    "url": "https://github.com/aleksUIX/vastlint/issues"
+  },
+  "keywords": [
+    "vast",
+    "vast-client",
+    "vast-xml",
+    "vast-wrapper",
+    "adtech",
+    "ctv",
+    "video",
+    "advertising",
+    "programmatic"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/**/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "vastlint": "^0.4.20"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}