@streamlayer/feature-advertisement 0.4.3 → 1.1.0

package/lib/units/gam.d.ts

@@ -0,0 +1,16 @@
+export type PalNonceManager = {
+    getNonce: () => string;
+    sendAdClick: () => void;
+    sendPlaybackStart: () => void;
+    sendPlaybackEnd: () => void;
+};
+export type GamNonceResult = {
+    url: URL;
+    manager?: PalNonceManager;
+};
+export declare const gam: (url: string, adContainer?: HTMLDivElement) => (() => Promise<{
+    url: URL;
+}>) | (() => Promise<{
+    url: URL;
+    manager: PalNonceManager;
+} | undefined>);

package/lib/units/gam.js

@@ -0,0 +1,99 @@
+/**
+ * Google PAL nonce manager + ad-tag resolution for programmatic (GAM) VAST requests.
+ *
+ * Lives here because the VAST fetcher (`units/external-ad.ts`) is its only consumer: this is the
+ * request side of an ad tag, not the promotion side. The *composition* of a tag URL from the proto
+ * (`processGamAdvertisement` / `selectGamOptions`) stays in `feature-gamification`, next to the
+ * `$store` bridge that is its only consumer — so the two feature packages share no code and
+ * neither depends on the other.
+ */
+import { safeLocalStorage, safeSessionStorage } from '@streamlayer/sdk-web-storage';
+import { validate as uuidValidate, v5 as uuid5, v4 as uuid4 } from 'uuid';
+const urlIsNotGam = (url) => {
+    return url.origin !== 'https://pubads.g.doubleclick.net';
+};
+export const gam = (url, adContainer) => {
+    const parsedUrl = (() => {
+        try {
+            const parsedUrl = new URL(url);
+            return parsedUrl;
+        }
+        catch (_err) {
+            return undefined;
+        }
+    })();
+    // Non-GAM VAST/VMAP URLs carry no GAM ad-request params and need no PAL nonce, so
+    // resolve them directly. PAL is only required for pubads.g.doubleclick.net requests —
+    // raw-VAST consumers (e.g. injected sidebar / l-bar) must not depend on the Google PAL
+    // SDK being loaded, so this must run before touching `goog`.
+    if (parsedUrl && urlIsNotGam(parsedUrl)) {
+        // eslint-disable-next-line require-await
+        return async () => {
+            return { url: parsedUrl };
+        };
+    }
+    // @ts-expect-error goog is injected by the externally-loaded Google PAL SDK
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pal = (typeof goog === 'undefined' ? undefined : goog.pal);
+    if (!pal || !parsedUrl) {
+        // eslint-disable-next-line require-await
+        return async () => {
+            return undefined;
+        };
+    }
+    const consentSettings = new pal.ConsentSettings();
+    consentSettings.allowStorage = false;
+    const nonceLoader = new pal.NonceLoader(consentSettings);
+    const generateUrl = async () => {
+        try {
+            const parsedUrl = new URL(url);
+            const request = new pal.NonceRequest();
+            let deviceId = safeLocalStorage().getItem('sl-device-id') || uuid4();
+            let sessionId = safeSessionStorage().getItem('sl-ad-session-id');
+            if (!sessionId) {
+                sessionId = uuid4();
+                safeSessionStorage().setItem('sl-ad-session-id', sessionId);
+            }
+            if (!uuidValidate(deviceId)) {
+                deviceId = uuid5(`https://${deviceId}`, uuid5.URL);
+            }
+            if (!parsedUrl.searchParams.get('url')) {
+                parsedUrl.searchParams.set('url', 'https://streamlayer.io');
+            }
+            if (!parsedUrl.searchParams.get('description_url')) {
+                parsedUrl.searchParams.set('description_url', 'https://streamlayer.io');
+            }
+            request.adWillAutoPlay = parsedUrl.searchParams.get('vpa') === 'auto';
+            request.adWillPlayMuted = parsedUrl.searchParams.get('vpmute') === '1';
+            request.continuousPlayback = true;
+            request.descriptionUrl = parsedUrl.searchParams.get('description_url');
+            request.iconsSupported = true;
+            request.sessionId = deviceId;
+            // Player support for VPAID 2.0, OMID 1.0, and SIMID 1.1
+            request.supportedApiFrameworks = '2,7,9';
+            request.videoHeight = adContainer?.clientHeight ?? 0;
+            request.videoWidth = adContainer?.clientWidth ?? 0;
+            const nonceManager = await nonceLoader.loadNonceManager(request);
+            if (parsedUrl.searchParams.get('is_lat') === '[placeholder]') {
+                parsedUrl.searchParams.set('is_lat', '1');
+            }
+            if (parsedUrl.searchParams.get('rdid') === '[placeholder]') {
+                parsedUrl.searchParams.set('rdid', deviceId);
+            }
+            if (parsedUrl.searchParams.get('correlator') === '[placeholder]') {
+                parsedUrl.searchParams.set('correlator', sessionId);
+            }
+            parsedUrl.searchParams.set('wta', '1');
+            parsedUrl.searchParams.set('givn', nonceManager.getNonce());
+            return {
+                url: parsedUrl,
+                manager: nonceManager,
+            };
+        }
+        catch (adError) {
+            console.log('AdsManager could not be started', adError);
+            return undefined;
+        }
+    };
+    return generateUrl;
+};

