vastlint-client 0.4.20

package/README.md

@@ -0,0 +1,21 @@
+# vastlint-client
+
+Headless VAST session/runtime package for the `vastlint` monorepo.
+
+Current status:
+
+- XML-backed sessions are implemented.
+- Root URL loading and recursive wrapper-chain resolution are implemented.
+- Per-hop validation, Rust-backed hop metadata extraction, and chain summary state are exposed on the session snapshot.
+- A derived `resolvedAd` model is exposed on the session snapshot for playback-facing consumers.
+- A pod-aware `resolvedAds` array is now exposed on the session snapshot so multi-`<Ad sequence="...">` responses stay separated instead of collapsing into one document-wide playback model.
+- `resolvedAd` now includes parsed companion ads and icons from the final creative.
+- `resolvedAd` now also includes universal ad IDs, categories, ad verifications, and ad-pod metadata.
+- Standalone media selection helpers rank and choose media files from `resolvedAd` using MIME, delivery, bitrate, and dimension preferences.
+- Tracker primitives are implemented for impression, error, viewability, click-tracking, and named `<Tracking event="...">` pixels, with click-through URLs exposed in session tracking state.
+- `createVastSession()` now also exposes low-level pod-aware helpers: `getAdTrackingTargets(adSelector, event)` and `trackAd(adSelector, event, options)`, where `adSelector` can be an index, `{ adId }`, or `{ sequence }`.
+- `createVastSession()` also exposes companion-specific helpers: `getAdCompanions(adSelector)`, `getCompanionTrackingTargets(adSelector, companionSelector, event)`, and `trackCompanion(adSelector, companionSelector, event, options)`.
+- A headless playback controller now layers media selection and player-event tracking on top of a resolved session for impression, quartiles, click, viewability, mute, pause/resume, fullscreen, skip, and error dispatch.
+- A headless playback queue controller now consumes `resolvedAds` and advances through ad pods with per-ad tracking dispatch.
+- Build-first Node runtime tests now cover wrapper resolution, resolved metadata extraction, and the playback controller event flow.
+- The package is intentionally framework-agnostic.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createVastSession } from "./session.js";
+export { rankMediaFiles, selectMediaFile, selectResolvedAdMediaFile } from "./media.js";
+export { createVastPlaybackController } from "./playback.js";
+export { createVastPlaybackQueueController } from "./playback-queue.js";
+export { selectTrackingTargets } from "./tracking.js";
+export type { VastAdIdSelector, VastAdIndexSelector, VastAdPodMetadata, VastAdSelector, VastAdSequenceSelector, VastCompanionAdSlotSelector, VastAdVerification, VastCategory, VastCompanionAd, VastCompanionIdSelector, VastCompanionIndexSelector, VastCompanionSelector, VastCreativeResource, VastCreativeResourceKind, VastIcon, VastMediaSelectionCandidate, VastMediaSelectionOptions, VastMediaSelectionResult, VastPlaybackClickResult, VastPlaybackController, VastPlaybackControllerOptions, VastPlaybackMilestones, VastPlaybackQueueClickResult, VastPlaybackQueueController, VastPlaybackQueueControllerOptions, VastPlaybackQueueItem, VastPlaybackQueueSnapshot, VastPlaybackSnapshot, VastPlaybackStatus, VastPlaybackViewability, VastResolvedAd, VastUniversalAdId, VastVerificationResource, VastVerificationResourceKind, VastSession, VastSessionEvent, VastSessionEventType, VastTrackingDispatchResult, VastTrackingPlan, VastTrackingState, VastTrackingTarget, VastTrackOptions, VastTrackableEvent, VastSessionOptions, VastSessionSnapshot, VastSessionSource, VastSessionStatus, VastUrlSource, VastWrapperHop, VastXmlSource, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createVastSession } from "./session.js";
+export { rankMediaFiles, selectMediaFile, selectResolvedAdMediaFile } from "./media.js";
+export { createVastPlaybackController } from "./playback.js";
+export { createVastPlaybackQueueController } from "./playback-queue.js";
+export { selectTrackingTargets } from "./tracking.js";

package/dist/media.d.ts

@@ -0,0 +1,4 @@
+import type { VastMediaFile, VastMediaSelectionCandidate, VastMediaSelectionOptions, VastMediaSelectionResult, VastResolvedAd } from "./types.js";
+export declare function rankMediaFiles(mediaFiles: readonly VastMediaFile[], options?: VastMediaSelectionOptions): VastMediaSelectionCandidate[];
+export declare function selectMediaFile(mediaFiles: readonly VastMediaFile[], options?: VastMediaSelectionOptions): VastMediaSelectionResult;
+export declare function selectResolvedAdMediaFile(resolvedAd: VastResolvedAd | null, options?: VastMediaSelectionOptions): VastMediaSelectionResult;

package/dist/media.js

