@streamlayer/feature-advertisement 1.2.0 → 1.2.1-rc.12.pc6c8e1c0

package/lib/cjs/units/external-ad.d.ts

@@ -0,0 +1,127 @@
+import type { AdTagParams } from '@streamlayer/sdk-web-core';
+import { StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
+import { VastAd, VastCompanionAd, VastCreativeCompanion, VastCreativeLinear, VastCreativeNonLinear, VastNonLinearAd, VastResponse } from '@dailymotion/vast-client';
+import '@streamlayer/sdk-web-api';
+import { type PalNonceManager } from './gam.js';
+import { VastCreative } from './parse-vast-extensions.js';
+export type AdCompanion = {
+    imageUrl?: string;
+    clickUrl?: string;
+    width?: number;
+    height?: number;
+    /** The `<CompanionAds>` creative — the `VASTTracker` 3rd argument. */
+    creative?: VastCreativeCompanion;
+    /** The `<Companion>` variation — the 4th argument; carries this companion's own `creativeView`. */
+    variation?: VastCompanionAd;
+};
+/**
+ * First `<NonLinear>` variation of a `<NonLinearAds>` creative. Tags that ship this instead of a
+ * `<Linear>` creative make it the ad's main media, not a companion strip.
+ */
+export type AdNonLinear = {
+    imageUrl: string;
+    clickUrl?: string;
+    width?: number;
+    height?: number;
+    /** The `<NonLinearAds>` creative — carries the creative-level `<TrackingEvents>`. */
+    creative: VastCreativeNonLinear;
+    /** The `<NonLinear>` variation — the `VASTTracker` 4th argument (click-through + its trackers). */
+    variation: VastNonLinearAd;
+};
+export type AdData = {
+    creative: VastCreativeLinear;
+    order: number;
+    mediaFileUrl?: string;
+    /** First companion creative (static image + click-through) — sources the L-Bar banner strip. */
+    companion?: AdCompanion;
+    /** The 300x75 `<Companion>` — the sponsor logo. Only set for a companion pair. */
+    logo?: AdCompanion;
+    /**
+     * The iOS `SLRVASTSlotRole.cardLogo` pick: companion-only, aspect-scored toward 1:1, and minus
+     * whatever the hero slot already claimed. Consumed **only** by the hero-card placements
+     * (Side-by-Side / Picture in Picture / Sponsor Frame) as a fallback for an otherwise empty
+     * header logo. `logo` is the SC-335 display rule and is unchanged; when it fires, this stays
+     * `undefined` because the display rule already won the slot.
+     */
+    cardLogo?: AdCompanion;
+    /**
+     * The tag's ONLY `<Companion>`, when it is exactly 300x75 and the hero is a Linear or a
+     * NonLinear — i.e. the companion is logo-sized and nothing else needs it. The pair rule behind
+     * `logo` exists to tell the logo from the media among companions; with the media coming from
+     * elsewhere there is nothing to tell apart, and iOS fills its logo from a single companion.
+     * Consumed only by the Standard Ad Sidebar (`createActiveAdFromVast`) as a header-logo fallback;
+     * a companion-only tag leaves it `undefined`, because there the companion IS the media.
+     */
+    loneLogo?: AdCompanion;
+    /** Banner-sized `<Companion>` (468x60 class) — the sidebar media for companion-pair tags. */
+    mediaCompanion?: AdCompanion;
+    /** NonLinear (image-only) creative — present when the tag has no `<Linear>` media. */
+    nonLinear?: AdNonLinear;
+    /** VAST `<AdTitle>`. */
+    title?: string;
+    /** VAST `<Description>`. */
+    description?: string;
+    /** Linear `<ClickThrough>`, else `<NonLinearClickThrough>`, else `<CompanionClickThrough>`. */
+    clickThrough?: string;
+    ad: VastAd;
+    extension?: VastCreative;
+    raw: VastResponse;
+};
+export type AdStore = {
+    ads: AdData[];
+    autoplay: boolean;
+    muted: boolean;
+    nonceManager?: PalNonceManager;
+};
+/**
+ * Split a `<CompanionAds>` creative's variations into the logo and media slots.
+ *
+ * The pair mapping activates only for a tag that ships an exact 300x75 companion next to at
+ * least one other. Deliberately conservative pending broader product sizes: on any other tag
+ * no companion is promoted to the logo slot and the first one stays the media/strip candidate.
+ *
+ * Both halves of that gate are load-bearing and neither is an aspect rule: a 320x80 companion is
+ * the same 4:1 shape as 300x75 and is still rejected, and a lone 300x75 companion is rejected too
+ * (the Standard Ad Sidebar recovers that one as `AdData.loneLogo` when a Linear / NonLinear is
+ * the media, so it is not needed here).
+ * This is **narrower than iOS**, which has no size rule at all and fills its logo slot from a
+ * single companion — see `docs/wiki/programmatic-ads-display-ios-parity.md`. Exported for
+ * `external-ad.spec.ts` only; `src/index.ts` re-exports names explicitly, so this stays out of the
+ * package's public API.
+ */
+export declare const selectCompanions: (companions: AdCompanion[]) => {
+    logo: undefined;
+    media: AdCompanion;
+} | {
+    logo: AdCompanion;
+    media: AdCompanion | undefined;
+};
+/**
+ * Map a parsed VAST response into our `AdData` shape. Shared by both acquisition
+ * paths — the GAM/VMAP tag flow and the Prebid auction flow — so the two always
+ * produce identical downstream data.
+ *
+ * Returns `undefined` for a no-ad, which is two distinct shapes: a response with no ad carrying
+ * creatives, and an ad whose creatives carry no RENDERABLE asset — no linear `<MediaFile>`, no
+ * `<NonLinear>` still and no `<Companion>` image. Both callers `filter(Boolean)` the result, so a
+ * no-ad leaves `ads: []` and the card keeps whatever the server configured for it.
+ *
+ * Exported for `vast-mapping.spec.ts`, which drives it over the same fixture corpus the iOS suite
+ * uses. `src/index.ts` re-exports names explicitly, so this stays out of the package's public API.
+ */
+export declare const buildAdData: (parsedVAST: VastResponse, order: number) => AdData | undefined;
+/**
+ * Build the OpenRTB request body for a single video auction. Placement config is
+ * carried on the Prebid link's query string so the consumer-facing interface stays a
+ * single URL string:
+ * - `configId` → `imp.ext.prebid.storedrequest.id` (production stored request).
+ * - `storedauctionresponse` → `imp.ext.prebid.storedauctionresponse.id` (staging mock).
+ * - `test=1` → top-level `test` flag.
+ * - `w` / `h` → video dimensions (default 1920×1080).
+ *
+ * The host's GDPR consent (`AdTagParams`) rides the OpenRTB 2.5 extension fields Prebid Server
+ * reads — `regs.ext.gdpr` and `user.ext.consent` — the same signal the `${GDPR}` /
+ * `${GDPR_CONSENT}` macros carry for a VAST tag. Each is sent only when the host passed it.
+ */
+export declare const buildAuctionRequest: (url: URL, adTagParams?: AdTagParams) => Record<string, unknown>;
+export declare const externalAd: (instance: StreamLayerContext) => (gamUrl: string) => import("@nanostores/query", { with: { "resolution-mode": "import" } }).FetcherStore<AdStore | undefined, any>;

package/lib/cjs/units/external-ad.js

@@ -0,0 +1,421 @@
+'use strict';
+
+var sdkWebLogger = require('@streamlayer/sdk-web-logger');
+var vastClient = require('@dailymotion/vast-client');
+require('@streamlayer/sdk-web-api');
+var VMAP = require('vmap');
+var gam = require('./gam.js');
+var parseVastExtensions = require('./parse-vast-extensions.js');
+var sponsorLogo = require('./sponsor-logo.js');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var VMAP__default = /*#__PURE__*/_interopDefault(VMAP);
+
+// Pins the `@dailymotion/vast-client` → `@types/vast-client` shim: TypeDoc
+// compiles this file through dependent packages' programs, whose tsconfig
+// `include` does not cover this package's ambient declarations.
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="../module.d.ts" />
+const log = sdkWebLogger.createLogger('ui:gam-external-ad');
+/** Default budget for a single VAST resolution before it is treated as "no ad". */
+const VAST_FETCH_TIMEOUT_MS = 10_000;
+/**
+ * Resolve `promise`, but fall back to `undefined` if it doesn't settle within `ms`.
+ * A slow/unreachable VAST endpoint must degrade to "no ad" instead of leaving the
+ * fetcher (and the sidebar) stuck waiting. Uses a timer rather than `AbortController`
+ * so it stays safe on the ES5/Chrome-32 target.
+ */
+const withTimeout = (promise, ms) => {
+    return Promise.race([
+        promise,
+        new Promise((resolve) => {
+            setTimeout(() => resolve(undefined), ms);
+        }),
+    ]);
+};
+// const preloadImage = (src: string) => {
+//   return new Promise((resolve, reject) => {
+//     const image = new Image()
+//     image.onload = () => resolve(src)
+//     image.onerror = () => reject()
+//     image.src = src
+//   })
+// }
+/**
+ * Get the first valid creative from an ad
+ */
+const getCreative = (ad) => {
+    return ad.creatives.find((creative) => getMediaFileUrl(creative));
+};
+/**
+ * Get the URL of the first media file in the creative
+ */
+const getMediaFileUrl = (creative) => {
+    const mediaFiles = creative?.mediaFiles;
+    if (!mediaFiles?.length) {
+        return '';
+    }
+    return mediaFiles.find((mediaFile) => mediaFile.fileURL)?.fileURL || '';
+};
+/**
+ * Extract the linear creative's `<ClickThrough>` URL. Sources the sidebar CTA (QR code
+ * + click-through). `videoClickThroughURLTemplate` isn't strongly typed in the client lib.
+ */
+const getClickThrough = (creative) => {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore — vast-client types `videoClickThroughURLTemplate` loosely
+    return creative?.videoClickThroughURLTemplate?.url || undefined;
+};
+/** Product companion mapping: the 300x75 companion is the logo, the banner-sized one the media. */
+const LOGO_COMPANION_WIDTH = 300;
+const LOGO_COMPANION_HEIGHT = 75;
+const isLogoSized = (companion) => companion?.width === LOGO_COMPANION_WIDTH && companion?.height === LOGO_COMPANION_HEIGHT;
+const companionArea = (companion) => (companion.width || 0) * (companion.height || 0);
+/**
+ * Split a `<CompanionAds>` creative's variations into the logo and media slots.
+ *
+ * The pair mapping activates only for a tag that ships an exact 300x75 companion next to at
+ * least one other. Deliberately conservative pending broader product sizes: on any other tag
+ * no companion is promoted to the logo slot and the first one stays the media/strip candidate.
+ *
+ * Both halves of that gate are load-bearing and neither is an aspect rule: a 320x80 companion is
+ * the same 4:1 shape as 300x75 and is still rejected, and a lone 300x75 companion is rejected too
+ * (the Standard Ad Sidebar recovers that one as `AdData.loneLogo` when a Linear / NonLinear is
+ * the media, so it is not needed here).
+ * This is **narrower than iOS**, which has no size rule at all and fills its logo slot from a
+ * single companion — see `docs/wiki/programmatic-ads-display-ios-parity.md`. Exported for
+ * `external-ad.spec.ts` only; `src/index.ts` re-exports names explicitly, so this stays out of the
+ * package's public API.
+ */
+const selectCompanions = (companions) => {
+    const logo = companions.length > 1 ? companions.find((companion) => isLogoSized(companion)) : undefined;
+    if (!logo) {
+        return { logo: undefined, media: companions[0] };
+    }
+    const media = companions
+        .filter((companion) => companion !== logo)
+        .sort((a, b) => companionArea(a) - companionArea(b))
+        .pop();
+    return { logo, media };
+};
+/**
+ * Map a parsed VAST response into our `AdData` shape. Shared by both acquisition
+ * paths — the GAM/VMAP tag flow and the Prebid auction flow — so the two always
+ * produce identical downstream data.
+ *
+ * Returns `undefined` for a no-ad, which is two distinct shapes: a response with no ad carrying
+ * creatives, and an ad whose creatives carry no RENDERABLE asset — no linear `<MediaFile>`, no
+ * `<NonLinear>` still and no `<Companion>` image. Both callers `filter(Boolean)` the result, so a
+ * no-ad leaves `ads: []` and the card keeps whatever the server configured for it.
+ *
+ * Exported for `vast-mapping.spec.ts`, which drives it over the same fixture corpus the iOS suite
+ * uses. `src/index.ts` re-exports names explicitly, so this stays out of the package's public API.
+ */
+const buildAdData = (parsedVAST, order) => {
+    // Defensive, and unreachable through either production path: `@dailymotion/vast-client` discards
+    // an ad whose creatives all fail to parse (empty `<Linear>`, empty/missing `<Creatives>`, unknown
+    // creative element) before `parseVAST` resolves, so it never yields an Ad with zero creatives.
+    // Kept because it costs nothing and `buildAdData` is also reachable from tests with a hand-built
+    // response — see the `invalid_ad` case in `vast-mapping.spec.ts`, which pins the parser contract
+    // this relies on rather than pretending to exercise the guard.
+    const validAd = parsedVAST.ads.find((ads) => ads.creatives.length > 0);
+    if (!validAd) {
+        log.warn({ order, ads: parsedVAST.ads.length }, 'vast response carries no ad with creatives — treated as no-ad');
+        return undefined;
+    }
+    const extension = validAd.extensions.find((ext) => ext.attributes.type.startsWith('streamlayer'))?.children[0];
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-expect-error
+    const parsedExtension = parseVastExtensions.parseVastExtension(extension);
+    const creative = getCreative(validAd);
+    const mediaFileUrl = getMediaFileUrl(creative);
+    const images = sponsorLogo.collectAssets(validAd);
+    const companions = images.filter((asset) => asset.origin === 'companion');
+    const nonLinear = images.find((asset) => asset.origin === 'nonlinear');
+    // An ad the parser KEPT whose creatives carry nothing any shell can draw is a no-ad, exactly
+    // like a response with no ad at all. vast-client only discards a creative it cannot parse; a
+    // `<NonLinear>` or `<Companion>` whose `<StaticResource>` body is empty parses fine and just
+    // yields no url, so the guard above cannot catch it. Without this the fabricated promotion still
+    // took the slot and drew the ad's TEXT — title and description over an empty media box — which
+    // is a billable impression for a creative that does not exist.
+    //
+    // "Renderable" is the union of the three slots the shells can fill: a linear `<MediaFile>`, a
+    // `<NonLinear>` still, or a `<Companion>` image. `collectAssets` already drops the imageless
+    // ones, so a non-empty `companions` means at least one drawable image. A tag carrying only a
+    // `<Mezzanine>` never reaches here — the parser drops that Linear itself — but it lands in the
+    // same place either way.
+    if (!mediaFileUrl && !nonLinear && companions.length === 0) {
+        log.warn({ order, adId: validAd.id, creatives: validAd.creatives.length }, 'vast ad carries no renderable asset (no media file, no nonlinear, no companion) — treated as no-ad');
+        return undefined;
+    }
+    const { logo, media: mediaCompanion } = selectCompanions(companions);
+    const clickThrough = getClickThrough(creative) || nonLinear?.clickUrl || mediaCompanion?.clickUrl;
+    // Mirror iOS's greedy `pool.select([hero, .cardLogo])`: the hero claims first and a claimed
+    // asset is gone for later roles. Web's hero precedence (`createActiveAdFromVast`) is linear
+    // video → pair media companion (unreachable here: a `logo` short-circuits the whole selection)
+    // → NonLinear still → lone companion, so a companion is only unavailable to the logo slot when
+    // it IS the hero, i.e. when the tag ships neither. `selectCardLogo` already filters to companion
+    // origins, so the NonLinear never needs excluding.
+    //
+    // Excluding `companions[0]` (which is what `mediaCompanion` is when there is no `logo`) rather
+    // than the largest-area asset is a deliberate difference from iOS's `areaDominant` hero: web's
+    // content slot draws the FIRST companion in document order, so document order is the correct
+    // criterion for "what the hero already claimed" on this platform.
+    const companionIsHero = !mediaFileUrl && !nonLinear;
+    const cardLogoAsset = logo ? undefined : sponsorLogo.selectCardLogo(validAd, companionIsHero ? [mediaCompanion] : []);
+    // Share the selected resource wrapper so drawn-companion identity remains stable.
+    const cardLogo = cardLogoAsset
+        ? companions.find((item) => item.variation === cardLogoAsset.variation && item.imageUrl === cardLogoAsset.imageUrl)
+        : undefined;
+    // Same collected instance as `companion` (identity matters to `drawnCompanions`). A lone
+    // companion never satisfies the pair rule, so this can only fill a slot `logo` left empty.
+    const loneLogo = companions.length === 1 && !companionIsHero && isLogoSized(companions[0]) ? companions[0] : undefined;
+    log.info({
+        order,
+        adId: validAd.id,
+        title: validAd.title || undefined,
+        found: {
+            linear: !!creative,
+            mediaFile: mediaFileUrl || undefined,
+            nonLinear: nonLinear ? `${nonLinear.width}x${nonLinear.height}` : undefined,
+            companions: companions.map((item) => `${item.width}x${item.height}`),
+        },
+        selected: {
+            logo: logo ? { size: `${logo.width}x${logo.height}`, url: logo.imageUrl } : undefined,
+            media: mediaCompanion
+                ? { size: `${mediaCompanion.width}x${mediaCompanion.height}`, url: mediaCompanion.imageUrl }
+                : undefined,
+            cardLogo: cardLogo ? { size: `${cardLogo.width}x${cardLogo.height}`, url: cardLogo.imageUrl } : undefined,
+            loneLogo: loneLogo ? { size: `${loneLogo.width}x${loneLogo.height}`, url: loneLogo.imageUrl } : undefined,
+            clickThrough: !!clickThrough,
+        },
+    }, 'vast ad parsed');
+    return {
+        creative,
+        order,
+        mediaFileUrl,
+        companion: companions[0],
+        logo,
+        cardLogo,
+        loneLogo,
+        mediaCompanion,
+        nonLinear,
+        clickThrough,
+        title: validAd.title || undefined,
+        description: validAd.description || undefined,
+        ad: validAd,
+        extension: parsedExtension,
+        raw: parsedVAST,
+    };
+};
+/** Path of the self-hosted Prebid Server OpenRTB auction endpoint. */
+const PREBID_AUCTION_PATH = '/openrtb2/auction';
+/**
+ * A Prebid link points at our Prebid Server auction endpoint (staging:
+ * `https://prebid.next.streamlayer.io/openrtb2/auction`) rather than at a VAST tag.
+ * Detected by path so both staging and production hosts match.
+ */
+const isPrebidUrl = (url) => url.pathname.endsWith(PREBID_AUCTION_PATH);
+/** Unique per-auction request id — Prebid responses are never cached/reused (RFC §5). */
+const createRequestId = () => `sl-web-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+/**
+ * Build the OpenRTB request body for a single video auction. Placement config is
+ * carried on the Prebid link's query string so the consumer-facing interface stays a
+ * single URL string:
+ * - `configId` → `imp.ext.prebid.storedrequest.id` (production stored request).
+ * - `storedauctionresponse` → `imp.ext.prebid.storedauctionresponse.id` (staging mock).
+ * - `test=1` → top-level `test` flag.
+ * - `w` / `h` → video dimensions (default 1920×1080).
+ *
+ * The host's GDPR consent (`AdTagParams`) rides the OpenRTB 2.5 extension fields Prebid Server
+ * reads — `regs.ext.gdpr` and `user.ext.consent` — the same signal the `${GDPR}` /
+ * `${GDPR_CONSENT}` macros carry for a VAST tag. Each is sent only when the host passed it.
+ */
+const buildAuctionRequest = (url, adTagParams) => {
+    const params = url.searchParams;
+    const width = Number(params.get('w')) || 1920;
+    const height = Number(params.get('h')) || 1080;
+    const configId = params.get('configId') ?? params.get('config_id') ?? undefined;
+    const storedAuctionResponse = params.get('storedauctionresponse') ?? undefined;
+    const prebid = {};
+    if (storedAuctionResponse) {
+        prebid.storedauctionresponse = { id: storedAuctionResponse };
+    }
+    if (configId) {
+        prebid.storedrequest = { id: configId };
+    }
+    prebid.bidder = {
+        appnexus: { placementId: 13144370 },
+    };
+    const request = {
+        id: createRequestId(),
+        imp: [
+            {
+                id: '1',
+                video: {
+                    mimes: ['video/mp4'],
+                    protocols: [2, 3, 5, 6],
+                    w: width,
+                    h: height,
+                    placement: 1,
+                    linearity: 1,
+                },
+                ext: { prebid },
+            },
+        ],
+        site: { page: typeof location !== 'undefined' ? location.href : url.origin },
+        tmax: 500,
+    };
+    if (params.get('test') === '1') {
+        request.test = 1;
+    }
+    if (adTagParams?.gdprApplies !== undefined) {
+        request.regs = { ext: { gdpr: adTagParams.gdprApplies ? 1 : 0 } };
+    }
+    if (adTagParams?.tcString) {
+        request.user = { ext: { consent: adTagParams.tcString } };
+    }
+    return request;
+};
+/**
+ * Run one Prebid Server auction and turn the winning inline VAST into an `AdStore`.
+ * Every bid's `adm` is inline VAST XML (no URL to fetch); bids are ordered by price
+ * so the winner plays first (RFC §2). A single bad bid must not drop the batch.
+ */
+const fetchPrebidAds = async (prebidUrl, adTagParams) => {
+    const response = await fetch(prebidUrl.toString(), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(buildAuctionRequest(prebidUrl, adTagParams)),
+    });
+    if (!response.ok) {
+        throw new Error(`prebid auction failed with status ${response.status}`);
+    }
+    const auction = (await response.json());
+    const bids = (auction.seatbid ?? [])
+        .reduce((acc, seat) => acc.concat(seat.bid ?? []), [])
+        .filter((bid) => !!bid.adm)
+        // Highest price wins — the winner is order 0 (RFC §2).
+        .sort((a, b) => (b.price ?? 0) - (a.price ?? 0));
+    const parser = new DOMParser();
+    const loadedAds = await Promise.all(bids.map((bid, i) => {
+        const xmlDoc = parser.parseFromString(bid.adm, 'text/xml');
+        // A fresh `VASTParser` per bid isolates parser state, mirroring the fresh
+        // `VASTClient` per link in the tag flow. `resolveAll: true` follows any
+        // `VASTAdTagURI` wrapper chain the bid's inline VAST may still contain.
+        return (new vastClient.VASTParser()
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-ignore
+            .parseVAST(xmlDoc, { resolveAll: true, wrapperLimit: 10, allowMultipleAds: true })
+            .then((parsedVAST) => buildAdData(parsedVAST, i))
+            .catch((err) => {
+            // A single failing bid must not drop the whole batch.
+            log.error(err, 'failed to parse prebid VAST');
+            return undefined;
+        }));
+    }));
+    const params = prebidUrl.searchParams;
+    const autoplay = params.get('vpa')?.replaceAll('?', '') !== 'click';
+    const muted = params.get('vpmute')?.replaceAll('?', '') === '1';
+    return {
+        ads: loadedAds.filter((d) => !!d),
+        autoplay,
+        muted,
+    };
+};
+const externalAd = (instance) => {
+    return (gamUrl) => instance.transport.nanoquery.createFetcherStore([gamUrl], {
+        dedupeTime: Infinity,
+        revalidateInterval: 0,
+        fetcher: async (adUrl) => {
+            if (!adUrl || typeof adUrl !== 'string') {
+                throw new Error('ad url is empty');
+            }
+            const parsedAdUrl = (() => {
+                try {
+                    return new URL(adUrl);
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+            // The host's CURRENT macro values, read per request rather than baked into the store: the
+            // store is cached by url for the session, and consent routinely arrives after the SDK
+            // starts (a CMP answers asynchronously) or changes mid-session.
+            const adTagParams = instance.sdk.options.get().adTagParams;
+            // Prebid links hit our Prebid Server auction endpoint instead of a VAST tag.
+            // Run the OpenRTB auction and parse the winning bid's inline VAST (`adm`) into
+            // the same `AdStore` shape the GAM/VMAP path returns. See rfcs/prebid.
+            if (parsedAdUrl && isPrebidUrl(parsedAdUrl)) {
+                return fetchPrebidAds(parsedAdUrl, adTagParams);
+            }
+            const generateUrl = gam.gam(adUrl, undefined, adTagParams);
+            const generatedUrl = await generateUrl();
+            const noncedLink = generatedUrl?.url;
+            if (!noncedLink) {
+                throw new Error('ad url is not generated');
+            }
+            let links;
+            if (noncedLink.searchParams.get('output')?.replaceAll('?', '') === 'vmap') {
+                const response = await withTimeout(fetch(noncedLink.toString()), VAST_FETCH_TIMEOUT_MS);
+                if (!response) {
+                    throw new Error('vmap fetch timed out');
+                }
+                const parser = new DOMParser();
+                const xmlStr = await response.text();
+                const xmlDoc = parser.parseFromString(xmlStr, 'text/xml');
+                const vmap = new VMAP__default.default(xmlDoc);
+                links = vmap.adBreaks.map((ad) => {
+                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                    // @ts-expect-error
+                    return ad.adSource.adTagURI.uri;
+                });
+            }
+            else {
+                links = [noncedLink.toString()];
+            }
+            const loadedAds = await Promise.all(links.map((link, i) => {
+                // `resolveAll: true` makes the client follow every `VASTAdTagURI` wrapper chain
+                // (up to the default depth of 10) and resolve all Ads, merging wrapper-level
+                // Impression/tracking URLs into the inline Ad. The default (`resolveAll: false`)
+                // only resolves the first standalone Ad and defers wrappers/remaining Ads to
+                // `getNextAds()`, which this fetcher never calls. A fresh `VASTClient` per link
+                // isolates parser state so concurrent (VMAP) resolutions don't clobber each other.
+                return withTimeout(new vastClient.VASTClient()
+                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                    // @ts-ignore
+                    .get(link, { resolveAll: true, wrapperLimit: 10, allowMultipleAds: true }), VAST_FETCH_TIMEOUT_MS)
+                    .then((parsedVAST) => {
+                    // `parsedVAST` is `undefined` when the resolution timed out (see `withTimeout`).
+                    if (!parsedVAST) {
+                        log.warn({ link, timeoutMs: VAST_FETCH_TIMEOUT_MS }, 'vast resolution timed out — treated as no-ad');
+                        return undefined;
+                    }
+                    return buildAdData(parsedVAST, i);
+                })
+                    .catch((err) => {
+                    // A single failing wrapper chain must not drop the whole batch.
+                    log.error(err, 'failed to resolve VAST');
+                    return undefined;
+                });
+            }));
+            const autoplay = noncedLink.searchParams.get('vpa')?.replaceAll('?', '') !== 'click';
+            const muted = noncedLink.searchParams.get('vpmute')?.replaceAll('?', '') === '1';
+            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+            // @ts-expect-error
+            const nonceManager = generatedUrl.manager;
+            return {
+                ads: loadedAds.filter((d) => !!d),
+                autoplay,
+                muted,
+                nonceManager,
+            };
+        },
+    });
+};
+
+exports.buildAdData = buildAdData;
+exports.buildAuctionRequest = buildAuctionRequest;
+exports.externalAd = externalAd;
+exports.selectCompanions = selectCompanions;

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

@@ -0,0 +1,50 @@
+import { createSingleStore, StreamLayerContext } from '@streamlayer/sdk-web-interfaces';
+import '@streamlayer/sdk-web-api';
+export type GAMStaticCore = {
+    id: string;
+    parentId: string;
+    url: string;
+    imageSrc?: string;
+    /**
+     * Linear MP4 from the VAST response → renders full-bleed `<video>` (SC-322).
+     * Only produced when the host asked for it via one of the `fullbleed-video*`
+     * values of `ExternalPauseAdOptions.template`; a `'default'` ad can never carry
+     * this field.
+     */
+    backgroundVideoSrc?: string;
+    adUrl?: string;
+    ad?: any;
+    creative?: any;
+    variation?: any;
+};
+/**
+ * Which VAST creative this request resolves, set by the host on
+ * `pauseAdExternalUrls[].template`:
+ * - `'default'` — static image (nonlinear → companion) → sidebar overlay.
+ * - `'fullbleed-video*'` — the **linear** creative's MP4 → full-screen video (SC-322).
+ *
+ * This is a resolution STRATEGY, not a renderer hint the fetcher may ignore. The
+ * `fullbleed-video` variants differ ONLY in the chrome the renderer draws around
+ * the video, so creative resolution treats them identically.
+ */
+export type PauseAdTemplate = 'default' | 'fullbleed-video' | 'fullbleed-video-center' | 'fullbleed-video-left';
+/**
+ * `indexOf` rather than `Array.prototype.includes`: this package ships to Chrome 32
+ * TV webviews and must stay ES5-compatible without a polyfill.
+ */
+export declare const isFullbleedVideoTemplate: (template?: PauseAdTemplate) => boolean;
+export type ExternalPauseAdOptions = {
+    refetchInterval: number;
+    prefetch: boolean;
+    $enabled: boolean;
+    /**
+     * Creative-resolution strategy. Defaults to `'default'`.
+     *
+     * NOT reactive — it is part of the store's IDENTITY (see the composite Map key
+     * in `Advertisement.getExternalPauseAd`), not of its state. `$enabled` is the
+     * only reactive option here; `refetchInterval`/`prefetch` are read once at
+     * store-creation time.
+     */
+    template?: PauseAdTemplate;
+};
+export declare const externalPauseAd: (instance: StreamLayerContext) => (gamUrl: string, $enabled: ReturnType<typeof createSingleStore<boolean>>, options: ExternalPauseAdOptions) => import("@nanostores/query", { with: { "resolution-mode": "import" } }).FetcherStore<GAMStaticCore | undefined, any>;