package/lib/units/parse-vast-extensions.d.ts

@@ -0,0 +1,17 @@
+import { AdType } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+export interface VastCreative {
+    adName: string;
+    adType: AdType;
+    landscapeBackground?: string;
+    portraitBackground?: string;
+    sponsorLogo?: string;
+    ctaLabel?: string;
+}
+interface VastNode {
+    name: string;
+    value: string | null;
+    attributes: Record<string, string>;
+    children: VastNode[];
+}
+export declare function parseVastExtension(root: VastNode): VastCreative | undefined;
+export {};

package/lib/units/parse-vast-extensions.js

@@ -0,0 +1,47 @@
+import { AdType } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+const MAP_EXTENSION_NAME_AD_TYPE = {
+    DoubleBox: AdType.SIDE_BY_SIDE,
+};
+export function parseVastExtension(root) {
+    if (!root) {
+        return undefined;
+    }
+    const child = (node, name) => node.children.find((c) => c.name === name);
+    const childrenByName = (node, name) => node.children.filter((c) => c.name === name);
+    const urlOf = (node) => child(node, 'Url')?.value ?? '';
+    const num = (v) => (v == null ? NaN : Number(v));
+    const adName = child(root, 'AdName')?.value ?? '';
+    const backgroundsNode = child(root, 'Backgrounds');
+    const backgrounds = backgroundsNode
+        ? childrenByName(backgroundsNode, 'Background').map((bg) => ({
+            orientation: bg.attributes.orientation,
+            width: num(bg.attributes.width),
+            height: num(bg.attributes.height),
+            type: bg.attributes.type,
+            url: urlOf(bg),
+        }))
+        : [];
+    const logosNode = child(root, 'Logos');
+    const logos = logosNode
+        ? childrenByName(logosNode, 'Logo').map((logo) => ({
+            role: logo.attributes.role,
+            width: num(logo.attributes.width),
+            height: num(logo.attributes.height),
+            type: logo.attributes.type,
+            url: urlOf(logo),
+        }))
+        : [];
+    const ctaNode = child(root, 'CTA');
+    const cta = {
+        label: ctaNode ? (child(ctaNode, 'Label')?.value ?? '') : '',
+        type: ctaNode ? (child(ctaNode, 'Type')?.value ?? '') : '',
+    };
+    return {
+        adName,
+        adType: MAP_EXTENSION_NAME_AD_TYPE[root.name] || AdType.SIDE_BY_SIDE,
+        landscapeBackground: backgrounds.find((b) => b.orientation === 'landscape')?.url,
+        portraitBackground: backgrounds.find((b) => b.orientation === 'portrait')?.url,
+        sponsorLogo: logos.find((l) => l.role === 'header')?.url,
+        ctaLabel: cta.label,
+    };
+}

package/lib/units/pause-ad-card.d.ts