@@ -0,0 +1,113 @@
+function normalizeValue(value) {
+    return value.trim().toLowerCase();
+}
+function parseOptionalNumber(value) {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function buildPreferredIndex(values) {
+    return new Map((values ?? []).map((value, index) => [normalizeValue(value), index]));
+}
+function sortCandidates(left, right) {
+    return right.score - left.score || left.mediaFile.url.localeCompare(right.mediaFile.url);
+}
+function scoreDistance(target, actual, weight) {
+    if (target === undefined || actual === null) {
+        return 0;
+    }
+    return Math.max(0, weight - Math.abs(target - actual));
+}
+function scoreMediaFile(mediaFile, options, preferredMimeTypes, preferredDelivery) {
+    const reasons = [];
+    let score = 0;
+    const mimeType = normalizeValue(mediaFile.mimeType);
+    const delivery = normalizeValue(mediaFile.delivery);
+    const width = parseOptionalNumber(mediaFile.width);
+    const height = parseOptionalNumber(mediaFile.height);
+    const bitrate = parseOptionalNumber(mediaFile.bitrate);
+    const supportedMimeTypes = (options.supportedMimeTypes ?? []).map(normalizeValue);
+    if (supportedMimeTypes.length > 0) {
+        if (!mimeType || !supportedMimeTypes.includes(mimeType)) {
+            return null;
+        }
+        score += 400;
+        reasons.push(`supported MIME type ${mimeType}`);
+    }
+    const preferredMimeIndex = preferredMimeTypes.get(mimeType);
+    if (preferredMimeIndex !== undefined) {
+        score += 300 - preferredMimeIndex * 25;
+        reasons.push(`preferred MIME type ${mimeType}`);
+    }
+    else if (mimeType.startsWith("video/")) {
+        score += 75;
+        reasons.push(`video MIME type ${mimeType}`);
+    }
+    const preferredDeliveryIndex = preferredDelivery.get(delivery);
+    if (preferredDeliveryIndex !== undefined) {
+        score += 120 - preferredDeliveryIndex * 15;
+        reasons.push(`preferred delivery ${delivery}`);
+    }
+    else if (delivery) {
+        score += 20;
+        reasons.push(`delivery ${delivery}`);
+    }
+    if (bitrate !== null) {
+        score += 25;
+        reasons.push(`declares bitrate ${bitrate}`);
+    }
+    if (width !== null && height !== null) {
+        score += 25;
+        reasons.push(`declares dimensions ${width}x${height}`);
+    }
+    if (options.maxBitrate !== undefined && bitrate !== null) {
+        if (bitrate > options.maxBitrate) {
+            score -= 200;
+            reasons.push(`bitrate ${bitrate} exceeds max ${options.maxBitrate}`);
+        }
+        else {
+            score += 40;
+            reasons.push(`bitrate ${bitrate} is within max ${options.maxBitrate}`);
+        }
+    }
+    const bitrateScore = scoreDistance(options.targetBitrate, bitrate, 160);
+    if (bitrateScore > 0 && bitrate !== null && options.targetBitrate !== undefined) {
+        score += bitrateScore;
+        reasons.push(`bitrate ${bitrate} is close to target ${options.targetBitrate}`);
+    }
+    const widthScore = scoreDistance(options.targetWidth, width, 120);
+    if (widthScore > 0 && width !== null && options.targetWidth !== undefined) {
+        score += widthScore;
+        reasons.push(`width ${width} is close to target ${options.targetWidth}`);
+    }
+    const heightScore = scoreDistance(options.targetHeight, height, 120);
+    if (heightScore > 0 && height !== null && options.targetHeight !== undefined) {
+        score += heightScore;
+        reasons.push(`height ${height} is close to target ${options.targetHeight}`);
+    }
+    if (mediaFile.url) {
+        score += 5;
+    }
+    return {
+        mediaFile: { ...mediaFile },
+        score,
+        reasons,
+    };
+}
+export function rankMediaFiles(mediaFiles, options = {}) {
+    const preferredMimeTypes = buildPreferredIndex(options.preferredMimeTypes);
+    const preferredDelivery = buildPreferredIndex(options.preferredDelivery);
+    return mediaFiles
+        .map((mediaFile) => scoreMediaFile(mediaFile, options, preferredMimeTypes, preferredDelivery))
+        .filter((candidate) => candidate !== null)
+        .sort(sortCandidates);
+}
+export function selectMediaFile(mediaFiles, options = {}) {
+    const candidates = rankMediaFiles(mediaFiles, options);
+    return {
+        selected: candidates[0]?.mediaFile ?? null,
+        candidates,
+    };
+}
+export function selectResolvedAdMediaFile(resolvedAd, options = {}) {
+    return selectMediaFile(resolvedAd?.mediaFiles ?? [], options);
+}

package/dist/playback-queue.d.ts

@@ -0,0 +1,2 @@
+import type { VastPlaybackQueueController, VastPlaybackQueueControllerOptions } from "./types.js";
+export declare function createVastPlaybackQueueController(options: VastPlaybackQueueControllerOptions): VastPlaybackQueueController;