@streamlayer/feature-advertisement 1.1.0 → 1.1.1-rc.1343

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

@@ -0,0 +1,390 @@
+'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');
+
+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) => creative.mediaFiles);
+};
+/**
+ * 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;
+};
+/**
+ * Extract every `<Companion>` variation of the first `<CompanionAds>` creative that carries a
+ * `<StaticResource>`, in document order. `width`/`height` are XML attributes (strings at
+ * runtime), normalised to numbers so the size mapping can compare them.
+ */
+const getCompanions = (ad) => {
+    const creative = ad.creatives.find((item) => item.type === 'companion');
+    return (creative?.variations || []).reduce((acc, variation) => {
+        const imageUrl = variation?.staticResources?.[0]?.url;
+        if (!imageUrl) {
+            return acc;
+        }
+        return acc.concat({
+            imageUrl,
+            clickUrl: variation.companionClickThroughURLTemplate ?? undefined,
+            width: Number(variation.width) || undefined,
+            height: Number(variation.height) || undefined,
+            creative,
+            variation,
+        });
+    }, []);
+};
+/** 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 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.
+ */
+const selectCompanions = (companions) => {
+    const logo = companions.length > 1
+        ? companions.find((companion) => companion.width === LOGO_COMPANION_WIDTH && companion.height === LOGO_COMPANION_HEIGHT)
+        : 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 };
+};
+/**
+ * Extract the first `<NonLinearAds>` creative's static-image variation. Both the creative (which
+ * owns the `<TrackingEvents>`) and the variation (which owns the click-through) are kept —
+ * `VASTTracker` needs both.
+ *
+ * `@dailymotion/vast-client` 6.4.2 emits `nonlinearClickThroughURLTemplate` (lower-case `l`),
+ * which the `@types/vast-client` shim declares as `nonLinearClickThroughURLTemplate` — the
+ * runtime spelling is authoritative.
+ */
+const getNonLinear = (ad) => {
+    const creative = ad.creatives.find((item) => item.type === 'nonlinear');
+    const variation = creative?.variations?.[0];
+    const imageUrl = variation?.staticResource;
+    if (!creative || !variation || !imageUrl) {
+        return undefined;
+    }
+    return {
+        imageUrl,
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore — see the runtime-vs-shim spelling note above
+        clickUrl: variation.nonlinearClickThroughURLTemplate ?? undefined,
+        width: Number(variation.width) || undefined,
+        height: Number(variation.height) || undefined,
+        creative,
+        variation,
+    };
+};
+/**
+ * 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` when the response has no
+ * ad carrying creatives.
+ */
+const buildAdData = (parsedVAST, order) => {
+    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 companions = getCompanions(validAd);
+    const { logo, media: mediaCompanion } = selectCompanions(companions);
+    const nonLinear = getNonLinear(validAd);
+    const clickThrough = getClickThrough(creative) || nonLinear?.clickUrl || mediaCompanion?.clickUrl;
+    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,
+            clickThrough: !!clickThrough,
+        },
+    }, 'vast ad parsed');
+    return {
+        creative,
+        order,
+        mediaFileUrl,
+        companion: companions[0],
+        logo,
+        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).
+ */
+const buildAuctionRequest = (url) => {
+    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;
+    }
+    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) => {
+    const response = await fetch(prebidUrl.toString(), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(buildAuctionRequest(prebidUrl)),
+    });
+    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;
+                }
+            })();
+            // 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);
+            }
+            const generateUrl = gam.gam(adUrl);
+            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.externalAd = externalAd;

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>;