@@ -0,0 +1,49 @@
+import { type Question } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+export type PauseAdLayout = 'left' | 'center' | 'image';
+/**
+ * Which full-bleed renderer draws the card. Absent === `'standard'`.
+ *
+ * - `'standard'` — the Standard/Image pause ad (promotion card).
+ * - `'insight'` — the Insight Pause Ad (factoid card): sponsor logo, heading and a
+ *   single-column body beside an optional media image (SC-353).
+ */
+export type PauseAdKind = 'standard' | 'insight';
+/** How the Insight media image is cropped — mirrors Studio's Media switcher. */
+export type PauseAdMediaMode = 'image' | 'circle' | 'none';
+/**
+ * Insight body cap (SC-353). Studio enforces it on the Additional Content field; the
+ * SDK clamps as well so a card authored before the limit landed cannot overflow the
+ * screen — the format is explicitly designed to fit without scrolling.
+ */
+export declare const INSIGHT_BODY_MAX_LENGTH = 600;
+export type PauseAdCard = {
+    id: string;
+    parentId: string;
+    /** Optional: a video-only card (programmatic VAST, SC-322) has no image. */
+    backgroundImageSrc?: string;
+    /** Linear MP4 from VAST → renders full-bleed `<video>` instead of the image (SC-322). */
+    backgroundVideoSrc?: string;
+    layout: PauseAdLayout;
+    isInteractive: boolean;
+    logoSrc?: string;
+    title?: string;
+    description?: string;
+    ctaLabel?: string;
+    ctaUrl?: string;
+    qrCodeUrl?: string;
+    qrCodeLabel?: string;
+    /** Absent === `'standard'`. */
+    kind?: PauseAdKind;
+    /** Insight only: the Media image (`FactoidOptions.image`). */
+    mediaSrc?: string;
+    /** Insight only: how `mediaSrc` is cropped. */
+    mediaMode?: PauseAdMediaMode;
+};
+/**
+ * The `pauseAdList` response, shaped for the renderers: keep the cards the SDK has chrome for,
+ * turn each into a `PauseAdCard`, drop the ones that cannot be drawn.
+ *
+ * Pure on purpose — `pause-ad.ts` owns the store and the transport, this owns the card shapes,
+ * and only this half needs unit tests.
+ */
+export declare const parsePauseAdCards: (questions: Question[]) => PauseAdCard[];

package/lib/units/pause-ad-card.js

@@ -0,0 +1,130 @@
+import { CardFormat, FactoidMediaMode, NotificationSponsorLogoMode, PauseAdLayout as PauseAdLayoutProto, PromotionButtonType, PromotionFormat, QRCode, UseGeneralLogo, UserAccountInfo, } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
+/**
+ * Insight body cap (SC-353). Studio enforces it on the Additional Content field; the
+ * SDK clamps as well so a card authored before the limit landed cannot overflow the
+ * screen — the format is explicitly designed to fit without scrolling.
+ */
+export const INSIGHT_BODY_MAX_LENGTH = 600;
+/**
+ * Sponsor logo for a factoid card. Same General-tab opt-in as the promotion path below,
+ * but the logo lives on `question.promotion.sponsor` (a factoid card carries no
+ * `PromotionOptions`) and Studio writes the uploaded file to `logo`, not `centerLogo`.
+ *
+ * `logo` therefore WINS over `centerLogo`: the latter is an optional field carried over from the
+ * notification/header surfaces, so a card that kept a stale `centerLogo` from an earlier revision
+ * would otherwise render it instead of the Insight logo the author just uploaded.
+ */
+const resolveInsightSponsorLogo = (question) => {
+    const sponsor = question.promotion?.sponsor;
+    if (sponsor?.logoPosition === NotificationSponsorLogoMode.NOTIFICATION_SPONSOR_LOGO_NONE) {
+        return undefined;
+    }
+    return sponsor?.useGeneralLogo === UseGeneralLogo.ENABLED
+        ? question.promotion?.generalTabMetadata?.advertiserTransparentLogo || undefined
+        : sponsor?.logo || sponsor?.centerLogo || undefined;
+};
+const MEDIA_MODE_BY_PROTO = {
+    [FactoidMediaMode.IMAGE]: 'image',
+    [FactoidMediaMode.CIRCLE]: 'circle',
+};
+/**
+ * Insight Pause Ad, Full Bleed (SC-353). A factoid card, so none of the promotion
+ * plumbing above applies: the heading is the question subject, the body is
+ * `FactoidOptions.body`, and the sponsor logo comes off `question.promotion.sponsor`.
+ *
+ * `FACTOID_MEDIA_MODE_VIDEO` is deliberately treated as "no media": the full-bleed
+ * format has no player chrome and no way to start playback, unlike the sidebar variant.
+ */
+const parseInsightPauseAdCard = (question) => {
+    const factoidOptions = question.options?.options.case === 'factoid' ? question.options.options.value : undefined;
+    if (!factoidOptions) {
+        return null;
+    }
+    const mediaMode = MEDIA_MODE_BY_PROTO[factoidOptions.mode] ?? 'none';
+    const body = factoidOptions.body.slice(0, INSIGHT_BODY_MAX_LENGTH);
+    return {
+        id: question.id,
+        parentId: question.eventId || question.id,
+        // `landscapeUrl` ONLY. `portraitUrl` keeps stale artwork from earlier revisions of the
+        // card that Studio no longer shows in its Background Image slot, so falling back to it
+        // paints a background the author has already removed. Unlike the standard card, an
+        // Insight one renders fine with no background at all — its copy is the ad.
+        backgroundImageSrc: question.backgroundImage?.landscapeUrl || undefined,
+        kind: 'insight',
+        layout: 'left',
+        isInteractive: false,
+        logoSrc: resolveInsightSponsorLogo(question),
+        title: question.subject || undefined,
+        description: body || undefined,
+        mediaSrc: mediaMode === 'none' ? undefined : factoidOptions.image || undefined,
+        mediaMode,
+    };
+};
+const parsePauseAdCard = (question) => {
+    if (question.options?.options.case === 'factoid') {
+        return parseInsightPauseAdCard(question);
+    }
+    const backgroundImageSrc = question.backgroundImage?.landscapeUrl;
+    if (!backgroundImageSrc) {
+        return null;
+    }
+    const promotionOptions = question.options?.options.case === 'promotion' ? question.options.options.value : undefined;
+    const pauseAdOptions = promotionOptions?.pauseAdOptions;
+    const optionsSponsor = promotionOptions?.sponsor;
+    const layoutProto = pauseAdOptions?.layout ?? PauseAdLayoutProto.UNSET;
+    const layout = layoutProto === PauseAdLayoutProto.CENTER ? 'center' : layoutProto === PauseAdLayoutProto.IMAGE ? 'image' : 'left';
+    const isInteractive = promotionOptions?.buttonType === PromotionButtonType.SEND_TO_USER;
+    const hasQr = pauseAdOptions?.qrCode === QRCode.QR_CODE_ENABLED && !!pauseAdOptions?.qrCodeUrl;
+    let ctaLabel;
+    let ctaUrl;
+    if (isInteractive && promotionOptions?.buttonOptions.case === 'sendToUserOptions') {
+        const accountInfo = promotionOptions.buttonOptions.value.userAccountInfo;
+        const isPhone = accountInfo === UserAccountInfo.PHONE;
+        ctaUrl = isPhone ? 'sendToPhone:' : 'sendToEmail:';
+        ctaLabel = isPhone ? 'Send info to account phone' : 'Send info to account email';
+    }
+    const logoSrc = optionsSponsor?.logoPosition === NotificationSponsorLogoMode.NOTIFICATION_SPONSOR_LOGO_NONE
+        ? undefined
+        : optionsSponsor?.useGeneralLogo === UseGeneralLogo.ENABLED
+            ? question.promotion?.generalTabMetadata?.advertiserTransparentLogo || undefined
+            : optionsSponsor?.centerLogo || undefined;
+    return {
+        id: question.id,
+        parentId: question.eventId || question.id,
+        backgroundImageSrc,
+        layout,
+        logoSrc,
+        title: promotionOptions?.banner?.title || undefined,
+        description: promotionOptions?.banner?.body || undefined,
+        isInteractive,
+        ctaLabel: ctaLabel || undefined,
+        ctaUrl: ctaUrl || undefined,
+        qrCodeUrl: hasQr ? (pauseAdOptions?.qrCodeUrl ?? undefined) : undefined,
+        qrCodeLabel: hasQr ? (pauseAdOptions?.qrCodeLabel ?? undefined) : undefined,
+    };
+};
+/**
+ * Which cards from `pauseAdList` the SDK can actually draw. Both renderers are full bleed; a
+ * Sidebar-format pause ad has no chrome yet and is skipped.
+ */
+const isFullBleedPauseAd = (question) => {
+    if (question.options?.options.case === 'factoid') {
+        // Insight Pause Ad (SC-353). Studio does not write `CardFormat` on these cards yet
+        // (SLW-7062), so an UNSET format is taken as Full Bleed — the only Insight pause-ad chrome
+        // the SDK has. An explicit Sidebar stays out. Drop the UNSET arm once Studio sets the field.
+        return question.format === CardFormat.FULL_BLEED || question.format === CardFormat.UNSET;
+    }
+    const promotionOptions = question.options?.options.case === 'promotion' ? question.options.options.value : undefined;
+    return promotionOptions?.format === PromotionFormat.FULL_BLEED || question.format === CardFormat.FULL_BLEED;
+};
+/**
+ * The `pauseAdList` response, shaped for the renderers: keep the cards the SDK has chrome for,
+ * turn each into a `PauseAdCard`, drop the ones that cannot be drawn.
+ *
+ * Pure on purpose — `pause-ad.ts` owns the store and the transport, this owns the card shapes,
+ * and only this half needs unit tests.
+ */
+export const parsePauseAdCards = (questions) => questions
+    .filter(isFullBleedPauseAd)
+    .map(parsePauseAdCard)
+    .filter((card) => card !== null);

package/lib/units/pause-ad.d.ts

@@ -1,21 +1,7 @@
 import { createSingleStore, StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
 import '@streamlayer/sdk-web-api';
 import '@streamlayer/sdk-web-core/store';
-export type PauseAdLayout = 'left' | 'center' | 'image';
-export type PauseAdCard = {
-    id: string;
-    parentId: string;
-    backgroundImageSrc: string;
-    layout: PauseAdLayout;
-    isInteractive: boolean;
-    logoSrc?: string;
-    title?: string;
-    description?: string;
-    ctaLabel?: string;
-    ctaUrl?: string;
-    qrCodeUrl?: string;
-    qrCodeLabel?: string;
-};
+import { type PauseAdCard } from './pause-ad-card';
 export type PauseAdListOptions = {
     refetchInterval: number;
     $enabled: boolean;

package/lib/units/pause-ad.js

@@ -2,49 +2,9 @@ import { createLogger } from '@streamlayer/sdk-web-logger';
 import { atom } from 'nanostores';
 import '@streamlayer/sdk-web-api';
 import '@streamlayer/sdk-web-core/store';
-import { CardFormat, NotificationSponsorLogoMode, PauseAdLayout as PauseAdLayoutProto, PromotionButtonType, PromotionFormat, QRCode, UseGeneralLogo, UserAccountInfo, } from '@streamlayer/sl-eslib/interactive/interactive.common_pb';
 import { Feed } from '@streamlayer/sl-eslib/interactive/feed/interactive.feed_pb';
+import { parsePauseAdCards } from './pause-ad-card';
 const log = createLogger('advertisement:pause-ad');
-const parsePauseAdCard = (question) => {
-    const backgroundImageSrc = question.backgroundImage?.landscapeUrl;
-    if (!backgroundImageSrc) {
-        return null;
-    }
-    const promotionOptions = question.options?.options.case === 'promotion' ? question.options.options.value : undefined;
-    const pauseAdOptions = promotionOptions?.pauseAdOptions;
-    const optionsSponsor = promotionOptions?.sponsor;
-    const layoutProto = pauseAdOptions?.layout ?? PauseAdLayoutProto.UNSET;
-    const layout = layoutProto === PauseAdLayoutProto.CENTER ? 'center' : layoutProto === PauseAdLayoutProto.IMAGE ? 'image' : 'left';
-    const isInteractive = promotionOptions?.buttonType === PromotionButtonType.SEND_TO_USER;
-    const hasQr = pauseAdOptions?.qrCode === QRCode.QR_CODE_ENABLED && !!pauseAdOptions?.qrCodeUrl;
-    let ctaLabel;
-    let ctaUrl;
-    if (isInteractive && promotionOptions?.buttonOptions.case === 'sendToUserOptions') {
-        const accountInfo = promotionOptions.buttonOptions.value.userAccountInfo;
-        const isPhone = accountInfo === UserAccountInfo.PHONE;
-        ctaUrl = isPhone ? 'sendToPhone:' : 'sendToEmail:';
-        ctaLabel = isPhone ? 'Send info to account phone' : 'Send info to account email';
-    }
-    const logoSrc = optionsSponsor?.logoPosition === NotificationSponsorLogoMode.NOTIFICATION_SPONSOR_LOGO_NONE
-        ? undefined
-        : optionsSponsor?.useGeneralLogo === UseGeneralLogo.ENABLED
-            ? question.promotion?.generalTabMetadata?.advertiserTransparentLogo || undefined
-            : optionsSponsor?.centerLogo || undefined;
-    return {
-        id: question.id,
-        parentId: question.eventId || question.id,
-        backgroundImageSrc,
-        layout,
-        logoSrc,
-        title: promotionOptions?.banner?.title || undefined,
-        description: promotionOptions?.banner?.body || undefined,
-        isInteractive,
-        ctaLabel: ctaLabel || undefined,
-        ctaUrl: ctaUrl || undefined,
-        qrCodeUrl: hasQr ? (pauseAdOptions?.qrCodeUrl ?? undefined) : undefined,
-        qrCodeLabel: hasQr ? (pauseAdOptions?.qrCodeLabel ?? undefined) : undefined,
-    };
-};
 export const pauseAdListStore = (instance) => {
     const $slStreamId = instance.stores.slStreamId.getAtomStore();
     return ($enabled, options) => {
@@ -61,14 +21,7 @@ export const pauseAdListStore = (instance) => {
                 }
                 log.debug({ eventId }, 'fetching pause ad list');
                 const res = await client.pauseAdList({ eventId });
-                const questions = res.data ?? [];
-                const cards = questions
-                    .filter((q) => {
-                    const opts = q.options?.options.case === 'promotion' ? q.options.options.value : undefined;
-                    return opts?.format === PromotionFormat.FULL_BLEED || q.format === CardFormat.FULL_BLEED;
-                })
-                    .map((q) => parsePauseAdCard(q))
-                    .filter((c) => c !== null);
+                const cards = parsePauseAdCards(res.data ?? []);
                 log.debug({ count: cards.length }, 'parsed %d fullbleed pause ad cards');
                 return cards;
             },

package/lib/units/ssai-ad-break.d.ts

@@ -0,0 +1,21 @@
+import { createSingleStore } from '@streamlayer/sdk-web-interfaces';
+import type { SsaiCreative } from './ssai-creative';
+/**
+ * 'ending' = the ad's window closes within the detector's lead (~0.5s): the
+ * overlay's cue to play its closing animation so it completes AT the boundary
+ * rather than after it. Beacons are unaffected — playback still owns those.
+ */
+export type SsaiAdBreakStatus = 'detecting' | 'ready' | 'ending' | 'ended';
+export type SsaiAdBreakState = {
+    creativeId: string;
+    creative?: SsaiCreative;
+    status: SsaiAdBreakStatus;
+    startMs: number;
+    durationSec: number;
+};
+export type SsaiAdBreakStore = ReturnType<typeof createSingleStore<SsaiAdBreakState | null>>;
+/**
+ * Imperative atom driven directly by the detector (no nanoquery — the trigger
+ * is push-based, not request/response).
+ */
+export declare const createSsaiAdBreakStore: () => SsaiAdBreakStore;

package/lib/units/ssai-ad-break.js

@@ -0,0 +1,6 @@
+import { createSingleStore } from '@streamlayer/sdk-web-interfaces';
+/**
+ * Imperative atom driven directly by the detector (no nanoquery — the trigger
+ * is push-based, not request/response).
+ */
+export const createSsaiAdBreakStore = () => createSingleStore(null);

package/lib/units/ssai-creative.d.ts

@@ -0,0 +1,89 @@
+import { DEFAULT_CREATIVE_API_BASE, type SsaiCreativeProvider } from './ssai-providers';
+export { DEFAULT_CREATIVE_API_BASE };
+export type SsaiTrackingEvent = {
+    event: string;
+    url: string;
+};
+export type SsaiCompanion = {
+    staticResource: string;
+    width: number;
+    height: number;
+    clickThrough?: string;
+    /** Beacons fired when the companion is clicked. May be empty. */
+    clickTracking: string[];
+};
+/**
+ * Lifecycle events the SDK fires beacons for, in the order they occur.
+ * `impression` is separate: it is tied to the overlay actually being rendered,
+ * not to playback position — see `SsaiCreativeCache.fireImpression`.
+ */
+export type SsaiProgressEvent = 'start' | 'firstQuartile' | 'midpoint' | 'thirdQuartile' | 'complete';
+export type SsaiCreative = {
+    creativeId: string;
+    advertiser: string;
+    title: string;
+    iconUrl?: string;
+    clickThroughUrl?: string;
+    trackingEvents: SsaiTrackingEvent[];
+    companion?: SsaiCompanion;
+};
+/**
+ * Per-instance cache + impression-firing wrapper around a SsaiCreativeProvider.
+ * Caches resolved creatives by creativeId so repeated active-ad polls and pod
+ * repeats don't refetch. In-flight fetches are cancellable via AbortController.
+ */
+export declare class SsaiCreativeCache {
+    private provider;
+    private cache;
+    private inflight;
+    constructor(provider: SsaiCreativeProvider);
+    /**
+     * The already-resolved creative, or undefined — synchronous on purpose: a
+     * prefetched creative lets the ad break flip straight to 'ready' with no
+     * async gap (which the UI would render as a blink between two ads of a pod).
+     */
+    peek: (creativeId: string) => SsaiCreative | undefined;
+    resolve: (creativeId: string) => Promise<SsaiCreative>;
+    /**
+     * Cancel an in-flight fetch (e.g. the break ended before it resolved).
+     */
+    cancel: (creativeId: string) => void;
+    /**
+     * Fire the impression for a creative. Delegates to the provider's
+     * `fireImpression` when present, otherwise the shared default (first
+     * trackingEvent named 'impression' via sendBeacon/fetch). Called once per
+     * visible appearance of the bar (the UI dedupes the ~250ms active-poll so a
+     * single continuous appearance fires exactly one impression). Each genuine pod
+     * insertion of the same creative is a distinct impression and re-fires.
+     */
+    fireImpression: (creative: SsaiCreative) => void;
+    /**
+     * Fire the impression for an already-resolved creativeId. No-op if the
+     * creative isn't cached yet (the bar only renders once resolved, so by the
+     * time the UI calls this the creative is present).
+     */
+    fireImpressionById: (creativeId: string) => void;
+    /**
+     * Fire a lifecycle / click beacon. Delegates to the provider's `fireTracking`
+     * when it defines one, otherwise fires every matching `trackingEvents` URL.
+     */
+    fireTracking: (creative: SsaiCreative, event: string) => void;
+    /**
+     * Fire a beacon for a creativeId that may still be resolving.
+     *
+     * `start` in particular lands the instant the break opens, which is usually
+     * BEFORE the metadata request has come back — dropping it would silently lose
+     * the first beacon of every ad. Resolution is already in flight by then and
+     * `resolve` returns that same promise, so this attaches to it rather than
+     * issuing a second request. A creative that never resolves fires nothing,
+     * which is the correct outcome: there are no URLs to fire.
+     */
+    fireTrackingById: (creativeId: string, event: string) => void;
+    /**
+     * Fire the companion's `clickTracking` beacons. Separate from
+     * {@link fireTracking} because these live on the companion, not in
+     * `trackingEvents` — a provider's `fireTracking` override has no say over them.
+     */
+    fireCompanionClickById: (creativeId: string) => void;
+    destroy: () => void;
+}